Links User Guide Reference Apache Tomcat Development | Manager App HOW-TO| 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"
docBase="/usr/local/kinetic/tomcat7/server/webapps/manager">
</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/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 installed Tomcat.
It would be quite unsafe to ship Tomcat with default settings that allowed
anyone on the Internet to execute the Manager application on your server.
Therefore, the Manager application is shipped with the requirement that anyone
who attempts to use it must authenticate themselves, using a username and
password that have one of manager-** roles associated with
them (the role name depends on what functionality is required).
Further, there is no username in the default users file
($CATALINA_BASE/conf/tomcat-users.xml) that is assigned to those
roles. Therefore, access to the Manager application is completely disabled
by default.
You can find the role names in the web.xml file of the Manager
web application. The available roles are:
- manager-gui — Access to the HTML interface.
- manager-status — Access to the "Server Status"
page only.
- manager-script — Access to the tools-friendly
plain text interface that is described in this document,
and to the "Server Status" page.
- manager-jmx — Access to JMX proxy interface
and to the "Server Status" page.
The HTML interface is protected against CSRF (Cross-Site Request Forgery)
attacks, but the text and JMX interfaces cannot be protected. To maintain
the CSRF protection:
- Users with the manager-gui role should not be granted
the manager-script or manager-jmx
roles.
- If you use web browser to access the Manager application using
a user that has either manager-script or
manager-jmx roles (for example for testing
the plain text or JMX interfaces),
then all windows of the browser MUST be closed afterwards to terminate
the session.
Note that JMX proxy interface is effectively low-level root-like
administrative interface of Tomcat. One can do a lot, if he knows
what commands to call. You should be cautious when enabling the
manager-jmx role.
To enable access to the Manager web application, you must either create
a new username/password combination and associate one of the
manager-** roles with it, or add a
manager-** role
to some existing username/password combination.
As the majority of this document describes the commands of plain textual
interface, let the role name for further example to be
manager-script.
Exactly how the usernames/passwords are configured depends on which
Realm implementation you are using:
- MemoryRealm — This one is configured in the default
$CATALINA_BASE/conf/server.xml.
If you have not configured it differently, or replaced it with
a different Realm implementation, this realm
reads an XML-format file stored at
$CATALINA_BASE/conf/tomcat-users.xml, which can be
edited with any text editor. This file contains an XML
<user> for each individual user, which might
look something like this:
 | | | |
<user name="craigmcc" password="secret" roles="standard,manager-script" />
| | | | |
roles attribute for one or more existing users, and/or
create new users with that assigned role.
- JDBCRealm — Your user and role information is stored in
a database accessed via JDBC. Add the manager-script 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.
- JNDIRealm — Your user and role information is stored in
a directory server accessed via LDAP. Add the
manager-script 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-script.
In addition to the password restrictions the Manager web application
could be restricted by the remote IP address or host by adding
a RemoteAddrValve or RemoteHostValve.
See valves documentation
for details. Here is
an example of restricting access to the localhost by IP address:
<Context privileged="true">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
|
| 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/text/{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:
- path - The context path (including the leading slash)
of the web application you are dealing with. To select the ROOT web
application, specify "/". NOTE -
It is not possible to perform administrative commands on the
Manager application itself.
- version - The version of this web application as used by
the parallel deployment feature,
- war - URL of a web application archive (WAR) file,
pathname of a directory which contains the web application, or a
Context configuration ".xml" file. You can use URLs in any of the
following formats:
- 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.
- 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.
- 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.
- file:/absolute/path/to/a/context.xml - The
absolute path of a web application Context configuration ".xml"
file which contains the Context configuration element.
- directory - The directory name for the web
application context in the Host's application base directory.
- webapp.war - The name of a web application war file
located in the Host's application base directory.
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 will 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 Remotely |
| | | |
http://localhost:8080/manager/text/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 , using the directory
name or the war file name without the .war extension as the path. The
application can later be undeployed (and the corresponding application directory
removed) by use of the /undeploy command.
The .WAR file may include Tomcat specific deployment configuration, by
including a Context configuration XML file in
/META-INF/context.xml.
URL parameters include:
update: When set to true, any existing update will be
undeployed first. The default value is set to false.tag: Specifying a tag name, this allows associating the
deployed webapp with a tag or label. If the web application is undeployed,
it can be later redeployed when needed using only the tag.
NOTE - 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:
- Application already exists at path /foo
The context paths for all currently running web applications must be
unique. Therefore, you must undeploy the existing web
application using this context path, or choose a different context path
for the new one. The update parameter may be specified as
a parameter on the URL, with a value of true to avoid this
error. In that case, an undeploy will be performed on an existing
application before performing the deployment.
- Encountered exception
An exception was encountered trying to start the new web application.
Check the Tomcat 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.
|
|
|
