Tomcat Management: Setting up the Tomcat Manager Application
The Tomcat Manager is a useful application bundled into tomcat 5.5 and tomcat 6. Although it is deployed by default in the tomcat distribution that can be downloaded from the Apache Software Foundation, access to it is disabled by default primarily because the functionality that it provides can be dangerous.
This article will provide instructions on how to enable it, show some of the interesting things you can do with it, and how to secure it so that it can not be accessed by untrusted sources. Since Tomcat 6.0.18 is the latest version of tomcat at the time of this writing, I will be using Tomcat 6 for all examples in this article.
Enabling Access to the Tomcat Manager
As I previously mentioned, the Tomcat Manager application is deployed by default but access to it is not enabled to anyone in a standard Tomcat 6 distribution. If you are working with a newly downloaded binary installation of Tomcat 6, go to $CATALINA_HOME/conf ($CATALINA_HOME is a variable pointing to the tomcat base installation directory, i.e. /usr/local/tomcat) and make a backup of the file named tomcat-users.xml. Open tomcat-users.xml up in your favorite editor and remove everything. Then replace it with the following:
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
<role rolename="manager"/>
<user username="tomcat" password="tomcat" roles="manager"/>
</tomcat-users>
The values in "username" and "password" can (and should) be set to something else that would not easily be guessed but for this and subsequent articles, I'll be keeping it simple. That's all you need to do to enable user-level access to the Tomcat Manager application. Once tomcat is restarted, you're ready to use the Tomcat Manager.
Update: Tomcat 7 introduces new management roles. Please see my post "The New Manager Roles in Tomcat 7 Are Wonderful" for an introduction.
Tomcat Manager Usage Examples
Since I'm working with a tomcat 6 implementation installed on my local machine, all URLs will be accessed over localhost. The default path to load the Tomcat Manager application is http://localhost:8080/manager/html. You will be prompted to enter the username and password that was stored in tomcat-users.xml.
The default application page will appear. Please refer to the screenshot below for an example:
Click the "Server Status" link from the table near the top and you will get a display of the status of each connector, jvm memory stats for tomcat, and information regarding thread status.
Click "Complete Server Status" at the top and you'll get a whole bunch of useful statistics on the server and applications installed in the server.
Click on the "List Applications" link at the top left in order to get back to the main screen. Now we''ll stop and start some running applications. Scroll down to the "/docs" application. You'll see a few links to the right, "Start", which is presently disabled, "Stop", "Reload", amnd "Undeploy".
To demonstrate what happens when you click "Stop", go ahead and click the "Stop" link, then click on the docs application link. You'll get a 404.
Go back to the Tomcat Manager, click "Start" and the docs application is started again.
Scroll down to the bottom of the Tomcat Manager's main page and you have basic OS and JVM info.
As you can see, the type of information you get and the way you can start, stop, or undeploy applications is very useful for us but we certainly don't want untrusted access to get into the Tomcat Manager. The next section will deal with restricting access.
Securing Access to the Tomcat Manager
As I already mentioned, the first thing to do is come up with a stronger value for both 'username' and 'password' in tomcat-users.xml. If running on a UNIX platform, change permisiion on tomcat-users.xml to 600. This will allow access to the user tomcat is running as, (as well as root) but will disallow access to all other accounts that might be on that system.
If you front-end your tomcat app server with Apache, you should double-check that you do not have a JkMount /manager/* statement anywhere in your apache configuration files.
You can also enable the RemoteAddr or RemoteHostName valves to restrict access to the Tomcat Manager application. It's easiest to modify $CATALINA_HOME/conf/context.xml and add the following at the bottom of the file:
<Context path="/manager" privileged="true"
docBase="/usr/local/tomcat6/webapps/manager">
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.0\.0\.1"/>
</Context>
This will disallow access to all hosts except 127.0.0.1 (localhost). If your site uses static IP addressing for administration workstations, this isn't too big a deal but if you are using DHCP addressing, you may need to modify context.xml every time you want to use the Tomcat Manager, which can something of a pain if you have a large number of systems. However, you don't need to restart tomcat for context.xml changes to be made, which is why it's better to add them into this file then it is to add them to server.xml. (I also am reluctant to modify any application specific web.xml files, which is another option). context.xml changes are dynamic, you just need to wait a few moments for tomcat to re-check the file for changes.
Other Articles in my Tomcat Management Series Include:
Tomcat Management: Use Groovy to Interact with Tomcat Manager
Tomcat Management: Using the JMXProxy
Tomcat Management: Use the JMXProxy to Change Configuration
Tomcat Management: Jmx4Perl Makes it Easier
Tomcat Management: The New Manager Roles in Tomcat 7 Are Wonderful
