Tomcat Manager App

 

Introduction

The Tomcat Manager App, found at http://domain/manager, is used to deploy, undeploy, and reload web applications, without having to shut down the server.

Functionality includes:

  1. Deploy a new web application using the contents of a WAR file.
  2. List active web apps.
  3. Reload existing web apps after changing /WEB-INF/classes or /WEB-INF/lib.
  4. Remove an installed web application.
  5. Start a stopped application.
  6. Stop an existing application, but do not undeploy it.
  7. Undeploy a web application .

Since Manager is itself a web application, it interacts with you using standard HTTP requests and responses. However, it's "user interface" is minimal, because it is intended to be accessed from scripts set up by the system administrator. For this reason, commands are given as part of the request URI, and responses are in the form of simple text that can be easily parsed and processed.

In addition to executing Manager commands directly via HTTP, Tomcat 4 includes a set of task definitions for the Ant build tool.

 

Access

To access the Manager App use a username and password associated that has "manager" role privileges. Where this is set depends on which Realm implementation you are using:

To enable access to the Manager web application, either create a new username/password combination and associate the role name manager with it, or add the manager role to some existing username/password combination. Exactly where this is done depends on which Realm

top>MemoryRealm Edit $TOMCAT_HOME/conf/tomcat-users.xml: 

<user name="michaelp" 
      password="secret" 
      roles="standard,manager" />
top>JDBCRealm Your user and role information is stored in a database accessed via JDBC. Add the manager role to one or more existing users, and/or create one or more new users with this role assigned, following the standard procedures for your environment.
top>JNDIRealm Your user and role information is stored in a directory server accessed via LDAP. Add the manager role to one or more existing users, and/or create one or more new users with this role assigned, following the standard procedures for your environment.

The first time you attempt to issue one of the Manager commands described in the next section, you will be challenged to log on using BASIC authentication. The username and password you enter do not matter, as long as they identify a valid user in the users database who possesses the role manager.

This is set in $CATALINA_HOME/conf/tomcat-users.xml

 

Supported Manager Commands

All commands that the Manager application knows how to process are specified in a single request URI like this:

http://{host}:{port}/manager/{command}?{parameters}

where {host} and {port} represent the hostname and port number on which Tomcat is running, {command} represents the Manager command you wish to execute, and {parameters} represents the query parameters that are specific to that command. In the illustrations below, customize the host and port appropriately for your installation.

Most commands accept one or more of the following query parameters:

  1. path - The context path (including the leading slash) of the web application you are dealing with. To select the ROOT web application, specify a zero-length string. NOTE - It is not possible to perform administrative commands on the Manager application itself.

  2. war - URL of a web application archive (WAR) file, or pathname of a directory, that contains the web application. You can use URLs in any of the following formats:

    1. file:/absolute/path/to/a/directory - The absolute path of a directory that contains the unpacked version of a web application. This directory will be attached to the context path you specify without any changes.

    2. file:/absolute/path/to/a/webapp.war - The absolute path of a web application archive (WAR) file. This is valid only for the /deploy command, and is the only acceptable format to that command.

    3. jar:file:/absolute/path/to/a/warfile.war!/ - The URL to a local web application archive (WAR) file. You can use any syntax that is valid for the JarURLConnection class for reference to an entire JAR file.

    4. jar:http://hostname:port/path/to/a/warfile.war!/ - You can also deploy web applications from a remote JAR file. You can use any syntax that is valid for the JarURLConnection class for reference to an entire JAR file.

Each command will return a response in text/plain format (i.e. plain ASCII with no HTML markup), making it easy for both humans and programs to read). The first line of the response wil begin with either OK or FAIL, indicating whether the requested command was successful or not. In the case of failure, the rest of the first line will contain a description of the problem that was encountered. Some commands include additional lines of information as described below.

Internationalization Note - The Manager application looks up its message strings in resource bundles, so it is possible that the strings have been translated for your platform. The examples below show the English version of the messages.

 

Deploy A New Application

http://localhost:8080/manager/deploy?path=/foo

Upload the web application archive (WAR) file that is specified as the request data in this HTTP PUT request, install it into the appBase directory of our corresponding virtual host, and start it on the context path specified by the path request parameter. The application can later be undeployed (and the corresponding application directory removed) by use of the /undeploy.

NOTE - Since this command requires an HTTP PUT request, it is usable only from tools (such as the custom Ant tasks described below). To install a new web application without copying, consider the /install command described below. This command is the logical opposite of the /undeploy command.

If installation and startup is successful, you will receive a response like this:

