| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="default-servlet.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="funkman@apache.org">Tim Funk</author> |
| <title>Default Servlet Reference</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| |
| <section anchor="what" name="What is the DefaultServlet"> |
| <p> |
| The default servlet is the servlet which serves static resources as well |
| as serves the directory listings (if directory listings are enabled). |
| </p> |
| </section> |
| |
| <section anchor="where" name="Where is it declared?"> |
| <p> |
| It is declared globally in <i>$CATALINA_BASE/conf/web.xml</i>. |
| By default here is it's declaration: |
| </p> |
| <source><![CDATA[ <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> |
| </init-param> |
| <load-on-startup>1</load-on-startup> |
| </servlet> |
| |
| ... |
| |
| <servlet-mapping> |
| <servlet-name>default</servlet-name> |
| <url-pattern>/</url-pattern> |
| </servlet-mapping>]]></source> |
| |
| <p>So by default, the default servlet is loaded at webapp startup and directory |
| listings are disabled and debugging is turned off.</p> |
| |
| <p>If you need to change the DefaultServlet settings for an application you can |
| override the default configuration by re-defining the DefaultServlet in |
| <code>/WEB-INF/web.xml</code>. However, this will cause problems if you attempt |
| to deploy the application on another container as the DefaultServlet class will |
| not be recognised. You can work-around this problem by using the Tomcat specific |
| <code>/WEB-INF/tomcat-web.xml</code> deployment descriptor. The format is |
| identical to <code>/WEB-INF/web.xml</code>. It will override any default |
| settings but not those in <code>/WEB-INF/web.xml</code>. Since it is Tomcat |
| specific, it will only be processed when the application is deployed on |
| Tomcat.</p> |
| </section> |
| |
| <section anchor="change" name="What can I change?"> |
| <p> |
| The DefaultServlet allows the following initParameters: |
| </p> |
| |
| <properties> |
| <property name="debug"> |
| Debugging level. It is not very useful unless you are a tomcat |
| developer. As |
| of this writing, useful values are 0, 1, 11. [0] |
| </property> |
| <property name="listings"> |
| If no welcome file is present, can a directory listing be |
| shown? |
| value may be <b>true</b> or <b>false</b> [false] |
| <br /> |
| Welcome files are part of the servlet api. |
| <br /> |
| <b>WARNING:</b> Listings of directories containing many entries are |
| expensive. Multiple requests for large directory listings can consume |
| significant proportions of server resources. |
| </property> |
| <property name="precompressed"> |
| If a precompressed version of a file exists (a file with <code>.br</code> |
| or <code>.gz</code> appended to the file name located alongside the |
| original file), Tomcat will serve the precompressed file if the user |
| agent supports the matching content encoding (br or gzip) and this |
| option is enabled. [false] |
| <br /> |
| The precompressed file with the with <code>.br</code> or <code>.gz</code> |
| extension will be accessible if requested directly so if the original |
| resource is protected with a security constraint, the precompressed |
| versions must be similarly protected. |
| <br /> |
| It is also possible to configure the list of precompressed formats. |
| The syntax is comma separated list of |
| <code>[content-encoding]=[file-extension]</code> pairs. For example: |
| <code>br=.br,gzip=.gz,bzip2=.bz2</code>. If multiple formats are |
| specified, the client supports more than one and the client does not |
| express a preference, the order of the list of formats will be treated |
| as the server preference order and used to select the format returned. |
| </property> |
| <property name="readmeFile"> |
| If a directory listing is presented, a readme file may also |
| be presented with the listing. This file is inserted as is |
| so it may contain HTML. |
| </property> |
| <property name="globalXsltFile"> |
| If you wish to customize your directory listing, you |
| can use an XSL transformation. This value is a relative file name (to |
| either $CATALINA_BASE/conf/ or $CATALINA_HOME/conf/) which will be used |
| for all directory listings. This can be overridden per context and/or |
| per directory. See <strong>contextXsltFile</strong> and |
| <strong>localXsltFile</strong> below. The format of the xml is shown |
| below. |
| </property> |
| <property name="contextXsltFile"> |
| You may also customize your directory listing by context by |
| configuring <code>contextXsltFile</code>. This must be a context |
| relative path (e.g.: <code>/path/to/context.xslt</code>) to a file with |
| a <code>.xsl</code> or <code>.xslt</code> extension. This overrides |
| <code>globalXsltFile</code>. If this value is present but a file does |
| not exist, then <code>globalXsltFile</code> will be used. If |
| <code>globalXsltFile</code> does not exist, then the default |
| directory listing will be shown. |
| </property> |
| <property name="localXsltFile"> |
| You may also customize your directory listing by directory by |
| configuring <code>localXsltFile</code>. This must be a file in the |
| directory where the listing will take place to with a |
| <code>.xsl</code> or <code>.xslt</code> extension. This overrides |
| <code>globalXsltFile</code> and <code>contextXsltFile</code>. If this |
| value is present but a file does not exist, then |
| <code>contextXsltFile</code> will be used. If |
| <code>contextXsltFile</code> does not exist, then |
| <code>globalXsltFile</code> will be used. If |
| <code>globalXsltFile</code> does not exist, then the default |
| directory listing will be shown. |
| </property> |
| <property name="input"> |
| Input buffer size (in bytes) when reading |
| resources to be served. [2048] |
| </property> |
| <property name="output"> |
| Output buffer size (in bytes) when writing |
| resources to be served. [2048] |
| </property> |
| <property name="readonly"> |
| Is this context "read only", so HTTP commands like PUT and |
| DELETE are rejected? [true] |
| </property> |
| <property name="fileEncoding"> |
| File encoding to be used when reading static resources. |
| [platform default] |
| </property> |
| <property name="useBomIfPresent"> |
| If a static file contains a byte order mark (BOM), should this be used |
| to determine the file encoding in preference to fileEncoding. [true] |
| </property> |
| <property name="sendfileSize"> |
| If the connector used supports sendfile, this represents the minimal |
| file size in KB for which sendfile will be used. Use a negative value |
| to always disable sendfile. [48] |
| </property> |
| <property name="useAcceptRanges"> |
| If true, the Accept-Ranges header will be set when appropriate for the |
| response. [true] |
| </property> |
| <property name="showServerInfo"> |
| Should server information be presented in the response sent to clients |
| when directory listing is enabled. [true] |
| </property> |
| <property name="sortListings"> |
| Should the server sort the listings in a directory. [false] |
| </property> |
| <property name="sortDirectoriesFirst"> |
| Should the server list all directories before all files. [false] |
| </property> |
| <property name="allowPartialPut"> |
| Should the server treat an HTTP PUT request with a Range header as a |
| partial PUT? Note that RFC 7233 clarified that Range headers are only |
| valid for GET requests. [true] |
| </property> |
| </properties> |
| </section> |
| |
| <section anchor="dir" name="How do I customize directory listings?"> |
| <p>You can override DefaultServlet with you own implementation and use that |
| in your web.xml declaration. If you |
| can understand what was just said, we will assume you can read the code |
| to DefaultServlet servlet and make the appropriate adjustments. (If not, |
| then that method isn't for you) |
| </p> |
| <p> |
| You can use either <code>localXsltFile</code> or |
| <code>globalXsltFile</code> and DefaultServlet will create |
| an xml document and run it through an xsl transformation based |
| on the values provided in <code>localXsltFile</code> and |
| <code>globalXsltFile</code>. <code>localXsltFile</code> is first |
| checked, followed by <code>globalXsltFile</code>, then default |
| behaviors takes place. |
| </p> |
| |
| <p> |
| Format: |
| </p> |
| <source><![CDATA[ <listing> |
| <entries> |
| <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> |
| fileName1 |
| </entry> |
| <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> |
| fileName2 |
| </entry> |
| ... |
| </entries> |
| <readme></readme> |
| </listing>]]></source> |
| <ul> |
| <li>size will be missing if <code>type='dir'</code></li> |
| <li>Readme is a CDATA entry</li> |
| </ul> |
| |
| <p> |
| The following is a sample xsl file which mimics the default tomcat behavior: |
| </p> |
| <source><?xml version="1.0" encoding="UTF-8"?> |
| |
| <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" |
| version="3.0"> |
| |
| <xsl:output method="html" html-version="5.0" |
| encoding="UTF-8" indent="no" |
| doctype-system="about:legacy-compat"/> |
| |
| <xsl:template match="listing"> |
| <html> |
| <head> |
| <title> |
| Sample Directory Listing For |
| <xsl:value-of select="@directory"/> |
| </title> |
| <style> |
| h1 {color : white;background-color : #0086b2;} |
| h3 {color : white;background-color : #0086b2;} |
| body {font-family : sans-serif,Arial,Tahoma; |
| color : black;background-color : white;} |
| b {color : white;background-color : #0086b2;} |
| a {color : black;} HR{color : #0086b2;} |
| table td { padding: 5px; } |
| </style> |
| </head> |
| <body> |
| <h1>Sample Directory Listing For |
| <xsl:value-of select="@directory"/> |
| </h1> |
| <hr style="height: 1px;" /> |
| <table style="width: 100%;"> |
| <tr> |
| <th style="text-align: left;">Filename</th> |
| <th style="text-align: center;">Size</th> |
| <th style="text-align: right;">Last Modified</th> |
| </tr> |
| <xsl:apply-templates select="entries"/> |
| </table> |
| <xsl:apply-templates select="readme"/> |
| <hr style="height: 1px;" /> |
| <h3>Apache Tomcat/<version-major-minor/></h3> |
| </body> |
| </html> |
| </xsl:template> |
| |
| |
| <xsl:template match="entries"> |
| <xsl:apply-templates select="entry"/> |
| </xsl:template> |
| |
| <xsl:template match="readme"> |
| <hr style="height: 1px;" /> |
| <pre><xsl:apply-templates/></pre> |
| </xsl:template> |
| |
| <xsl:template match="entry"> |
| <tr> |
| <td style="text-align: left;"> |
| <xsl:variable name="urlPath" select="@urlPath"/> |
| <a href="{$urlPath}"> |
| <pre><xsl:apply-templates/></pre> |
| </a> |
| </td> |
| <td style="text-align: right;"> |
| <pre><xsl:value-of select="@size"/></pre> |
| </td> |
| <td style="text-align: right;"> |
| <pre><xsl:value-of select="@date"/></pre> |
| </td> |
| </tr> |
| </xsl:template> |
| |
| </xsl:stylesheet></source> |
| |
| </section> |
| |
| <section anchor="secure" name="How do I secure directory listings?"> |
| Use web.xml in each individual webapp. See the security section of the |
| Servlet specification. |
| |
| </section> |
| |
| </body> |
| |
| </document> |