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-xxx 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
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"
- 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. It means that
users who are allowed access to the text and JMX interfaces have to be cautious
when accessing the Manager application with a web browser.
To maintain the CSRF protection:
- 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), you MUST close all windows
of the browser afterwards to terminate the session.
If you do not close the browser and visit other sites, you may become
victim of a CSRF attack.
- It is recommended to never grant
the manager-script or manager-jmx
roles to users that have the manager-gui role.
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
To enable access to the Manager web application, you must either create
a new username/password combination and associate one of the
manager-xxx roles with it, or add a
to some existing username/password combination.
As the majority of this document describes the using the text interface, this
example will use the role name manager-script.
Exactly how the usernames/passwords are configured depends on which
Realm implementation you are using:
- UserDatabaseRealm plus MemoryUserDatabase, or MemoryRealm
— The UserDatabaseRealm and MemoryUserDatabase are
configured in the default
Both MemoryUserDatabase and MemoryRealm read an
XML-format file by default 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:
which defines the username and password used by this individual to
log on, and the role names he or she is associated with. You can
add the manager-script role to the comma-delimited
<user username="craigmcc" password="secret" roles="standard,manager-script" />
roles attribute for one or more existing users, and/or
create new users with that assigned role.
- DataSourceRealm or 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
- 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, access to the Manager web
application can be restricted by the remote IP address or host
by adding a
See valves documentation
for details. Here is
an example of restricting access to the localhost by IP address: