![]() |
![]() |
||||
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.
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:
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:
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>
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:
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>
Let's make a simple application for an online document share, which lets us browse it's /files folder.
<?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>
<h1>File Browser</h1> <p />Welcome to the online document repository! <p /><a href="files">Click here to start browsing</a>