OK - Deployed application at context path /foo

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Application already exists at path /foo

    The context paths for all currently running web applications must be unique. Therefore, either remove or undeploy the existing web application using this context path, or choose a different context path for the new one.

  2. Encountered exception

    An exception was encountered trying to start the new web application. Check the Tomcat 4 logs for the details, but likely explanations include problems parsing your /WEB-INF/web.xml file, or missing classes encountered when initializing application event listeners and filters.

  3. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  4. No context path was specified
    The path parameter is required.

 

Install A New Application

http://localhost:8080/manager/install?path=/foo&war=file:/path/to/foo

http://localhost:8080/manager/install?path=/bar&war=jar:file:/path/to/bar.war!/

Install and start a new web application, attached to the specified context path (which must not be in use by any other web application). The war parameter specifies a URL (including the file: scheme) for either a directory or a web application archive (WAR) file. The supported syntax for a URL referring to a WAR file is described on the Javadocs page for the java.net.JarURLConnection class. Use only URLs that refer to the entire WAR file. This command is the logical opposite of the /remove command.

If installation and startup is successful, you will receive a response like this:

OK - Installed application at context path /foo

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Application already exists at path /foo

    The context paths for all currently running web applications must be unique. Therefore, either remove or undeploy the existing web application using this context path, or choose a different context path for the new one.

  2. Document base does not exist or is not a readable directory

    The URL specified by the war parameter must identify a directory on this server that contains the "unpacked" version of a web application, or the absolute URL of a web application archive (WAR) file that contains this application. Correct the value specified by the war parameter.

  3. Encountered exception

    An exception was encountered trying to start the new web application. Check the Tomcat 4 logs for the details, but likely explanations include problems parsing your /WEB-INF/web.xml file, or missing classes encountered when initializing application event listeners and filters.

  4. Invalid application URL was specified

    The URL for the directory or web application that you specified was not valid. Such URLs must start with file:, and URLs for a WAR file must end in ".war".

  5. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  6. No context path was specified
    The path parameter is required.

 

List Currently Deployed and Installed Applications

http://localhost:8080/manager/list

List the context paths, current status (running or stopped), and number of active sessions for all currently deployed and installed web applications. A typical response immediately after starting Tomcat might look like this:

OK - Listed applications for virtual host localhost
/webdav:running:0
/examples:running:0
/manager:running:0
/:running:0

 

Reload An Existing Application

http://localhost:8080/manager/reload?path=/examples

Signal an existing application to shut itself down and reload. This can be useful when you've recompiled classes on an application that is not configured with the reloadable="true" attribute in its <Context> entry in $CATALINA_HOME/conf/server.xml, or when you've made other changes (such as to conf/web.xml) that are not automatically recognized by Tomcat.

If this command succeeds, you will see a response like this:

OK - Reloaded application at context path /examples

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Encountered exception

    An exception was encountered trying to restart the web application. Check the Tomcat 4 logs for the details.

  2. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  3. No context exists for path /foo

    There is no deployed or installed application on the context path that you specified.

  4. No context path was specified
    The path parameter is required.

 

Remove an Existing Application

http://localhost:8080/manager/remove?path=/examples

Signal an existing application to gracefully shut itself down, and then remove it from Tomcat (which also makes this context path available for reuse later). This command is the logical opposite of the /install command.

If this command succeeds, you will see a response like this:

OK - Removed application at context path /examples

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Encountered exception

    An exception was encountered trying to remove the web application. Check the Tomcat 4 logs for the details.

  2. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  3. No context exists for path /foo

    There is no deployed or installed application on the context path that you specified.

  4. No context path was specified
    The path parameter is required.

 

Session Statistics

http://localhost:8080/manager/sessions?path=/examples

Display the default session timeout for a web application, and the number of currently active sessions that fall within ten-minute ranges of their actual timeout times. For example, after restarting Tomcat and then executing one of the JSP samples in the /examples web app, you might get something like this:

OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
30 - <40 minutes:1 sessions

 

Start an Existing Application

http://localhost:8080/manager/start?path=/examples

Signal a stopped application to restart, and make itself available again. Stopping and starting is useful, for example, if the database required by your application becomes temporarily unavailable. It is usually better to stop the web application that relies on this database, rather than letting users continuously encounter database exceptions.

If this command succeeds, you will see a response like this:

OK - Started application at context path /examples

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Encountered exception

    An exception was encountered trying to start the web application. Check the Tomcat 4 logs for the details.

  2. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  3. No context exists for path /foo

    There is no deployed or installed application on the context path that you specified.

  4. No context path was specified
    The path parameter is required.

 

Stop an Existing Application

http://localhost:8080/manager/stop?path=/examples

