Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Default Servlet Reference</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Default Servlet Reference</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#what">What is the DefaultServlet</a></li><li><a href="#where">Where is it declared?</a></li><li><a href="#change">What can I change?</a></li><li><a href="#dir">How do I customize directory listings?</a></li><li><a href="#secure">How do I secure directory listings?</a></li></ul>
6 
</div><h3 id="what">What is the DefaultServlet</h3><div class="text">
7 
<p>
8 
The default servlet is the servlet which serves static resources as well
9 
as serves the directory listings (if directory listings are enabled).
10 
</p>
11 
</div><h3 id="where">Where is it declared?</h3><div class="text">
12 
<p>
13 
It is declared globally in <i>$CATALINA_BASE/conf/web.xml</i>.
14 
By default here is it's declaration:
15 
</p>
16 
<div class="codeBox"><pre><code>    &lt;servlet&gt;
17 
        &lt;servlet-name&gt;default&lt;/servlet-name&gt;
18 
        &lt;servlet-class&gt;
19 
          org.apache.catalina.servlets.DefaultServlet
20 
        &lt;/servlet-class&gt;
21 
        &lt;init-param&gt;
22 
            &lt;param-name&gt;debug&lt;/param-name&gt;
23 
            &lt;param-value&gt;0&lt;/param-value&gt;
24 
        &lt;/init-param&gt;
25 
        &lt;init-param&gt;
26 
            &lt;param-name&gt;listings&lt;/param-name&gt;
27 
            &lt;param-value&gt;false&lt;/param-value&gt;
28 
        &lt;/init-param&gt;
29 
        &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
30 
    &lt;/servlet&gt;
31 
 
32 
...
33 
 
34 
    &lt;servlet-mapping&gt;
35 
        &lt;servlet-name&gt;default&lt;/servlet-name&gt;
36 
        &lt;url-pattern&gt;/&lt;/url-pattern&gt;
37 
    &lt;/servlet-mapping&gt;</code></pre></div>
38 
 
39 
<p>So by default, the default servlet is loaded at webapp startup and directory
40 
listings are disabled and debugging is turned off.</p>
41 
 
42 
<p>If you need to change the DefaultServlet settings for an application you can
43 
override the default configuration by re-defining the DefaultServlet in
44 
<code>/WEB-INF/web.xml</code>. However, this will cause problems if you attempt
45 
to deploy the application on another container as the DefaultServlet class will
46 
not be recognised. You can work-around this problem by using the Tomcat specific
47 
<code>/WEB-INF/tomcat-web.xml</code> deployment descriptor. The format is
48 
identical to <code>/WEB-INF/web.xml</code>. It will override any default
49 
settings but not those in <code>/WEB-INF/web.xml</code>. Since it is Tomcat
50 
specific, it will only be processed when the application is deployed on
51 
Tomcat.</p>
52 
</div><h3 id="change">What can I change?</h3><div class="text">
53 
<p>
54 
  The DefaultServlet allows the following initParameters:
55 
</p>
56 
 
57 
<table class="defaultTable"><tr><th style="width: 15%;">
58 
          Property
59 
        </th><th style="width: 85%;">
60 
          Description
61 
        </th></tr><tr><td><code class="propertyName">debug</code></td><td>
62 
        Debugging level. It is not very useful unless you are a tomcat
63 
        developer. As
64 
        of this writing, useful values are 0, 1, 11. [0]
65 
  </td></tr><tr><td><code class="propertyName">listings</code></td><td>
66 
        If no welcome file is present, can a directory listing be
67 
        shown?
68 
        value may be <b>true</b> or <b>false</b> [false]
69 
        <br>
70 
        Welcome files are part of the servlet api.
71 
        <br>
72 
        <b>WARNING:</b> Listings of directories containing many entries are
73 
        expensive. Multiple requests for large directory listings can consume
74 
        significant proportions of server resources.
75 
  </td></tr><tr><td><code class="propertyName">precompressed</code></td><td>
76 
        If a precompressed version of a file exists (a file with <code>.br</code>
77 
        or <code>.gz</code> appended to the file name located alongside the
78 
        original file), Tomcat will serve the precompressed file if the user
