Using The Tomcat Manager Webapp

All standard distributions of Apache Tomcat 4.1.x and following include a web application called Manager, a lightweight monitoring and administration tool with the ability to deploy, undeploy, and reload applications without shutting down the Container.  If you are using Tomcat in an enterprise environment, you may not end up spending too much time with it, but there are a few reasons why you should at least be aware of it and have a general grasp of its functionality.

 

First of all, as of Tomcat 6.x, which did away with the "admintool" that was included in version of Tomcat up to 5.5.x, Manager is the only "out-of-the-box" administrative tool included with Tomcat, so it's worth checking out.  

 

Though lightweight, there's actually a lot of functionality packed into this little application, and when used in conjunction with Apache Ant for task automation, it can really come in handy.  Later in this article, we'll get Manager up and running, and go over some situations where each of the three ways you can access its functionality could come in handy.

 

The other reason you should spend some time learning about Manager is that as an administrative program enabled in Tomcat by default, it represents something of a security concern.  

 

Don't worry - Apache hasn't built a back door into your server.  Although Manager starts automatically by default, it takes some additional configuration to allow anyone access to it.  Still, it pays to know about any administrative processes running on your server.  This article also goes over some best practices you can follow to make sure that Manager isn't used maliciously - whether you end up using it or not.

 

Sound good?  Great - we'll start by configuring Tomcat to allow us access to the Manager program, so that we can dig in and see what it can do.

 

 

Tomcat makes sure that not just anyone can access the Manager program by only allowing users with the role "manager" to utilize the program.  

 

To start experimenting with Manager, you'll need to either add the "manager" role to an existing user entry's list of roles, or create a new username and password specifically for accessing Manager.  This user entry can either be located in the default "tomcat-users.xml" file, located in "$CATALINA_BASE/conf/", or in your JDBC or JNDI Realm, depending on your server configuration.  

 

That's it!  If you've configured everything correctly, the users you specified should now have access to the Manager application.  Before we get  down to using Manager, though, let's take a few minutes to eliminate the potential security risks of enabling this program.

 

 

Making the Manager program secure is a matter of improving the security of its communication with the user, and restricting all unnecessary access points.

 

By default, logins to Manager occur in plain-text.  Clearly, this is less than desirable.  You can force Tomcat to send authentication data over SSL instead by adding an user data security constraint to Manager's "/WEB-INF/web.xml".  The code will look something like this:

 

<user-data-constraint>

<transport-guarantee>CONFIDENTIAL</transport-guarantee>

</user-data-constraint>

 

Next, you should restrict access to Manager to only the IPs that will need to access it.  You can do this by nesting a Remote Address Valve within Manager's Context element, found in the file "$CATALINA_HOME/webapps/host-manager/manager.xml".  Add the following entry, with the allowed IP address set to an appropriate value (or values, separated by commas):

 

<Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127.0.0.1"/>

 

Alternatively, if you prefer to control access by hostname rather than IP address, use a Remote Host Valve instead:

 

<Valve className="org.apache.catalina.valves.RemoteHostValve" allow="(*.).example.site.address.com"/>

 

Finally, you can rename and relocate the Manager application itself in order to protect your server from automated attacks that search for it in its default location.  Simply rename "manager.xml" to a name of your choice, create a new directory with the same name, and then update Manager's docBase attribute with the new name.

 

Although it is a lightweight application, you can access Manager's functionality in three different ways: 

 

Let's take a look at how each of these methods works, and some example scenarios in which you might use them.

 

URI commands are the most direct, and most powerful way you can use Tomcat.  They are also not particularly user-friendly, although their syntax is simple enough.  Here is a sample Manager URI request, with placeholders for the actual values:

 

http://{host}:{port}/manager/{command}?{parameters} 

 

The appropriate parameter to specify varies from command to command, but in general, either specifies a path, a WAR, a directory, or a file.  For example:

 

http://{host}:{port}/manager/deploy?path=/newapp&war=file:/path/to/app

 

This URI sends the "deploy" command to Manager, instructing it to deploy the application contained in the WAR file located at "path/to/app" in the Context "newapp".

 

Some manager commands do not have parameters.  For example:

 

http://{host}:{port}/manager/serverinfo

 

This command simply prints information about the JVM, OS, and currently running version of Tomcat.

 

For a comprehensive list of Manager commands, include relevant parameters and usage examples, visit the Apache Tomcat documentation site.

 

 

In order to allow integration of JMX functionalities into Manager URI scripts, Manager includes a small servlet called JMXProxy.  This servlet can receive JMX "qry" and "set" commands in the following format:  

 

http://{host}:{port}/manager/jmxproxy/?qry=YOURQUERY

 

or

 

http://{host}:{port}/manager/jmxproxy/?set=YOURCOMMAND

 

The actual commands are written in standard JMX syntax, using URL encoding for special characters.  If you aren't familiar with JMX (Java Management Extensions) syntax, you can read up on the specification itself at the project website, and find more information about its Tomcat-specific functions in the Tomcat source.

 

If you don't want to take the time to mess around with command syntax, but still want access to some of Manager's functionality, you might find the HTML console useful.  To call up the console, send the following Manager command:

 

http://{host}:{port}/manager/html

 

The console's functionality is fairly self-explanatory and easy to access.  The functionalities are available on individual tabs, and include a list of all the running applications, with the ability to expire their sessions, start, stop, reload, or undeploy, and a server status tab, which displays basic information about the Server, Connectors, OS, and JVM.  

 

Note that while the Manager can provide you with some simple server statistics, it is not all that useful as a diagnostic tool.

 

Apache ANT (Another Neat Tool) is a program that automates the execution of commands in other applications.  

 

Manager includes a set of Ant task definitions, including deploy, list, reload, resources, and others.  If you want to use these tasks, you can enable them in your application's build.xml file, using <taskdef> elements.  

 

In order to set up Ant to work with Manager, you'll have to have at least a basic understanding of Ant's functionality and syntax (and, of course, download the binary).  For more information about Apache ANT, visit the project site.