Manager App HOW-TO

Table of Contents

Introduction

In many production environments, it is very useful to have the capability to deploy a new web application, or undeploy an existing one, without having to shut down and restart the entire container. In addition, you can request an existing application to reload itself, even if you have not declared it to be reloadable in the Tomcat server configuration file.

To support these capabilities, Tomcat includes a web application (installed by default on context path /manager) that supports the following functions:

  • Deploy a new web application from the uploaded contents of a WAR file.
  • Deploy a new web application, on a specified context path, from the server file system.
  • List the currently deployed web applications, as well as the sessions that are currently active for those web apps.
  • Reload an existing web application, to reflect changes in the contents of /WEB-INF/classes or /WEB-INF/lib.
  • List the OS and JVM property values.
  • List the available global JNDI resources, for use in deployment tools that are preparing <ResourceLink> elements nested in a <Context> deployment description.
  • Start a stopped application (thus making it available again).
  • Stop an existing application (so that it becomes unavailable), but do not undeploy it.
  • Undeploy a deployed web application and delete its document base directory (unless it was deployed from file system).

A default Tomcat installation includes the Manager. To add an instance of the Manager web application Context to a new host install the manager.xml context configuration file in the $CATALINA_BASE/conf/[enginename]/[hostname] folder. Here is an example:

<Context privileged="true" antiResourceLocking="false"
         docBase="${catalina.home}/webapps/manager">
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         allow="127\.0\.0\.1" />
</Context>

If you have Tomcat configured to support multiple virtual hosts (websites) you would need to configure a Manager for each.

There are three ways to use the Manager web application.

  • As an application with a user interface you use in your browser. Here is an example URL where you can replace localhost with your website host name: http://localhost:8080/manager/html .
  • A minimal version using HTTP requests only which is suitable for use by scripts setup by system administrators. 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. See Supported Manager Commands for more information.
  • A convenient set of task definitions for the Ant (version 1.4 or later) build tool. See Executing Manager Commands With Ant for more information.

Configuring Manager Application Access

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have insta