79 
        agent supports the matching content encoding (br or gzip) and this
80 
        option is enabled. [false]
81 
        <br>
82 
        The precompressed file with the with <code>.br</code> or <code>.gz</code>
83 
        extension will be accessible if requested directly so if the original
84 
        resource is protected with a security constraint, the precompressed
85 
        versions must be similarly protected.
86 
        <br>
87 
        It is also possible to configure the list of precompressed formats.
88 
        The syntax is comma separated list of
89 
        <code>[content-encoding]=[file-extension]</code> pairs. For example:
90 
        <code>br=.br,gzip=.gz,bzip2=.bz2</code>. If multiple formats are
91 
        specified, the client supports more than one and the client does not
92 
        express a preference, the order of the list of formats will be treated
93 
        as the server preference order and used to select the format returned.
94 
  </td></tr><tr><td><code class="propertyName">readmeFile</code></td><td>
95 
        If a directory listing is presented, a readme file may also
96 
        be presented with the listing. This file is inserted as is
97 
        so it may contain HTML.
98 
  </td></tr><tr><td><code class="propertyName">globalXsltFile</code></td><td>
99 
        If you wish to customize your directory listing, you
100 
        can use an XSL transformation. This value is a relative file name (to
101 
        either $CATALINA_BASE/conf/ or $CATALINA_HOME/conf/) which will be used
102 
        for all directory listings. This can be overridden per context and/or
103 
        per directory. See <strong>contextXsltFile</strong> and
104 
        <strong>localXsltFile</strong> below. The format of the xml is shown
105 
        below.
106 
  </td></tr><tr><td><code class="propertyName">contextXsltFile</code></td><td>
107 
        You may also customize your directory listing by context by
108 
        configuring <code>contextXsltFile</code>. This must be a context
109 
        relative path (e.g.: <code>/path/to/context.xslt</code>) to a file with
110 
        a <code>.xsl</code> or <code>.xslt</code> extension. This overrides
111 
        <code>globalXsltFile</code>. If this value is present but a file does
112 
        not exist, then <code>globalXsltFile</code> will be used. If
113 
        <code>globalXsltFile</code> does not exist, then the default
114 
        directory listing will be shown.
115 
  </td></tr><tr><td><code class="propertyName">localXsltFile</code></td><td>
116 
    <p>You may also customize your directory listing by directory by configuring
117 
    <code>localXsltFile</code>. This must be a file in the directory where the
118 
    listing will take place to with a <code>.xsl</code> or <code>.xslt</code>
119 
    extension. This overrides <code>globalXsltFile</code> and
120 
    <code>contextXsltFile</code>. If this value is present but a file does not
121 
    exist, then <code>contextXsltFile</code> will be used. If
122 
    <code>contextXsltFile</code> does not exist, then
123 
    <code>globalXsltFile</code> will be used. If <code>globalXsltFile</code>
124 
    does not exist, then the default directory listing will be shown.</p>
125 
    <p>Any <code>localXsltFile</code> is both a Tomcat configuration file and
126 
    part of the web application. As per the Tomcat security model, such files
127 
    are assumed to be trusted. Write access to this file should, like write
128 
    access to any Tomcat configuration file, be limited to trusted users. This
129 
    incudes users with remote access via WebDAV, PUT or similar.</p>
130 
  </td></tr><tr><td><code class="propertyName">input</code></td><td>
131 
        Input buffer size (in bytes) when reading
132 
        resources to be served.  [2048]
133 
  </td></tr><tr><td><code class="propertyName">output</code></td><td>
134 
        Output buffer size (in bytes) when writing
135 
        resources to be served.  [2048]
136 
  </td></tr><tr><td><code class="propertyName">readonly</code></td><td>
137 
        Is this context "read only", so HTTP commands like PUT and
138 
        DELETE are rejected?  [true]
139 
  </td></tr><tr><td><code class="propertyName">fileEncoding</code></td><td>
140 
        File encoding to be used when reading static resources.
141 
        [platform default]
142 
  </td></tr><tr><td><code class="propertyName">useBomIfPresent</code></td><td>
143 
        If a static file contains a byte order mark (BOM), should this be used
144 
        to determine the file encoding in preference to fileEncoding. This
