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 ofmanager-** 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 ormanager-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.

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” />

 

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 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 themanager-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. 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>