Apache Tomcat

Apache Tomcat is an open source J2EE Web container software that has been developed by ASF (Apache Software Foundation), the creator of the most popular HTTP server software. It is also the reference implementation of Java Servlet and JavaServer Pages specifications. Tomcat 4.1.18, the latest stable release at the time of this writing, implements Servlet 2.3 and JavaServer Pages 1.2 specifications. Work is underway on Tomcat 5 to support Servlet 2.4 and JavaServer Pages 2.0 specifications. Because the changes offered by these new versions in the area of security are minimal, we focus our discussion around Tomcat 4.1.18 and point out the new features wherever appropriate. Subsequent releases in the 4.x series, or even the 5.x series, are not likely to be very different from this.

You should keep in mind that this discussion is geared toward security features of Tomcat. Refer to the online documentation available from Tomcat's home page http://jakarta.apache.org/tomcat for detailed information on other features of Tomcat.

Installing and Running Tomcat

Download the zip file containing the runtime binaries by following the download instructions available at the Tomcat homepage. The name of the distribution file usually indicates the Tomcat and J2SE SDK version. For example, the Tomcat 4.1.18 distribution file for J2SE SDK v1.4.x is jakarta-tomcat-4.1.18-LE-jdk14.zip.

Choose a directory where you want to install Tomcat (it is c:apache in my test setup) and unzip the distribution file:

C:apache>jar xvf jakarta-tomcat-4.1.18-LE-jdk14.zip
						

This creates the Tomcat home directory jakarta-tomcat-4.1.18-LE-jdk14 and places the installation files and directories there. To run Tomcat, go to the Tomcat home directory and issue binstartup command:

C:apachejakarta-tomcat-4.1.18-LE-jdk14>binstartup
						

This creates a separate command window and you can run Tomcat there. You should see a number of INFO messages in this window, indicating that Tomcat is running fine and is listening for HTTP requests on port 8080.

It is also possible to run Tomcat as a Windows service (on Windows machines) or a daemon program (on UNIX or Linux machines). This way, the Tomcat process is not associated with any command window and keeps running even when all windows are closed and no one is logged on. In fact, this is the recommended way for production environments to function, for an accidental close of a window might kill the process and disrupt many applications. However, during development, it is convenient to start and stop Tomcat manually and that is what we do for our illustrations.

After you have started Tomcat, point your browser to the URL http://localhost:8080. If the browser is running on a different machine, replace localhost with the name or IP address of that machine. This should bring up the default home page as shown in Figure 9-1, congratulating you on a successful setup of Tomcat.

If you want, you can stop Tomcat by issuing the command binshutdown from its home directory. For the exploration steps of the next section, keep it running.

Exploring Tomcat Setup

The default home page is a good place to start learning about Tomcat. Read the text displayed in the browser. It informs you about the location of the file that generates the default home page, suggests that you read the Tomcat documentation, and lists login requirements for two bundled Web applications—Tomcat Administration and Tomcat Manager. Access of Tomcat Administration is limited to users with "admin" role and that of Tomcat Manager to users with "manager" role. We talk about role-based access control for Web applications later in this chapter.

To explore these bundled Web applications, you need to create the roles "admin" and "manager" and a user with these roles. Do this by modifying the default user file tomcat-users.xml located in the conf subdirectory of Tomcat home:

// file: conf	omcat-users.xml
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="admin"/>
  <role rolename="manager"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="role1" password="tomcat" roles="role1"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="jstkuser" password="changeit" roles="admin, manager"/>
</tomcat-users>

Can you spot the name and password of the newly added user? The username is jstkuser and the password is our favorite changeit. It goes without saying that you should select something better as a password (i.e., less intuitive) for your production environment. In fact, managing users with such a text file with clear-text passwords is not recommended for a production environment for multiple reasons. Anyone with read access to this file has access to all the usernames and their passwords. Also, as the number of users and roles grows, the management of the text file becomes difficult. Fortunately, Tomcat works with a relational database or an LDAP (Lightweight Data Access Protocol) server or any other kind of server to access the user and role information. Please refer to the online documentation for details.

Why can't Tomcat distribution have a default user with "admin" and "manager" roles? That would certainly make it faster to explore administration and manager applications for new users. However, this would achieve ease of use at the cost of security. What if an administrator forgets to change the default? Anyone would be able to run these applications with default username and password and completely compromise the security of the site. In fact, a lot of security breaches have been traced to the insecure default settings. The overhead of initial setup is a small price to pay for better overall security.