Signal an existing application to make itself unavailable, but leave it deployed or installed. Any request that comes in while an application is stopped will see an HTTP error 404, and this application will show as "stopped" on a list applications command.

If this command succeeds, you will see a response like this:

OK - Stopped application at context path /examples

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Encountered exception

    An exception was encountered trying to stop the web application. Check the Tomcat 4 logs for the details.

  2. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  3. No context exists for path /foo

    There is no deployed or installed application on the context path that you specified.

  4. No context path was specified
    The path parameter is required.

 

Undeploy an Existing Application

http://localhost:8080/manager/undeploy?path=/examples

WARNING - This command will delete the contents of the web application directory if it exists within the appBase directory (typically "webapps") for this virtual host . If you simply want to take an application out of service, you should use the /remove command instead.

Signal an existing application to gracefully shut itself down, and remove it from Tomcat (which also makes this context path available for reuse later). In addition, the document root directory is removed, if it exists in the appBase directory (typically "webapps") for this virtual host. This command is the logical opposite of the /deploy command.

If this command succeeds, you will see a response like this:

OK - Undeployed application at context path /examples

Otherwise, the response will start with FAIL and include an error message. Possible causes for problems include:

  1. Encountered exception

    An exception was encountered trying to undeploy the web application. Check the Tomcat 4 logs for the details.

  2. Invalid context path was specified

    The context path must start with a slash character, unless you are referencing the ROOT web application -- in which case the context path must be a zero-length string.

  3. No context exists for path /foo

    There is no deployed or installed application on the context path that you specified.

  4. No context path was specified
    The path parameter is required.

 

Executing Manager Commands With Ant

In addition to the ability to execute Manager commands via HTTP requests, as documented above, Tomcat 4 includes a convenient set of Task definitions for the Ant (version 1.4 or later) build tool. In order to use these commands, perform the following setup operations:

  1. Download the binary distribution of Ant from http://jakarta.apache.org/ant. You must use version 1.4 or later.

  2. Install the Ant distribution in a convenient directory (called ANT_HOME in the remainder of these instructions).

  3. Copy the file server/lib/catalina-ant.jar from your Tomcat 4 installation into Ant's library directory ($ANT_HOME/lib).

  4. Add the $ANT_HOME/bin directory to your PATH environment variable.

  5. Configure at least one username/password combination in your Tomcat user database that includes the manager role.

To use custom tasks within Ant, declare them first with a <taskdef> element. Therefore, your build.xml file might look something like this:

<project name="My Application" default="compile" basedir=".">

  <-- Configure the directory into which the web application is built -->
  <property name="build"    value="${basedir}/build"/>

  <-- Configure the context path for this application -->
  <property name="path"     value="/myapp"/>

  <-- Configure properties to access the Manager application -->
  <property name="url"      value="http://localhost:8080/manager"/>
  <property name="username" value="myusername"/>
  <property name="password" value="mypassword"/>

  <-- Configure the custom Ant tasks for the Manager application -->
  <taskdef name="deploy"   classname="org.apache.catalina.ant.DeployTask"/>
  <taskdef name="install"  classname="org.apache.catalina.ant.InstallTask"/>
  <taskdef name="list"     classname="org.apache.catalina.ant.ListTask"/>
  <taskdef name="reload"   classname="org.apache.catalina.ant.ReloadTask"/>
  <taskdef name="remove"   classname="org.apache.catalina.ant.RemoveTask"/>
  <taskdef name="start"    classname="org.apache.catalina.ant.StartTask"/>
  <taskdef name="stop"     classname="org.apache.catalina.ant.StopTask"/>
  <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/>

  <-- Executable Targets -->
  <target name="compile" description="Compile web application">
    ... construct web application in ${build} subdirectory ...
  </target>

  <target name="install" description="Install web application"
          depends="compile">
    <install url="${url}" username="${username}" password="${password}"
            path="${path}" war="file://${build}"/>
  </target>

  <target name="reload" description="Reload web application"
          depends="compile">
    <reload  url="${url}" username="${username}" password="${password}"
            path="${path}"/>
  </target>

  <target name="remove" description="Remove web application">
    <remove url="${url}" username="${username}" password="${password}"
            path="${path}"/>
  </target>

</project>

Now, you can execute commands like ant install to install th applcation to a running instance of Tomcat, or ant reload to tell Tomcat to reload it. Note also that most of the interesting values in this build.xml file are defined as replaceable properties, so you can override their values from the command line. For example, you might consider it a security risk to include the real manager password in your build.xml file's source code. To avoid this, omit the password property, and specify it from the command line:

  ant -Dpassword=secret deploy