Chapter 6. Customizing Tomcat

This section explores some of the ways you can control the way Tomcat operates. This is not exhaustive -- Tomcat is extremely sophisticated software and there are a lot of things you can change or tweak.

6.1. Disable Directory Listing

For fresh Tomcat installations, directory listing is enabled by default. This can be a very useful debugging tool, and if, like me, you sometimes forget what servlets are deployed in a certain web application, you can get a complete listing by simply keying in the web application's URL.

But for production deployments, you may want to turn it off. If nothing else, it discourages users from poking around where they should not. There are basically 2 methods of "turning off" this option :

The first option is fairly simple, so we shall only examine the second option.

Open the file web.xml which is located inside $CATALINA_HOME/conf/. This is the global web.xml file, which means that any changes here will affect ALL web applications deployed by that Tomcat instance. If you want more granular control, like turning it off for certain applications but not for others, you will need to go with the first option of creating index.html files.

Locate the following section:

<servlet>
        <servlet-name>default</servlet-name>
                <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
            <init-param>
                <param-name>debug</param-name>
                <param-value>0</param-value>
            </init-param>
            <init-param>
                <param-name>listings</param-name>
                <param-value>true</param-value>
            </init-param>
            <load-on-startup>1</load-on-startup>
    </servlet>
</sect1>

This is the first section in web.xml. The options that concern us are :

<init-param>
        <param-name>listings</param-name>
        <param-value>true</param-value>
</init-param>

Change <param-value> to false and you turn off directory listing. It is that simple.

6.2. Custom Default Pages

Tomcat uses the same convention as the Apache Web Server in that index.html is the default or home page of any directory. Sometimes you may want to change that to page1.html or maybe a JSP page, like now_see_this.jsp.

To do that, simply open the web.xml of your web application, and add the following lines :

<welcome-file-list>
        <welcome-file>now_see_this.jsp</welcome-file>
        <welcome-file>page1.html</welcome-file>
        <welcome-file>index.html</welcome-file>
</welcome-file-list>

To change it system-wide, edit the global web.xml in $CATALINA_HOME/conf, and change the <welcome-file> to point to the file of your choice.

6.3. Custom Error Pages

Unhappy with the default error pages that come with Tomcat ? You can define your own custom error pages in your web.xml file. In the example shown below, we define 2 web pages -- server_error.html and file_not_found.html -- which will be displayed when the server encounters an error 500 or an error 404 respectively.

    <error-page>
        <error-code>500</error-code>
        <location>/server_error.html</location>
    </error-page>
    <error-page>
        <error-code>404</error-code>
        <location>/file_not_found.html</location>
    </error-page>   

You should bear in mind, however, that the order of the tags for the web.xml file is very important. If the order in your web.xml file is incorrect, Tomcat will output errors on startup.