mystyleit

Adventures with Tomcat 5.5

Tomcat has one main configuration files: server.xml. There is also another very misunderstood file web.xml that I will talk about too.

server.xml contains all the parameters of the Tomcat instance. The file has the following "big parts":

Now let's talk about the most important/common questions about the file, Connectors and Realms (ie Authentication).

Minimal server.xml File

You should use the default server.xml file, this is only presented in order to get familiar with it's layout.

Connectors

Tomcat has this idea of Connects, each Connector allows Tomcat to speak a different language, HTTP, or AJP, or HTTPS. The default Connectors are HTTP (on port 8080) and AJP (port 8009). AJP is what IIS or Apache talk to Tomcat on (when you have a web server sitting in front of Tomcat).

One important trick with the AJP connector is to turn off Tomcat Authentication when you have another web server sitting in front of Tomcat performing the authentication. To do this, add the following to your AJP connector entry:

SSL Connector

In order to have an SSL connector, you need to have a keystore that contains a SSL certificate. Here is a link to how to create a keystore, and other keystore tasks (import, export, etc):
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html

Here is a link to a GUI interface to the keystore, requires Java 6 and very handy:
http://yellowcat1.free.fr/

So (hopefully) you have a keystore with a key inside (the default self-signed key or something else). Now you need to add the SSL connector. It should go with the other connectors in the Service section and looks something like this:

In order to require SSL on a specific site, you need to configure a security constrant for that app. You can do this by editing that app's web.xml file (see below). The constrant looks like this: ><user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint>

Deploying Web Appls and the web.xml File

Hopefully the above explains the server.xml enough to grasp what Tomcat is doing. The important thing to realize is that different sections of the file have differents scopes. The futher down you go, the narrower the scope.

Tomcat, like Apache, has this idea of a Virtual Host. Basically it allows you to run serveral different sites on the same port (either 80 or 8080). This post isn't going to cover all that. Instead, just realize that localhost is the default host.

In order to deploy a web app that isn't a WAR file (beyond the scope of this document) you need to create a context for it. You can either create the context in the host section in the server.xml (which is bad because it makes the file more complicated) or you can create a seperate xml file in the host folder, under the Engine.

The default host folder, (under the default engine) is of course:
\Tomcat 5.5\conf\Catalina\localhost

You should name the xml file will of the directory in the URL.
If I created \Tomcat 5.5\conf\Catalina\localhost\myapp.xml the URL for this application http://site/myapp

A very simple context looks something this:

For more about contexts see the following:
http://tomcat.apache.org/tomcat-5.5-doc/config/context.html

What about the web.xml?

Every web application is going to have a WEB-INF folder. In the above example, this would be C:\myapp\WEB-INF. Inside the WEB-INF folder is a file, web.xml.

The web.xml file in the WEB-INF folder of your web app is used to configure that web app. That is it's scope ONLY.

The web.xml file in Tomcat 5.5\conf is the global web.xml file. It is processed before it reads the WEB-INF\web.xml file in the app's docBase. You can override what is in the Tomcat 5.5\conf\web.xml by setting knew values in the WEB-INF\web.xml.

So (hopefully you have guessed this) you shouldn't mess about with the Tomcat 5.5\conf\web.xml file. It's way better to mess around with the web.xml in WEB-INF\

Realms (Tomcat Authentication)

Unlike IIS, Tomcat has many, different (and complicated) authentication methods. They call them Realms.

The steps for securing a web app is first to have a Realm setup in the server.xml file. The second is to create a security constrant in the app's web.xml file.

Going over how to create all the security constraint's is what Google is great for. The important thing to know about Realms are:

• You make them in the server.xml file
• Where you put them affects their scope (ie which applications can use the Realm)
• When in doubt, put them under the Engine, that way every app run by that engine can use them.

Here is a link that covers all of Tomcat's Realms:
http://tomcat.apache.org/tomcat-5.5-doc/realm-howto.html

Conclusion

I love IIS. Unfortunately it doesn't run JSP and Servlets so you need an Application Server.