Enabling or Disabling Directory Listings using web.xml

Author: Neale Rudd, Metawerx

Date: 03-Oct-2006

Introduction

The directory listings feature of Tomcat outputs a list of all files in a folder if none of the default welcome files are found. This article shows how to override the default behaviour of the VM on a per-application basis, in your local web.xml file.

Warning: This technique will only work with Tomcat, or application servers that include Tomcat, as it requires certain classes from Apache. It should work on JBoss, Geronimo and Websphere.

The directory listing page lists all files in the folder, along with their size and last modified date. Here is an example screenshot:

This feature is either enabled or disabled in the Tomcat configuration file by the server administrator. This setting affects all applications running in the JVM.

Default Behaviour

When a user browses to a URL which points to a directory, Tomcat first tries to display the default welcome files. If none of these exist, either a directory listing or 404 error is displayed, depending on the setting in the server's default web.xml file - <jakarta>/conf/web.xml.

This wiki has directory listings disabled, therefore the link http://wiki.metawerx.net/images/ will show a 404 error, even though it exists.

In older versions of Tomcat, this feature was enabled by default. Depending on the distribution, the feature may be enabled or disabled. You can check this in 2 ways:

• Create a folder on your application, with no html/jsp files in it, and browse to it with your browser
• or, check the <jakarta>/conf/web.xml file directly

The server administrator, or distribution, will normally disable this feature as it poses a security risk. See Risks of Enabling Directory Listings for more information.

However, in some cases, you want to override this behaviour for a single application.

Examples are as follows:

• You want to create a document share with directory listings enabled, but want all other applications on the VM to disallow directory browsing.
• Shared VM: The server administrator has disabled directory listings in the server-wide web.xml, but you want to enable it for your application.
• Shared VM: The server administrator has enabled directory listings in the server-wide web.xml, but you want to protect your application by disabling it.

The DefaultServlet

The module responsible for deciding when, and if to display a directory listing, is the Tomcat "DefaultServlet".

The DefaultServlet is also responsible for checking the welcome file list (index.jsp, index.htm etc..)

This servlet comes as part of Tomcat, and it's servlet parameters are in the system-wide <jakarta>/conf/web.xml file, along with documentation on its various attributes.

To override the default functionality for the VM, we will need to override these settings.

Here is the code from <jakarta>/conf/web.xml:

<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>false</param-value>    <!-- This setting enables/disables directory listings -->
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

There is also a <servlet-mapping> tag which maps the servlet to the "/" url-mapping:

<!-- The mapping for the default servlet -->
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

How to Override

To override the default behaviour, we will copy (most of) this information into our own web.xml file.

However, the following changes will be made:

• The system-wide web.xml file has used the <servlet-name> tag to name the DefaultServlet as default. We have to select a new name to avoid a conflict, or our application won't start. We will use DefaultServletOverride as the name in our web.xml.
• We will set the listings attribute to true, to enable directory listings
• We don't need the debug attribute, so we'll leave it out (although you can leave it in if you like).

Here is the code to add to our application's web.xml:

<!-- Enable directory listings by overriding the server default web.xml -->
<!-- definition for the default servlet -->
<servlet>
    <servlet-name>DefaultServletOverride</servlet-name>
    <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
    <init-param>
        <param-name>listings</param-name>
        <param-value>true</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<!-- Add a mapping for our new default servlet -->
<servlet-mapping>
    <servlet-name>DefaultServletOverride</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

A Complete Example - the Directory Browser application

Let's make a simple application for an online document share, which lets us browse it's /files folder.

• First create a new application folder in your webapps folder called Browser

• In the new Browser folder, create two folders: WEB-INF and files

• The files folder will be our browseable folder. Create some other subfolders under files (eg: photos and code), and add a few example files such as some photos or source code, so that we have something to browse.

• Copy the following into /Browser/WEB-INF/web.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

    <display-name>Browser</display-name>
    <description>File Browsing Application for the Document Share</description>

    <!-- Enable directory listings by overriding the server default web.xml -->
    <!-- definition for the default servlet -->
    <servlet>
        <servlet-name>DefaultServletOverride</servlet-name>
        <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
        <init-param>
            <param-name>listings</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- Add a mapping for our new default servlet -->
    <servlet-mapping>
        <servlet-name>DefaultServletOverride</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

</web-app>

• Copy the following into /Browser/index.jsp:

<h1>File Browser</h1>

<p />Welcome to the online document repository!

<p /><a href="files">Click here to start browsing</a>

• The application is now ready, use the Tomcat Manager to check if Tomcat has already deployed the application. If not, then start it.

• Browse to http://yoursite/Browser

• If all has gone well, the index.jsp file will now be displayed (because it is a welcome-file), and will invite you to start browsing.

See Also

• Customising the Tomcat Directory Listing - The look of the directory listing page can be customized in Tomcat 5.5 and above, using XSLT (XSL Transformation).
• How to use a servlet as your main web page