Tomcat 4.0 Manager Application

Introduction

Tomcat 4.0 ships with a web application (by default installed at context path /manager) that facilitates deploying, undeploying, and reloading (that is, forcing a reload of all class files without removing the application from service) of other 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 "deploy" command that prevents deploying, undeploying, and then redeploying an application from the same URL for a web application archive (WAR) file. To work around this, either redeploy the application from a different WAR file URL, or deploy 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 4.0.

• http://localhost:8080/manager/list - List the context paths of all web applications currently deployed on the virtual host in which this manager application is deployed.
• http://localhost:8080/manager/deploy?path=/xxx&war=yyy - Deploy 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/reload?path=/xxx - Cause the web application deployed at context path /xxx to reload all its associated Java classes, even if automatic reloading is disabled.
• http://localhost:8080/manager/undeploy?path=/xxx - Cause the web application deployed at context path /xxx to be gracefully shut down and undeployed. If a WAR file was automatically expanded into an unpacked directory when this application was deployed (or when the servlet container was first started), the expanded directory is deleted.

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

• 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. If the /list operation was requested, this line is followed by a list of the context paths of all deployed web applcations in this virtual host, one per line.

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.