Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Deployment and Contexts

The Manager App and Parallel Deployment

Use Tomcat's Manager application to deploy, reload and undeploy apps from a browser or curl, secure its roles and access, and run several versions of an app in parallel with ##version names.

Copying files into webapps works on one machine. For scripted or remote deployments Tomcat ships a web application called Manager, with an HTML interface for people and a text/JMX interface for scripts. It can list, deploy, reload, stop, start and undeploy applications, and show server and session information. Combined with parallel deployment (several versions of the same application side by side), it supports zero-downtime upgrades.

This lesson covers the Manager roles, a safe configuration, the text commands and the parallel-deployment rules. The HTTP calls are read-only; the version-routing logic is implemented in a runnable stand-in.

Enabling the Manager

The Manager is in webapps/manager, but nobody can use it until you define a user with one of its roles in conf/tomcat-users.xml:

XML
<tomcat-users xmlns="http://tomcat.apache.org/xml" version="1.0">
  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <user username="deployer" password="{SHA-512}..." roles="manager-script"/>
  <user username="admin" password="{SHA-512}..." roles="manager-gui"/>
</tomcat-users>
Role Gives access to
manager-gui The HTML interface at /manager/html (needs a CSRF-protected browser session).
manager-script The plain-text API at /manager/text, for curl and build tools.
manager-jmx JMX proxy at /manager/jmxproxy.
manager-status Read-only status pages at /manager/status.

Passwords should be stored as digests, not plain text: create them with bin/digest.sh -a SHA-512 -h org.apache.catalina.realm.MessageDigestCredentialHandler yourSecret and set the matching CredentialHandler in the realm (realms and authentication).

By default the Manager only accepts connections from localhost. This is enforced by a RemoteCIDRValve in webapps/manager/META-INF/context.xml:

XML
<Context antiResourceLocking="false" privileged="true">
  <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor" sameSiteCookies="strict" />
  <Valve className="org.apache.catalina.valves.RemoteCIDRValve"
         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>

Widen allow only to your trusted management network (a VPN or bastion), never to the Internet. Better still, leave the Manager off public machines and deploy through your CI server that logs in locally.

A reachable Manager with a weak password lets an attacker upload a WAR, which is remote code execution. Treat manager-script like a root account: strong password, TLS, network restriction, or remove the application entirely.

Locking the Manager down

Strong credentials Hashed password, own role
RemoteCIDRValve Localhost or VPN only
TLS Never send passwords in clear text
Or remove it Delete manager, host-manager

Manager access equals code execution.

1 / 2

The text interface

Commands are plain HTTP requests (use PUT for uploads, GET otherwise). curl with a manager-script user:

Terminal
# List applications
curl -u deployer:secret http://localhost:8080/manager/text/list

# Deploy a WAR from the local disk of the server
curl -u deployer:secret "http://localhost:8080/manager/text/deploy?path=/shop&war=file:/srv/builds/shop.war&update=true"

# Upload a WAR from your machine
curl -u deployer:secret -T shop.war "http://localhost:8080/manager/text/deploy?path=/shop&update=true"

# Reload, stop, start, undeploy
curl -u deployer:secret "http://localhost:8080/manager/text/reload?path=/shop"
curl -u deployer:secret "http://localhost:8080/manager/text/stop?path=/shop"
curl -u deployer:secret "http://localhost:8080/manager/text/start?path=/shop"
curl -u deployer:secret "http://localhost:8080/manager/text/undeploy?path=/shop"

# Server information, sessions, resources
curl -u deployer:secret http://localhost:8080/manager/text/serverinfo
curl -u deployer:secret "http://localhost:8080/manager/text/sessions?path=/shop"
curl -u deployer:secret "http://localhost:8080/manager/text/resources?type=javax.sql.DataSource"

Responses start with OK - ... or FAIL - ..., which build scripts can test. Maven plug-ins and Ant tasks wrap these calls. Uploads are subject to the max-file-size and max-request-size limits in the Manager's own WEB-INF/web.xml (50 MB by default).

The stand-in below parses a typical list response and checks for failures the way a deployment script does.

Java Parsing Manager text responses (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Parallel deployment

Parallel deployment lets you keep several versions of one context path deployed. You name each version with ## in its WAR (or directory, or descriptor) name:

TEXT
webapps/shop##001.war
webapps/shop##002.war

Both are mapped to /shop. Tomcat applies these rules:

  • New sessions go to the highest version (compared as text, so use zero-padded numbers: 001, 002, 010).
  • Existing sessions stay on the version that created them, so users in the middle of a checkout are not switched to new code.
  • When the old version has no sessions left (they expired or ended) you undeploy it. The Manager's undeploy?path=/shop&version=001 removes one version, and Tomcat can even undeploy an old version automatically when its last session ends if you use the undeployOldVersions Host attribute (default false; the ContainerBackgroundProcessor does the check).
  • Requests without a session cookie also get the latest version.
flowchart LR
    U1["User with session on v001"] --> V1["shop##001"]
    U2["New visitor"] --> V2["shop##002 (latest)"]
    U3["User with session on v002"] --> V2

A new release is deployed beside the old one; traffic drains from old to new as sessions end.

Sessions must be distinguishable between versions; Tomcat uses the session id and the context version recorded with it. Applications sharing a database must be compatible with both versions at the same time, which is the real work in parallel deployment: schema changes must be backward compatible for a while.

Routing by version, in code

This runnable model implements the routing rule: no session or an unknown session chooses the latest version; a known session sticks to its version; and it reports when the old version can be removed.

Java Parallel deployment routing (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

A zero-downtime release script

A simple sequence using the text API (read-only):

Terminal
VERSION=$(date +%Y%m%d%H%M)
curl -u deployer:secret -T shop.war \
  "http://localhost:8080/manager/text/deploy?path=/shop&version=$VERSION"
# wait until old sessions drain, then:
curl -u deployer:secret "http://localhost:8080/manager/text/list" | grep shop
curl -u deployer:secret "http://localhost:8080/manager/text/undeploy?path=/shop&version=$OLD"

Using a timestamp as the version keeps ordering correct (the version string is compared lexically, so zero-padded or ISO-like values sort properly).

Common mistakes

  • Using manager-gui credentials in scripts; use manager-script.
  • Version names such as shop##9 and shop##10: text order puts 9 after 10; pad the numbers.
  • Opening the Manager to the whole network by editing allow to .*.
  • Parallel versions with an incompatible database schema.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Manager role should a build server use for curl-based deployments?

    manager-script gives access to the text interface under /manager/text. manager-gui is for the HTML interface.
  2. 2. How does Tomcat restrict the Manager to the local machine by default?

    The Manager's META-INF/context.xml has a RemoteCIDRValve allowing only loopback addresses.
  3. 3. With shop##001.war and shop##002.war deployed, where does a brand-new visitor go?

    New sessions are routed to the highest version; existing sessions stay on the version that created them.
  4. 4. Why pad version numbers like 001, 002, 010?

    Versions are ordered lexically, so unpadded numbers sort wrongly (9 after 10).

Summary

  • The Manager app offers an HTML GUI, a text API for scripts, JMX and status pages, protected by roles and a localhost-only valve.
  • Treat Manager access as code execution: strong hashed passwords, TLS, restricted networks, or remove it.
  • Text commands: list, deploy, reload, stop, start, undeploy, sessions, serverinfo.
  • Parallel deployment with name##version keeps old sessions on the old version and sends new ones to the latest.
  • Undeploy the old version when its sessions are gone and keep database changes backward compatible.

Next: Connectors and thread pools