Using the Tomcat Administration Tool

Tomcat also has a Web-based administration tool that you can use to administer the server and individual Web applications. In other words, it allows you to edit server.xml and Web application context settings remotely, as well as other server configuration files. If you’re using Tomcat 5.5, you must download the admin tool separately from the main server. This is an indirect indication of the status of the admin tool, meaning that, as it stands, the admin tool isn’t as essential or as useful as it may seem on the surface. The following description, the discussion of realms in Chapter 12 will cover the drawbacks of the admin tool.

Note 

The source distribution of Tomcat 5.5 includes the admin application, which means you’ll install it if you build Tomcat 5.5 from source.

Before you run the admin application, you must add an admin role and assign it to a user in tomcat-users.xml, or whichever authentication mechanism you’re using. As with the manager application’s Web interface, the admin tool is a Web application running on the server. You can access it via the following URL:

 http://localhost:8080/admin 

Once you log in via the form, you’ll see the admin Web interface similar to that shown in Figure 6-11. Tomcat 5.0.x users will see a debug-level setting as well.

Figure 6-11: The admin application Web interface

You can configure the admin application in the CATALINA_HOME/conf/[Engine_name]/[Host_name]/admin.xml file. Listing 6-9 shows the contents.

Listing 6-9: The admin Application’s Context XML File

 <!-- Tomcat 5.0.x -->  <Context path="/admin" docBase="${catalina.home}/server/webapps/admin"          debug="0" privileged="true">    <!-- Uncomment this Valve to limit access to the Admin app to localhost     for obvious security reasons. Allow may be a comma-separated list of     hosts (or even regular expressions).    <Valve className="org.apache.catalina.valves.RemoteAddrValve"      allow="127.0.0.1"/>    -->    <Logger className="org.apache.catalina.logger.FileLogger"               prefix="localhost_admin_log." suffix=".txt"            timestamp="true"/>  </Context>  <!-- Tomcat 5.5 -->  <Context docBase="${catalina.home}/server/webapps/admin" privileged="true"           antiResourceLocking="false" antiJARLocking="false">    <!-- Uncomment this Valve to limit access to the Admin app to localhost     for obvious security reasons. Allow may be a comma-separated list of     hosts (or even regular expressions).    <Valve className="org.apache.catalina.valves.RemoteAddrValve"      allow="127.0.0.1"/>    -->  </Context> 

The other configuration file for the admin application is the deployment descriptor (CATALINA_HOME/server/webapps/admin/WEB-INF/web.xml). As with the manager application, you can alter the security constraints and authentication settings for the admin application here. In this case, the admin application uses form-based authentication to protect the admin pages. If you’d rather it use something else, change the setting appropriately.

Using the Administration Tool

Each node in the left pane represents a setting you can edit. The Service node corresponds to the <Service> element in server.xml, and its subnodes are the <Service> element’s subelements. If you expand this node, you’ll see each subelement, which you can then alter via commands in the right pane. There are few settings you can’t alter, but changing the document base of a Web application is one of them. If you want to change the application’s base directory, you’ll have to undeploy it and redeploy it with new settings.

The next set of nodes after the Service node, under Resources, contains global settings for server.xml. Again, few settings can’t be changed.

The final set of nodes corresponds to the settings in tomcat-users.xml. You can add users, roles, and groups here.

Each setting screen has a Save button and a Reset button. Clicking Save will commit any changes to the admin application’s memory but won’t write them to server.xml. Therefore, you can make all your changes before writing to disk. This is important because when the admin application writes the changes to server.xml, it restarts Tomcat to enable the changes to take effect. The restart will be graceful, but some users may experience problems with the restart, least of all you because you’ll be logged out of the admin application.

To make the changes permanent, click the Commit Changes button at the top of the admin application screen. This makes the write to server.xml. However, the admin application creates a new server.xml file based on the settings it’s holding in memory. It doesn’t delete the old server.xml, but rather it renames it as follows:

 server.xml.yyyy-MM-dd.hh-mm-ss 

The new server.xml file won’t have any comments in it and as such may be significantly smaller and less comprehensible to someone not familiar with your setup. It may be a good idea to copy the comments from the old file into the new one.

The exception to the previous discussion is editing users in the default user database. Clicking the Save button on a user’s screen will commit the changes to tomcat-users.xml straightaway.

As you can see, the admin tool has some drawbacks, the least of which are still to be discussed in the security chapter. Careful consideration should go into whether you need the admin tool. Remote access is its biggest advantage.