There is still one problem. As we mentioned earlier, the password is stored in clear-text and can be read by anyone with read access to the users file conf omcat-users.xml. This is certainly not desirable for high security sites. We learn later in this chapter about how to get rid of clear text passwords.

Tomcat reads the users file only during startup—meaning you must stop and restart it after making any modifications to this file. Now that we have modified this file, stop Tomcat and then start it. We are now ready to launch Tomcat Administration and Tomcat Manager applications. Let us start with Tomcat Administration by clicking the appropriate link from the Tomcat home page. This takes us to a login page. Supply jstkuser as username, changeit as password and click the Login button. This should take you to the main page of the Tomcat Administration Tool. A screen shot of this page is shown in Figure 9-2.

Explore the entities in the left pane. Some of these are higher-level entities consisting of subentities and can be expanded or collapsed. Clicking on an entity in this pane displays the entity properties in the right pane and lists the ---- Available Actions ---- in a drop-down box. For example, clicking on Roles displays a list of currently active roles and allows creation of new roles and removal of the existing ones. The same is true with the entity Users. You notice that the roles and users displayed here are the same ones that we saw in the conf omcat-users.xml file. This is no coincidence. As per the default configuration, the Administration Tool operates on the user account information stored in this file. As expected, these actions will eventually update file conf omcat-users.xml.

You can learn about other entities, such as Tomcat Server and Service and their subentities by reading the online documentation. Most of them have counterparts in the Tomcat configuration file confserver.xml. The information in this file captures the configuration of Tomcat installation and the running instance. You can change this configuration either through the Administration Tool or by directly editing the server.xml file.

Among all the elements, the ones to pay particular attention to are: Service, Connector, Realm, Host, and Context. As the name suggests, a connector is a component responsible for accepting connections. Recall that Tomcat listens for browser requests on port 8080. Do you see a Connector for this port? What are its properties and which ones can you modify?

Logout from Administration Tool by clicking on Logout button, located at the right top of the screen. We are finished exploring this tool.

Another tool of interest is Tomcat Manager. Invoke this tool from the default Tomcat homepage. This also requires login, but the login panel decidedly appears different from the login page of the Administration Tool as shown in Figure 9-3. The login page of the Administration Tool is created by the application itself to carry out what is known as Form Based Authentication. The login panel shown by the browser for the Tomcat Manager has resulted from what is known as HTTP Basic Authentication. We talk more about different authentication mechanisms later in this chapter.

The Tomcat Manager allows you to view the currently deployed Web applications, go to start page of any of the deployed Web applications, deploy new Web applications, and stop or reload the existing ones. As we learned earlier, some of these activities (especially deployment) can also be done by simply moving files and modifying appropriate configuration files under the Tomcat home directory.

A noteworthy aspect of the login to the Tomcat Manager is that you do not have a Logout button and there is no way to log in as a different user, other than starting a separate instance of the browser. This has to do with the way HTTP Basic Authentication works.

Let us shift our attention to the server side setup for Tomcat. We have already come across two files in the conf subdirectory:

server.xml— contains configuration information about the Tomcat. The Realm element within the Engine element of this file links the user database to file conf omcat-users.xml.

tomcat-users.xml— contains information about current users, roles and association of users with roles.

Other files of the subdirectory conf that are of interest to us are:

web.xml— contains Web application descriptor elements common to all the Web applications. The elements in this file are merged with the elements of the Web application-specific deployment descriptor to form the complete deployment descriptor.

catalina.policy— has the Java security policy entries for the Tomcat software.

You are encouraged to take a look at these files.

Besides these files, the directory webapps is of special interest. As we have already seen, a WAR file or a subdirectory tree conforming to Java Web application structure moved into this directory gets deployed as a Web application. Another way of deploying a Web application is to add a Context element to a Tomcat configuration file server.xml or place an XML file containing a Context element within the webapps directory. When you move a WAR file or a directory tree to the webapps directory, the base directory of the Web application is within this directory. It is possible to specify a base directory outside the webapps directory for Web applications deployed through a Context element by setting the docBase attribute of the Context element. This is the case with the Administration Tool and Tomcat Manager. Administration application is deployed through admin.xml file in the webapps directory. This file is shown below:

<Context path="/admin" docBase="../server/webapps/admin"
        debug="0" privileged="true">
  <!—Context sub-elements commented out  -->
</Context>

Now that we have covered the basics of Web applications and Web container Tomcat, we are ready to go over a simple Web application, Example ch9-rmb, and see how it works under Tomcat.