145 
        setting must be one of <code>true</code> (remove the BOM and use it in
146 
        preference to fileEncoding), <code>false</code> (remove the BOM but do
147 
        not use it) or <code>pass-through</code> (do not use the BOM and do not
148 
        remove it). [true]
149 
  </td></tr><tr><td><code class="propertyName">sendfileSize</code></td><td>
150 
        If the connector used supports sendfile, this represents the minimal
151 
        file size in KiB for which sendfile will be used. Use a negative value
152 
        to always disable sendfile. [48]
153 
  </td></tr><tr><td><code class="propertyName">useAcceptRanges</code></td><td>
154 
        If true, the Accept-Ranges header will be set when appropriate for the
155 
        response. [true]
156 
        <br>
157 
        Deprecated. This option will be removed without replacement in Tomcat
158 
        12 onwards where it will effectively be hard coded to <code>true</code>.
159 
  </td></tr><tr><td><code class="propertyName">showServerInfo</code></td><td>
160 
        Should server information be presented in the response sent to clients
161 
        when directory listing is enabled. [true]
162 
  </td></tr><tr><td><code class="propertyName">sortListings</code></td><td>
163 
        Should the server sort the listings in a directory. [false]
164 
  </td></tr><tr><td><code class="propertyName">sortDirectoriesFirst</code></td><td>
165 
        Should the server list all directories before all files. [false]
166 
  </td></tr><tr><td><code class="propertyName">allowPartialPut</code></td><td>
167 
        Should the server treat an HTTP PUT request with a Content-Range header
168 
        as a partial PUT? Note that while RFC 7231 clarified that such a PUT
169 
        with a Content-Range header field is a bad request, RFC 9110
170 
        (which obsoletes RFC 7231) now allows partial PUT. [true]
171 
  </td></tr><tr><td><code class="propertyName">allowPostAsGet</code></td><td>
172 
        Controls whether a direct request (i.e. not a forward or an include) for
173 
        a static resource using the POST method will be processed as if the GET
174 
        method had been used. If not allowed, the request will be rejected. The
175 
        default behaviour of processing the request as if the GET method had
176 
        been used is unchanged. [true]
177 
  </td></tr></table>
