Tomcat Manager Application

Introduction

Tomcat ships with a web application (by default installed at context path /manager) that facilitates installing, starting, stopping, removing, listing information, and reloading (that is, forcing a reload of all class files without removing the application from service) of other web applications that are running in the same virtual host as the Manager application itself. This application is suited to scripted operation, because it can be executed from any client program that can issue HTTP requests. As such, it is complementary to other administrative applications that have a more human-oriented user interface.

WARNING - As of the Tomcat 4.0 milestone 2 release, there is a bug in the operation of the "install" command that prevents installing, removing, and then reinstalling an application from the same URL for a web application archive (WAR) file. To work around this, either reinstall the application from a different WAR file URL, or install from an unpacked directory (on the same server that Tomcat is running on).

Available Commands

The Manager application servlet responds to action requests that are encoded as the extra path information, and request parameters, of HTTP requests made to the manager application. The following command descriptions assume that you have installed the Manager application on context path /manager on your local host installation of Tomcat.

• http://localhost:8080/manager/install?path=/xxx&war=yyy - Install the web application whose WAR file (or directory containing the unpacked application) is present at URL yyy, and attach it to context path /xxx. See below for valid syntax options for the web applcation archive URl. If the URL of an actual WAR file is specified, the WAR will be automatically expanded into a directory underneath the application base for this virtual host.
• http://localhost:8080/manager/list - List the context paths of all currently installed web applications for this virtual host. Each context will be listed with the following format path:status:sessions. Where path is the context path. Status is either running or stopped. Sessions is the number of active Sessions.
• http://localhost:8080/manager/reload?path=/xxx - Cause the web application installed at context path /xxx to reload all its associated Java classes, even if automatic reloading is disabled.
• http://localhost:8080/manager/remove?path=/xxx - Cause the web application installed at context path /xxx to be gracefully shutdown and delete the web application directory and files.
• http://localhost:8080/manager/sessions?path=/xxx - List session information about the web application attached to context path /xxx for this virtual host.
• http://localhost:8080/manager/start?path=/xxx - Start the web application attached to context path /xxx for this virtual host.
• http://localhost:8080/manager/stop?path=/xxx - Stop the web application attached to context path /xxx for this virtual host.

Use path=/ for the ROOT context.

The syntax of the URL for a web application archive must conform to one of the following patterns to be successfully installed:

• file:/absolute/path/to/a/directory - You can specify 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.
• jar:file:/absolute/path/to/a/warfile.war!/ - You can specify a URL to a local web application archive file. The syntax must conform to the rules specified by the JarURLConnection class for a reference to an entire JAR file.
• jar:http://hostname:port/path/to/a/warfile.war!/ - You can specify a URL to a remote (HTTP-accessible) web application archive file. The syntax must conform to the rules specified by the JarURLConnection class for a reference to an entire JAR file.

For ease of script processing, the response generated by the Manager application servlet is rendered with content type text/plain. The first line of the response starts with "OK - " or "FAIL - " depending on whether the requested operation was successful or not, followed by a descriptive summary of the operation that took place, or the error that prevented the requested operation from taking place.

Security Considerations

Obviously, the Manager application can have significant impacts on a running instance of Tomcat. Therefore, it should not be (and is not) enabled by default. The following security considerations apply to this application.

• By default, the manager application is restricted by a security constraint that looks for users with an assigned role of manager. There are no such users in the default $CATALINA_HOME/conf/tomcat-users.xml file, so by default no one can execute any of the commands supported by the Manager application.
• The Manager application servlet will refuse to initialize itself if it is invoked by the invoker servlet (via a context relative path like /servlet/org.apache.catalina.servlets.ManagerServlet). You MUST install a <servlet-mapping> element in a web application deployment descriptor (or use the default web application shipped with Tomcat) to use this functionality.
• You SHOULD ensure that the Manager application is always protected by a security constraint so that user login is required. To facilitate scripting, the default login configuration for the Manager application uses HTTP BASIC authentication, because client programs can easily determine the content of the Authorization header they should send, once the assigned username and password are known.