Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apache/tomcat/llms.txt

Use this file to discover all available pages before exploring further.

The Manager application ships with every Tomcat installation and provides both a browser-based HTML interface and a machine-readable text HTTP API for managing deployed web applications. It allows operators to deploy new applications, stop or reload running ones, inspect session counts, and collect diagnostics — all without restarting Tomcat. The Manager itself is deployed as a privileged web application at /manager and relies on Tomcat’s security framework to restrict access.

​
Enabling the Manager

The Manager application is included in the default Tomcat distribution under webapps/manager, but it ships with no authorized users. You must add user entries to conf/tomcat-users.xml before you can log in. There are four distinct Manager roles, each granting access to a different interface:
RoleAccess Granted
manager-guiHTML browser interface at /manager/html
manager-scriptText (machine-readable) HTTP API at /manager/text
manager-jmxJMX proxy at /manager/jmxproxy
manager-statusServer status pages at /manager/status
Add role and user entries to conf/tomcat-users.xml: 
<tomcat-users>
  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <role rolename="manager-status"/>

  <!-- Browser-only operator -->
  <user username="admin"
        password="str0ngP@ssw0rd!"
        roles="manager-gui,manager-status"/>

  <!-- CI/CD automation account (no GUI needed) -->
  <user username="deploy-bot"
        password="c1Dep10yS3cr3t"
        roles="manager-script"/>
</tomcat-users>
The Manager application is a high-value attack target. Use strong, unique passwords for every Manager account. Never use the default tomcat/tomcat credentials in any environment. Prefer manager-script accounts for automation and limit manager-gui access to named individuals. Rotate credentials regularly and audit conf/tomcat-users.xml as part of your security review process.

​
Remote Access Configuration

By default, Tomcat restricts Manager access to connections originating from localhost (127.0.0.1 and ::1). This is enforced by a RemoteAddrValve in the context descriptor at conf/Catalina/localhost/manager.xml. Default conf/Catalina/localhost/manager.xml: 
<Context antiResourceLocking="false" privileged="true">
  <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"
                   sameSiteCookies="strict" />
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1"/>
  <Manager sessionAttributeValueClassNameFilter="java\.lang\.
(?:Boolean|Integer|Long|Number|String)|org\.apache\.catalina\.filters\.
CsrfPreventionFilter\$LruCache(?:\$1)?|java\.util\.(?:Linked)?HashMap"/>
</Context>
To allow access from an internal network (e.g., 192.168.1.0/24), extend the allow regex: 
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
       allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1|192\.168\.1\.\d+"/>
For access from any address on a secured network, replace the allow attribute with a permissive pattern — but only do this behind a firewall or VPN: 
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
       allow=".*"/>

​
HTML Manager Interface

Navigate to http://localhost:8080/manager/html in a browser and authenticate with a manager-gui account. The HTML interface provides:
  • A table of all deployed applications showing context path, display name, running state, and active session count.
  • Per-application action buttons: Start, Stop, Reload, Undeploy, and Expire Sessions.
  • A deploy panel for uploading a WAR file from your local machine or specifying a server-side path.
  • Links to the Server Status page and the application session detail views.
The HTML interface is served by HTMLManagerServlet, which extends ManagerServlet and renders the same underlying operations as formatted HTML rather than plain text responses.

​
Text API Commands

The text API is available at /manager/text/ and is designed for scripted access. Every response begins with OK - on success or FAIL - on error, making it easy to parse from shell scripts or CI/CD pipelines.

​
Endpoint Reference

EndpointMethodDescription
/manager/text/listGETList all deployed applications with path, status, and session count
/manager/text/deploy?path=&war=GETDeploy a WAR from a file: or jar: URL on the server filesystem
/manager/text/deploy?path=PUTUpload and deploy a WAR from the request body
/manager/text/undeploy?path=GETUndeploy the application at the given path and remove it from appBase
/manager/text/start?path=GETStart a previously stopped application
/manager/text/stop?path=GETStop a running application (keeps it registered)
/manager/text/reload?path=GETReload the application (stop + start the context)
/manager/text/sessions?path=GETDeprecated. Use /expire instead. Displays session idle time distribution
/manager/text/expire?path=&idle=GETExpire sessions idle for more than idle minutes
/manager/text/findleaksGETFind applications that triggered memory leaks on previous reload/undeploy
/manager/text/serverinfoGETDisplay Tomcat version, OS, JVM, and hostname
/manager/text/vminfoGETDetailed JVM memory, GC, and thread pool information
/manager/text/threaddumpGETFull JVM thread dump
/manager/text/saveGETSave current server configuration to server.xml
/manager/text/save?path=GETSave a context’s configuration to conf/Catalina/<host>/<app>.xml

​
curl Examples

List all deployed applications: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  http://localhost:8080/manager/text/list
Example output: 
OK - Listed applications for virtual host [localhost]
/:running:0:ROOT
/manager:running:1:manager
/myapp:running:42:myapp
/oldapp:stopped:0:oldapp
Deploy a WAR from the server filesystem: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  "http://localhost:8080/manager/text/deploy?path=/myapp&war=file:/opt/releases/myapp-2.1.war"
Upload a WAR from your local machine (PUT): 
curl -u deploy-bot:c1Dep10yS3cr3t \
  -T target/myapp.war \
  "http://localhost:8080/manager/text/deploy?path=/myapp"
Undeploy an application: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  "http://localhost:8080/manager/text/undeploy?path=/myapp"
Reload a running application: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  "http://localhost:8080/manager/text/reload?path=/myapp"
Expire sessions idle for more than 30 minutes: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  "http://localhost:8080/manager/text/expire?path=/myapp&idle=30"
Find memory-leaking applications: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  "http://localhost:8080/manager/text/findleaks"
Capture a thread dump for troubleshooting: 
curl -u deploy-bot:c1Dep10yS3cr3t \
  "http://localhost:8080/manager/text/threaddump"
Use path=/ (not path=) to target the ROOT context. For example: curl ".../manager/text/stop?path=/".

​
Status App

The Status application at /manager/status (also accessible as /manager/status/all for extended output) provides a real-time server health overview. It requires only the manager-status role, making it safe to grant to monitoring systems. The status page displays:

JVM Memory

Heap usage, non-heap, and individual memory pool statistics from the running JVM.

Thread Pools

Current thread count, maximum threads, and queue depth for each Connector’s executor.

Connector Statistics

Request count, error count, bytes sent/received, and processing time per Connector.

JVM Version Info

Tomcat version, Java version, OS name/version/architecture, and hostname.
The status page is available in both HTML format (browser) and XML format for machine consumption: 
# XML format for monitoring tools
curl -u admin:str0ngP@ssw0rd! \
  "http://localhost:8080/manager/status/all?XML=true"

Build docs developers (and LLMs) love

Get started for freeTalk to us