Tomcat administration

Tomcat is a servlet container, and as such can be used to deploy web applications using Java on the server side.

Installation & Configuration

Tomcat on Gentoo

• To launch Tomcat with an LD_LIBRARY_PATH custom value, just export this environment variable in /etc/conf.d/tomcat-6. It will work, but strangely, only on the first load of a web-application. If you undeploy the webapp and redeploy it, you will get an UnsatisfiedLinkError exception.

• Currently (19/03/2007), the init scripts on Gentoo are not able to redirect Tomcat's standard output to a file. This is bug 162379 in Gentoo's bugzilla.

• This means everything sending stuff to the standard output (for example a console appender in Log4J) won't work. This also means that stack trace logs (caused by exceptions) are not going to be available, since they are outputted to stdout.

• UPDATE: This is now fixed.

Controlling Tomcat

• You can control Tomcat via the web GUI (the manager web-application), or with an useful set of Ant tasks. The jar containing the ant tasks is named catalina-ant.jar. You can deploy or redeploy (update) a web application, and generally achieve everything you usually need.

Virtual Hosts

• Tomcat supports virtual hosts. This is a nice way to have several webapps hosted on the root context ("/"), but at different hostnames. Follow Tomcat documentation to create virtual hosts.

• You can deploy a WAR archive on a virtual host using the Manager Tomcat webapp. The easiest way to do this is to deploy the manager webapp to the new virtual host. On Gentoo this is done very easily just by copying a context file /etc/tomcat-6/Catalina/localhost/manager.xml to a context corresponding to the virtual host (eg /etc/tomcat-6/Catalina/newhost/manager.xml).

Concepts

Tomcat Classloading

• Tomcat seeems to be picky about classloading. In particular put your JDBC driver (along with Hibernate) in common/lib. I had troubles when it was placed in shared/lib. This seems to happen when you let Tomcat do the pooling.

Session Mechanism

• The cookie set by Tomcat is by default set on the path corresponding to the context path of the web-application. I did not yet find a way to change this (in Jetty you can control every aspect of the session cookie).

• UPDATE: there is a way to set the session path to "/", which will usually always work. Set the emptySessionPath attribute to true in your Tomcat Connector configuration file.

Tomcat Logging

• If Tomcat finds the log4j.jar on its classpath, it will use log4j as its logging system. And if log4j is not configured at all, *nothing* will be printed anywhere. So if you want to disable log4j logging and use JDK logging, you must delete the log4j.jar, it is not sufficient to delete or remove the log4j.properties file.

• Warning: You need to emerge commons-logging (the base library Tomcat uses for logging) with the log4j USE flag enabled, else it won't be able to use log4j logging!

Tomcat Security

• By default, Tomcat uses a Security Manager on Gentoo. This Security Manager policy is by default, very strict. In particular, it allows JDBC connections but does not allow any kind of write operations on the webapp directory. The security policy configuration file is located at /etc/tomcat-5.5/catalina.policy on Gentoo. Adding for example the following line will make the webapps directory writable by the servlets:

permission java.io.FilePermission "${catalina.home}/webapps/-", "read, write";

The "-" at the end indicates that every file recursively has the permission applied. Don't forget that standard UNIX permissions still apply, so the tomcat user must of course be able to write to the desired directories.

Tomcat Port and Connectors

• The base configuration file for Tomcat is named server.xml. Here you define a server (the port attribute in the server node is used only to shut down Tomcat). Inside this server you can define several connectors. The most basic connector is the HTTP 1.1 connector. It has a port attribute that you can edit in order to change the port.

HTTP connector

• There is no configuration based way to add standard HTTP headers to the responses the Tomcat connector generates. The only way is to use a servlet filter to programmatically set those headers. Grails filters work equally well for this.

• Another option of course, if you are behind a lighttpd proxy, is to set the headers via lighttpd mod_header. This would also work with Apache httpd.

Web Applications

Context Path

• Every web application has a context path. To deploy to the root context (the "/" path), currently the only way I have found is to name the WAR file ROOT.war. In Grails I also had to rename the application name to "ROOT".

Mappings to Servlets

• The mappings from URL to servlets are declared in the webapp deployment descriptor (web.xml file).

• Be careful - mappings are not expected to be used with the default servlet. The default servlet is intented to serve static resources *that are not mapped*. You can still map files with extension based wildcards (*.css, *.png), however using path wildcards (/css/*) won't work with the default servlet. This is probably due to the fact that the default servlet (in Tomcat at least) look at the pathInfo data, not the full request path (servletPath + pathInfo).

• Information regarding request path elements is available at section 3.4 of the Servlet Specification. What is important to understand is that it's the responsibility of the servlet container to fill the contextPath, servletPath and pathInfo elements. Depending on the mapping used (extension mapping, directory mapping, default "/" mapping), the repartition of the URL within those sections can be different and some servlets can react differently. This is the case for Spring dispatcher too apparently.