178 
</div><h3 id="dir">How do I customize directory listings?</h3><div class="text">
179 
<p>You can override DefaultServlet with you own implementation and use that
180 
in your web.xml declaration. If you
181 
can understand what was just said, we will assume you can read the code
182 
to DefaultServlet servlet and make the appropriate adjustments. (If not,
183 
then that method isn't for you)
184 
</p>
185 
<p>
186 
You can use either  <code>localXsltFile</code>, <code>contextXsltFile</code>
187 
or <code>globalXsltFile</code> and DefaultServlet will create
188 
an xml document and run it through an xsl transformation based
189 
on the values provided in the XSLT file. <code>localXsltFile</code> is first
190 
checked, then <code>contextXsltFile</code>, followed by
191 
<code>globalXsltFile</code>. If no XSLT files are configured, default behavior
192 
is used.
193 
</p>
194 
 
195 
<p>
196 
Format:
197 
</p>
198 
<div class="codeBox"><pre><code>    &lt;listing&gt;
199 
     &lt;entries&gt;
200 
      &lt;entry type='file|dir' urlPath='aPath' size='###' date='gmt date'&gt;
201 
        fileName1
202 
      &lt;/entry&gt;
203 
      &lt;entry type='file|dir' urlPath='aPath' size='###' date='gmt date'&gt;
204 
        fileName2
205 
      &lt;/entry&gt;
206 
      ...
207 
     &lt;/entries&gt;
208 
     &lt;readme&gt;&lt;/readme&gt;
209 
    &lt;/listing&gt;</code></pre></div>
210 
<ul>
211 
  <li>size will be missing if <code>type='dir'</code></li>
212 
  <li>Readme is a CDATA entry</li>
213 
</ul>
214 
 
215 
<p>
216 
  The following is a sample xsl file which mimics the default tomcat behavior:
217 
</p>
218 
<div class="codeBox"><pre><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
219 
 
220 
&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
221 
  version="3.0"&gt;
222 
 
223 
  &lt;xsl:output method="html" html-version="5.0"
224 
    encoding="UTF-8" indent="no"
225 
    doctype-system="about:legacy-compat"/&gt;
226 
 
227 
  &lt;xsl:template match="listing"&gt;
228 
   &lt;html&gt;
229 
    &lt;head&gt;
230 
      &lt;title&gt;
231 
        Sample Directory Listing For
232 
        &lt;xsl:value-of select="@directory"/&gt;
233 
      &lt;/title&gt;
234 
      &lt;style&gt;
235 
        h1 {color : white;background-color : #0086b2;}
236 
        h3 {color : white;background-color : #0086b2;}
237 
        body {font-family : sans-serif,Arial,Tahoma;
238 
             color : black;background-color : white;}
239 
        b {color : white;background-color : #0086b2;}
240 
        a {color : black;} HR{color : #0086b2;}
241 
        table td { padding: 5px; }
242 
      &lt;/style&gt;
243 
    &lt;/head&gt;
244 
    &lt;body&gt;
245 
      &lt;h1&gt;Sample Directory Listing For
246 
            &lt;xsl:value-of select="@directory"/&gt;
247 
      &lt;/h1&gt;
248 
      &lt;hr style="height: 1px;" /&gt;
249 
      &lt;table style="width: 100%;"&gt;
250 
        &lt;tr&gt;
251 
          &lt;th style="text-align: left;"&gt;Filename&lt;/th&gt;
252 
          &lt;th style="text-align: center;"&gt;Size&lt;/th&gt;
253 
          &lt;th style="text-align: right;"&gt;Last Modified&lt;/th&gt;
254 
        &lt;/tr&gt;
255 
        &lt;xsl:apply-templates select="entries"/&gt;
256 
        &lt;/table&gt;
257 
      &lt;xsl:apply-templates select="readme"/&gt;
258 
      &lt;hr style="height: 1px;" /&gt;
259 
      &lt;h3&gt;Apache Tomcat/9.0&lt;/h3&gt;
260 
    &lt;/body&gt;
261 
   &lt;/html&gt;
262 
  &lt;/xsl:template&gt;
263 
 
264 
 
265 
  &lt;xsl:template match="entries"&gt;
266 
    &lt;xsl:apply-templates select="entry"/&gt;
267 
  &lt;/xsl:template&gt;
268 
 
269 
  &lt;xsl:template match="readme"&gt;
270 
    &lt;hr style="height: 1px;" /&gt;
271 
    &lt;pre&gt;&lt;xsl:apply-templates/&gt;&lt;/pre&gt;
272 
  &lt;/xsl:template&gt;
273 
 
274 
  &lt;xsl:template match="entry"&gt;
275 
    &lt;tr&gt;
276 
      &lt;td style="text-align: left;"&gt;
277 
        &lt;xsl:variable name="urlPath" select="@urlPath"/&gt;
278 
        &lt;a href="{$urlPath}"&gt;
279 
          &lt;pre&gt;&lt;xsl:apply-templates/&gt;&lt;/pre&gt;
280 
        &lt;/a&gt;
281 
      &lt;/td&gt;
282 
      &lt;td style="text-align: right;"&gt;
283 
        &lt;pre&gt;&lt;xsl:value-of select="@size"/&gt;&lt;/pre&gt;
284 
      &lt;/td&gt;
285 
      &lt;td style="text-align: right;"&gt;
286 
        &lt;pre&gt;&lt;xsl:value-of select="@date"/&gt;&lt;/pre&gt;
287 
      &lt;/td&gt;
288 
    &lt;/tr&gt;
289 
  &lt;/xsl:template&gt;
290 
 
291 
&lt;/xsl:stylesheet&gt;</code></pre></div>
292 
 
293 
</div><h3 id="secure">How do I secure directory listings?</h3><div class="text">
294 
Use web.xml in each individual webapp. See the security section of the
295 
Servlet specification.
296 
 
297 
</div></div></div></div></div><footer><div id="footer">
298 
    Copyright &copy; 1999-2025, The Apache Software Foundation
299 
    <br>
300 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
301 
    are either registered trademarks or trademarks of the Apache Software
302 
    Foundation.
303 
    </div></footer></div></body></html>