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 Configuration Reference (9.0.112) - The Host Container</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 Configuration Reference</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="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Host Container</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Logging">Logging</a></li><li><a href="#Access_Logs">Access Logs</a></li><li><a href="#Automatic_Application_Deployment">Automatic Application Deployment</a></li><li><a href="#Host_Name_Aliases">Host Name Aliases</a></li><li><a href="#Lifecycle_Listeners">Lifecycle Listeners</a></li><li><a href="#Request_Filters">Request Filters</a></li><li><a href="#Single_Sign_On">Single Sign On</a></li><li><a href="#User_Web_Applications">User Web Applications</a></li><li><a href="#Custom_context.xml_and_web.xml">Custom context.xml and web.xml</a></li></ol></li></ul> |
||
| 6 | </div><h3 id="Introduction">Introduction</h3><div class="text"> |
||
| 7 | |||
| 8 | <p>The <strong>Host</strong> element represents a <em>virtual host</em>, |
||
| 9 | which is an association of a network name for a server (such as |
||
| 10 | "www.mycompany.com") with the particular server on which Tomcat is running. |
||
| 11 | For clients to be able to connect to a Tomcat server using its network name, |
||
| 12 | this name must be registered in the <em>Domain Name Service</em> (DNS) server |
||
| 13 | that manages the Internet domain you belong to - contact your Network |
||
| 14 | Administrator for more information.</p> |
||
| 15 | |||
| 16 | <p>In many cases, System Administrators wish to associate more than |
||
| 17 | one network name (such as <code>www.mycompany.com</code> and |
||
| 18 | <code>company.com</code>) with the same virtual host and applications. |
||
| 19 | This can be accomplished using the <a href="#Host_Name_Aliases">Host |
||
| 20 | Name Aliases</a> feature discussed below.</p> |
||
| 21 | |||
| 22 | <p>One or more <strong>Host</strong> elements are nested inside an |
||
| 23 | <a href="engine.html">Engine</a> element. Inside the Host element, you |
||
| 24 | can nest <a href="context.html">Context</a> elements for the web |
||
| 25 | applications associated with this virtual host. Exactly one of the Hosts |
||
| 26 | associated with each Engine MUST have a name matching the |
||
| 27 | <code>defaultHost</code> attribute of that Engine.</p> |
||
| 28 | |||
| 29 | <p>Clients normally use host names to identify the server they wish to connect |
||
| 30 | to. This host name is also included in the HTTP request headers. Tomcat |
||
| 31 | extracts the host name from the HTTP headers and looks for a |
||
| 32 | <strong>Host</strong> with a matching name. If no match is found, the request |
||
| 33 | is routed to the default host. The name of the default host does not have to |
||
| 34 | match a DNS name (although it can) since any request where the DNS name does |
||
| 35 | not match the name of a <strong>Host</strong> element will be routed to the |
||
| 36 | default host.</p> |
||
| 37 | |||
| 38 | <p><em>The description below uses the variable name $CATALINA_BASE to refer the |
||
| 39 | base directory against which most relative paths are resolved. If you have |
||
| 40 | not configured Tomcat for multiple instances by setting a CATALINA_BASE |
||
| 41 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, |
||
| 42 | the directory into which you have installed Tomcat.</em></p> |
||
| 43 | |||
| 44 | </div><h3 id="Attributes">Attributes</h3><div class="text"> |
||
| 45 | |||
| 46 | <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text"> |
||
| 47 | |||
| 48 | <p>All implementations of <strong>Host</strong> |
||
| 49 | support the following attributes:</p> |
||
| 50 | |||
| 51 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 52 | Attribute |
||
| 53 | </th><th style="width: 85%;"> |
||
| 54 | Description |
||
| 55 | </th></tr><tr id="Attributes_Common Attributes_appBase"><td><strong><code class="attributeName">appBase</code></strong></td><td> |
||
| 56 | <p>The <em>Application Base</em> directory for this virtual host. |
||
| 57 | This is the pathname of a directory that may contain web applications |
||
| 58 | to be deployed on this virtual host. You may specify an |
||
| 59 | absolute pathname, or a pathname that is relative to the |
||
| 60 | <code>$CATALINA_BASE</code> directory. See |
||
| 61 | <a href="#Automatic_Application_Deployment">Automatic Application |
||
| 62 | Deployment</a> for more information on automatic recognition and |
||
| 63 | deployment of web applications. If not specified, the default of |
||
| 64 | <code>webapps</code> will be used.</p> |
||
| 65 | </td></tr><tr id="Attributes_Common Attributes_xmlBase"><td><code class="attributeName">xmlBase</code></td><td> |
||
| 66 | <p>The <em>XML Base</em> directory for this virtual host. |
||
| 67 | This is the pathname of a directory that may contain context XML |
||
| 68 | descriptors to be deployed on this virtual host. You may specify an |
||
| 69 | absolute pathname for this directory, or a pathname that is relative |
||
| 70 | to the <code>$CATALINA_BASE</code> directory. See |
||
| 71 | <a href="#Automatic_Application_Deployment">Automatic Application |
||
| 72 | Deployment</a> for more information on automatic recognition and |
||
| 73 | deployment of web applications. If not specified the default of |
||
| 74 | <code>conf/<engine_name>/<host_name></code> will be used.</p> |
||
| 75 | </td></tr><tr id="Attributes_Common Attributes_createDirs"><td><code class="attributeName">createDirs</code></td><td> |
||
| 76 | <p>If set to <code>true</code>, Tomcat will attempt to create the |
||
| 77 | directories defined by the attributes <code>appBase</code> and |
||
| 78 | <code>xmlBase</code> during the startup phase. The default value is |
||
| 79 | <code>true</code>. If set to <code>true</code>, and directory creation |
||
| 80 | fails, an error message will be printed out but will not halt the |
||
| 81 | startup sequence.</p> |
||
| 82 | </td></tr><tr id="Attributes_Common Attributes_autoDeploy"><td><code class="attributeName">autoDeploy</code></td><td> |
||
| 83 | <p>This flag value indicates if Tomcat should check periodically for new |
||
| 84 | or updated web applications while Tomcat is running. If |
||
| 85 | <code>true</code>, Tomcat periodically checks the <code>appBase</code> |
||
| 86 | and <code>xmlBase</code> directories and deploys any new web |
||
| 87 | applications or context XML descriptors found. Updated web applications |
||
| 88 | or context XML descriptors will trigger a reload of the web application. |
||
| 89 | The default is <code>true</code>. See |
||
| 90 | <a href="#Automatic_Application_Deployment">Automatic Application |
||
| 91 | Deployment</a> for more information.</p> |
||
| 92 | </td></tr><tr id="Attributes_Common Attributes_backgroundProcessorDelay"><td><code class="attributeName">backgroundProcessorDelay</code></td><td> |
||
| 93 | <p>This value represents the delay in seconds between the |
||
| 94 | invocation of the backgroundProcess method on this host and |
||
| 95 | its child containers, including all contexts. |
||
| 96 | Child containers will not be invoked if their delay value is not |
||
| 97 | negative (which would mean they are using their own processing |
||
| 98 | thread). Setting this to a positive value will cause |
||
| 99 | a thread to be spawn. After waiting the specified amount of time, |
||
| 100 | the thread will invoke the backgroundProcess method on this host |
||
| 101 | and all its child containers. A host will use background processing to |
||
| 102 | perform live web application deployment related tasks. If not |
||
| 103 | specified, the default value for this attribute is -1, which means |
||
| 104 | the host will rely on the background processing setting of its parent |
||
| 105 | engine.</p> |
||
| 106 | </td></tr><tr id="Attributes_Common Attributes_className"><td><code class="attributeName">className</code></td><td> |
||
| 107 | <p>Java class name of the implementation to use. This class must |
||
| 108 | implement the <code>org.apache.catalina.Host</code> interface. |
||
| 109 | If not specified, the standard value (defined below) will be used.</p> |
||
| 110 | </td></tr><tr id="Attributes_Common Attributes_deployIgnore"><td><code class="attributeName">deployIgnore</code></td><td> |
||
| 111 | <p>A regular expression defining paths to ignore when |
||
| 112 | <code>autoDeploy</code> and <code>deployOnStartup</code> are set. This |
||
| 113 | allows you to keep your configuration in a version control system, for |
||
| 114 | example, and not deploy a <code>.svn</code>, <code>.git</code> or other |
||
| 115 | configuration control system folder that happens to be in the |
||
| 116 | <code>appBase</code>.</p> |
||
| 117 | <p>This regular expression is relative to <code>appBase</code>. It is |
||
| 118 | also <em>anchored</em>, meaning the match is performed against the |
||
| 119 | entire file/directory name. So, <code>foo</code> matches only a file or |
||
| 120 | directory named <code>foo</code> but not <code>foo.war</code>, |
||
| 121 | <code>foobar</code>, or <code>myfooapp</code>. To match anything with |
||
| 122 | "foo", you could use <code>.*foo.*</code>.</p> |
||
| 123 | <p>See <a href="#Automatic_Application_Deployment">Automatic Application |
||
| 124 | Deployment</a> for more information.</p> |
||
| 125 | </td></tr><tr id="Attributes_Common Attributes_deployOnStartup"><td><code class="attributeName">deployOnStartup</code></td><td> |
||
| 126 | <p>This flag value indicates if web applications from this host should |
||
| 127 | be automatically deployed when Tomcat starts. The default is |
||
| 128 | <code>true</code>. See |
||
| 129 | <a href="#Automatic_Application_Deployment">Automatic Application |
||
| 130 | Deployment</a> for more information.</p> |
||
| 131 | </td></tr><tr id="Attributes_Common Attributes_failCtxIfServletStartFails"><td><code class="attributeName">failCtxIfServletStartFails</code></td><td> |
||
| 132 | <p>Set to <code>true</code> to have each child contexts fail its startup |
||
| 133 | if any of its servlet that has load-on-startup >=0 fails its own |
||
| 134 | startup.</p> |
||
| 135 | <p>Each child context may override this attribute.</p> |
||
| 136 | <p>If not specified, the default value of <code>false</code> is |
||
| 137 | used.</p> |
||
| 138 | </td></tr><tr id="Attributes_Common Attributes_name"><td><strong><code class="attributeName">name</code></strong></td><td> |
||
| 139 | <p>Usually the network name of this virtual host, as registered in your |
||
| 140 | <em>Domain Name Service</em> server. Regardless of the case used to |
||
| 141 | specify the host name, Tomcat will convert it to lower case internally. |
||
| 142 | One of the Hosts nested within an <a href="engine.html">Engine</a> MUST |
||
| 143 | have a name that matches the <code>defaultHost</code> setting for that |
||
| 144 | Engine. See <a href="#Host_Name_Aliases">Host Name Aliases</a> for |
||
| 145 | information on how to assign more than one network name to the same |
||
| 146 | virtual host. The name can not contain a wildcard, this is only |
||
| 147 | valid in an Alias.</p> |
||
| 148 | </td></tr><tr id="Attributes_Common Attributes_startStopThreads"><td><code class="attributeName">startStopThreads</code></td><td> |
||
| 149 | <p>The number of threads this <strong>Host</strong> will use to start |
||
| 150 | child <a href="context.html">Context</a> elements in parallel. The same |
||
| 151 | thread pool will be used to deploy new |
||
| 152 | <a href="context.html">Context</a>s if automatic deployment is being |
||
| 153 | used. |
||
| 154 | As the thread pool is shared at the Server level, if more than one |
||
| 155 | Host specifies this setting, only the maximum value will apply and will |
||
| 156 | be used for all except for the special value 1. If |
||
| 157 | not specified, the default value of 1 will be used. If 1 thread is |
||
| 158 | used then rather than using an <code>ExecutorService</code> the current |
||
| 159 | thread will be used.</p> |
||
| 160 | </td></tr><tr id="Attributes_Common Attributes_undeployOldVersions"><td><code class="attributeName">undeployOldVersions</code></td><td> |
||
| 161 | <p>This flag determines if Tomcat, as part of the auto deployment |
||
| 162 | process, will check for old, unused versions of web applications |
||
| 163 | deployed using parallel deployment and, if any are found, remove them. |
||
| 164 | This flag only applies if <code>autoDeploy</code> is <code>true</code>. |
||
| 165 | If not specified the default value of <code>false</code> will be used. |
||
| 166 | </p> |
||
| 167 | </td></tr></table> |
||
| 168 | |||
| 169 | </div></div> |
||
| 170 | |||
| 171 | |||
| 172 | <div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text"> |
||
| 173 | |||
| 174 | <p>The standard implementation of <strong>Host</strong> is |
||
| 175 | <strong>org.apache.catalina.core.StandardHost</strong>. |
||
| 176 | It supports the following additional attributes (in addition to the |
||
| 177 | common attributes listed above):</p> |
||
| 178 | |||
| 179 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 180 | Attribute |
||
| 181 | </th><th style="width: 85%;"> |
||
| 182 | Description |
||
| 183 | </th></tr><tr id="Attributes_Standard Implementation_copyXML"><td><code class="attributeName">copyXML</code></td><td> |
||
| 184 | <p>Set to <code>true</code> if you want a context XML descriptor |
||
| 185 | embedded inside the application (located at |
||
| 186 | <code>/META-INF/context.xml</code>) to be copied to <code>xmlBase</code> |
||
| 187 | when the application is deployed. On subsequent starts, the copied |
||
| 188 | context XML descriptor will be used in preference to any context XML |
||
| 189 | descriptor embedded inside the application even if the descriptor |
||
| 190 | embedded inside the application is more recent. The default is |
||
| 191 | <code>false</code>. Note if <strong>deployXML</strong> is |
||
| 192 | <code>false</code>, this attribute will have no effect.</p> |
||
| 193 | </td></tr><tr id="Attributes_Standard Implementation_deployXML"><td><code class="attributeName">deployXML</code></td><td> |
||
| 194 | <p>Set to <code>false</code> if you want to disable parsing the context |
||
| 195 | XML descriptor embedded inside the application (located at |
||
| 196 | <code>/META-INF/context.xml</code>). Security conscious environments |
||
| 197 | should set this to <code>false</code> to prevent applications from |
||
| 198 | interacting with the container's configuration. The administrator will |
||
| 199 | then be responsible for providing an external context configuration |
||
| 200 | file, and putting it in the location defined by the |
||
| 201 | <strong>xmlBase</strong> attribute. If this flag is <code>false</code>, |
||
| 202 | a descriptor is located at <code>/META-INF/context.xml</code> and no |
||
| 203 | descriptor is present in <strong>xmlBase</strong> then the context will |
||
| 204 | fail to start in case the descriptor contains necessary configuration |
||
| 205 | for secure deployment (such as a RemoteCIDRValve) which should not be |
||
| 206 | ignored. The default is <code>true</code> unless a security manager is |
||
| 207 | enabled when the default is <code>false</code>. When running under a |
||
| 208 | security manager this may be enabled on a per web application basis by |
||
| 209 | granting the |
||
| 210 | <code>org.apache.catalina.security.DeployXmlPermission</code> to the web |
||
| 211 | application. The Manager and Host Manager applications are granted this |
||
| 212 | permission by default so that they continue to work when running under a |
||
| 213 | security manager.</p> |
||
| 214 | </td></tr><tr id="Attributes_Standard Implementation_errorReportValveClass"><td><code class="attributeName">errorReportValveClass</code></td><td> |
||
| 215 | <p>Java class name of the error reporting valve which will be used |
||
| 216 | by this Host. The responsibility of this valve is to output error |
||
| 217 | reports. Setting this property allows to customize the look of the |
||
| 218 | error pages which will be generated by Tomcat. This class must |
||
| 219 | implement the |
||
| 220 | <code>org.apache.catalina.Valve</code> interface. If none is specified, |
||
| 221 | the value <code>org.apache.catalina.valves.ErrorReportValve</code> |
||
| 222 | will be used by default. if set to an empty string, the error report |
||
| 223 | will be disabled.</p> |
||
| 224 | </td></tr><tr id="Attributes_Standard Implementation_unpackWARs"><td><code class="attributeName">unpackWARs</code></td><td> |
||
| 225 | <p>Set to <code>true</code> if you want web applications that are |
||
| 226 | placed in the <code>appBase</code> directory as web application |
||
| 227 | archive (WAR) files to be unpacked into a corresponding disk directory |
||
| 228 | structure, <code>false</code> to run such web applications directly |
||
| 229 | from a WAR file. The default is <code>true</code>. See |
||
| 230 | <a href="#Automatic_Application_Deployment">Automatic Application |
||
| 231 | Deployment</a> for more information.</p> |
||
| 232 | <p>Note: If Tomcat expands the WAR file then it will add a file |
||
| 233 | (<code>/META-INF/war-tracker</code>) to the unpacked directory |
||
| 234 | structure which it uses to detect changes in the WAR file while Tomcat |
||
| 235 | is not running. Any such change will trigger the deletion of the |
||
| 236 | expanded directory and the deployment of the updated WAR file when |
||
| 237 | Tomcat next starts.</p> |
||
| 238 | <p>Note: Running with this option set to <code>false</code> will incur |
||
| 239 | a performance penalty. To avoid a significant performance penalty, the |
||
| 240 | web application should be configured such that class scanning for |
||
| 241 | Servlet 3.0+ pluggability features is not required. Users may also wish |
||
| 242 | to consider the <strong>ExtractingRoot</strong> |
||
| 243 | <a href="resources.html">Resources</a> implementation.</p> |
||
| 244 | </td></tr><tr id="Attributes_Standard Implementation_workDir"><td><code class="attributeName">workDir</code></td><td> |
||
| 245 | <p>Pathname to a scratch directory to be used by applications for |
||
| 246 | this Host. Each application will have its own sub directory with |
||
| 247 | temporary read-write use. Configuring a Context workDir will override |
||
| 248 | use of the Host workDir configuration. This directory will be made |
||
| 249 | visible to servlets in the web application by a servlet context |
||
| 250 | attribute (of type <code>java.io.File</code>) named |
||
| 251 | <code>javax.servlet.context.tempdir</code> as described in the |
||
| 252 | Servlet Specification. If not specified, a suitable directory |
||
| 253 | underneath <code>$CATALINA_BASE/work</code> will be provided.</p> |
||
| 254 | </td></tr></table> |
||
| 255 | |||
| 256 | </div></div> |
||
| 257 | |||
| 258 | |||
| 259 | </div><h3 id="Nested_Components">Nested Components</h3><div class="text"> |
||
| 260 | |||
| 261 | <p>You can nest one or more <a href="context.html">Context</a> elements |
||
| 262 | inside this <strong>Host</strong> element, each representing a different web |
||
| 263 | application associated with this virtual host.</p> |
||
| 264 | |||
| 265 | <p>You can nest at most one instance of the following utility components |
||
| 266 | by nesting a corresponding element inside your <strong>Host</strong> |
||
| 267 | element:</p> |
||
| 268 | <ul> |
||
| 269 | <li><a href="realm.html"><strong>Realm</strong></a> - |
||
| 270 | Configure a realm that will allow its |
||
| 271 | database of users, and their associated roles, to be shared across all |
||
| 272 | <a href="context.html">Contexts</a> nested inside this Host (unless |
||
| 273 | overridden by a <a href="realm.html">Realm</a> configuration |
||
| 274 | at a lower level).</li> |
||
| 275 | </ul> |
||
| 276 | |||
| 277 | </div><h3 id="Special_Features">Special Features</h3><div class="text"> |
||
| 278 | |||
| 279 | |||
| 280 | <div class="subsection"><h4 id="Logging">Logging</h4><div class="text"> |
||
| 281 | |||
| 282 | <p>A host is associated with the |
||
| 283 | <code>org.apache.catalina.core.ContainerBase.[engine_name].[host_name]</code> |
||
| 284 | log category. Note that the brackets are part of the name, |
||
| 285 | don't omit them.</p> |
||
| 286 | |||
| 287 | </div></div> |
||
| 288 | |||
| 289 | |||
| 290 | <div class="subsection"><h4 id="Access_Logs">Access Logs</h4><div class="text"> |
||
| 291 | |||
| 292 | <p>When you run a web server, one of the output files normally generated |
||
| 293 | is an <em>access log</em>, which generates one line of information for |
||
| 294 | each request processed by the server, in a standard format. Catalina |
||
| 295 | includes an optional <a href="valve.html">Valve</a> implementation that |
||
| 296 | can create access logs in the same standard format created by web servers, |
||
| 297 | or in any number of custom formats.</p> |
||
| 298 | |||
| 299 | <p>You can ask Catalina to create an access log for all requests |
||
| 300 | processed by an <a href="engine.html">Engine</a>, |
||
| 301 | <a href="host.html">Host</a>, or <a href="context.html">Context</a> |
||
| 302 | by nesting a <a href="valve.html">Valve</a> element like this:</p> |
||
| 303 | |||
| 304 | <div class="codeBox"><pre><code><Host name="localhost" ...> |
||
| 305 | ... |
||
| 306 | <Valve className="org.apache.catalina.valves.AccessLogValve" |
||
| 307 | prefix="localhost_access_log" suffix=".txt" |
||
| 308 | pattern="common"/> |
||
| 309 | ... |
||
| 310 | </Host></code></pre></div> |
||
| 311 | |||
| 312 | <p>See <a href="valve.html#Access_Logging">Access Logging Valves</a> |
||
| 313 | for more information on the configuration attributes that are |
||
| 314 | supported.</p> |
||
| 315 | |||
| 316 | </div></div> |
||
| 317 | |||
| 318 | |||
| 319 | <div class="subsection"><h4 id="Automatic_Application_Deployment">Automatic Application Deployment</h4><div class="text"> |
||
| 320 | |||
| 321 | <p>If you are using the standard <strong>Host</strong> implementation with |
||
| 322 | default settings then applications in the <em>appBase</em> or with context |
||
| 323 | files in the <em>configBase</em> are automatically deployed when Tomcat |
||
| 324 | starts (the <code>deployOnStartup</code> property defaults to |
||
| 325 | <code>true</code>) and reloaded or redeployed (as appropriate) when a change |
||
| 326 | is detected while Tomcat is running (the <code>autoDeploy</code> attribute |
||
| 327 | also defaults to <code>true</code>).</p> |
||
| 328 | |||
| 329 | <p><code>deployOnStartup</code> and <code>autoDeploy</code> trigger |
||
| 330 | execution of exactly the same code so the behaviour is very similar. |
||
| 331 | However, there is one key difference. When Tomcat starts it has no knowledge |
||
| 332 | of which files are the same, which have been changed and which are new. It |
||
| 333 | therefore treats all files as new. While Tomcat is running, it can |
||
| 334 | differentiate between unchanged, modified and new files. This leads to some |
||
| 335 | differences in behaviour between files being modified while Tomcat is |
||
| 336 | running and files being modified while Tomcat is stopped.</p> |
||
| 337 | |||
| 338 | <p>When you use automatic deployment, related files (a web application may |
||
| 339 | have a context.xml file, a WAR and a directory) that exist in the |
||
| 340 | <strong>Host</strong>'s <em>appBase</em> and/or <em>configBase</em> |
||
| 341 | must conform to the expected <a href="context.html#Naming">naming |
||
| 342 | convention</a>. In short, this means files for the same web application must |
||
| 343 | share the same <em>base name</em>.</p> |
||
| 344 | |||
| 345 | <p>The automatic deployment process identifies new and/or modified web |
||
| 346 | applications using the following search order:</p> |
||
| 347 | |||
| 348 | <ol> |
||
| 349 | <li>Web applications with a context.xml file located in the Host's |
||
| 350 | <em>configBase</em>.</li> |
||
| 351 | <li>Web applications with a WAR file located in the Host's |
||
| 352 | <em>appBase</em> that have not already been identified during the scan for |
||
| 353 | context.xml files.</li> |
||
| 354 | <li>Web applications with a directory located in the Host's |
||
| 355 | <em>appBase</em> that have not already been identified during the scans |
||
| 356 | for context.xml and/or WAR files.</li> |
||
| 357 | </ol> |
||
| 358 | |||
| 359 | <p>When <code>autoDeploy</code> is <code>true</code>, the automatic |
||
| 360 | deployment process will monitor the deployed web applications for changes. |
||
| 361 | Depending on exactly what changes, the web application will either be |
||
| 362 | re-deployed or reloaded. Re-deployment involves the creation of a new web |
||
| 363 | application and, if using the standard session manager, user sessions will |
||
| 364 | not be retained. Reloading uses the existing web application but re-parses |
||
| 365 | the web.xml and reloads any classes. If using the standard session manager, |
||
| 366 | user sessions will be persisted.</p> |
||
| 367 | |||
| 368 | <p>Users may add to the files that the automatic deployment process monitors |
||
| 369 | for reloading (i.e. any change to one of these files triggers a reload of |
||
| 370 | the web application) by adding a <em>WatchedResources</em> element to the |
||
| 371 | context.xml file. See the |
||
| 372 | <a href="context.html#Nested_Components">Context</a> documentation for |
||
| 373 | further details.</p> |
||
| 374 | |||
| 375 | <p>When using automatic deployment, the <code>docBase</code> defined by |
||
| 376 | an XML <a href="context.html">Context</a> file should be outside of the |
||
| 377 | <code>appBase</code> directory. If this is not the case, difficulties |
||
| 378 | may be experienced deploying the web application or the application may |
||
| 379 | be deployed twice. The <code>deployIgnore</code> attribute can be used |
||
| 380 | to avoid this situation.</p> |
||
| 381 | |||
| 382 | <p>Note that if you are defining contexts explicitly in server.xml, you |
||
| 383 | should probably turn off automatic application deployment or specify |
||
| 384 | <code>deployIgnore</code> carefully. Otherwise, the web applications |
||
| 385 | will each be deployed twice, and that may cause problems for the |
||
| 386 | applications.</p> |
||
| 387 | |||
| 388 | <p>There are many possible combinations of settings, new files, changed |
||
| 389 | files and deleted files. A separate page describes the |
||
| 390 | <a href="automatic-deployment.html">expected behaviour of the automatic |
||
| 391 | deployment process</a> in many of these scenarios.</p> |
||
| 392 | |||
| 393 | </div></div> |
||
| 394 | |||
| 395 | |||
| 396 | <div class="subsection"><h4 id="Host_Name_Aliases">Host Name Aliases</h4><div class="text"> |
||
| 397 | |||
| 398 | <p>In many server environments, Network Administrators have configured |
||
| 399 | more than one network name (in the <em>Domain Name Service</em> (DNS) |
||
| 400 | server), that resolve to the IP address of the same server. Normally, |
||
| 401 | each such network name would be configured as a separate |
||
| 402 | <strong>Host</strong> element in <code>conf/server.xml</code>, each |
||
| 403 | with its own set of web applications.</p> |
||
| 404 | |||
| 405 | <p>However, in some circumstances, it is desirable that two or more |
||
| 406 | network names should resolve to the <strong>same</strong> virtual host, |
||
| 407 | running the same set of applications. A common use case for this |
||
| 408 | scenario is a corporate web site, where it is desirable that users |
||
| 409 | be able to utilize either <code>www.mycompany.com</code> or |
||
| 410 | <code>company.com</code> to access exactly the same content and |
||
| 411 | applications.</p> |
||
| 412 | |||
| 413 | <p>This is accomplished by utilizing one or more <strong>Alias</strong> |
||
| 414 | elements nested inside your <strong>Host</strong> element. For |
||
| 415 | example:</p> |
||
| 416 | <div class="codeBox"><pre><code><Host name="www.mycompany.com" ...> |
||
| 417 | ... |
||
| 418 | <Alias>mycompany.com</Alias> |
||
| 419 | ... |
||
| 420 | </Host></code></pre></div> |
||
| 421 | |||
| 422 | <p>In order for this strategy to be effective, all of the network names |
||
| 423 | involved must be registered in your DNS server to resolve to the |
||
| 424 | same computer that is running this instance of Catalina.</p> |
||
| 425 | |||
| 426 | <p>Aliases may also use the wildcard form (<code>*.domainname</code>), |
||
| 427 | unlike for the <strong>name</strong> attribute of a <strong>Host</strong>. |
||
| 428 | </p> |
||
| 429 | </div></div> |
||
| 430 | |||
| 431 | |||
| 432 | <div class="subsection"><h4 id="Lifecycle_Listeners">Lifecycle Listeners</h4><div class="text"> |
||
| 433 | |||
| 434 | <p>If you have implemented a Java object that needs to know when this |
||
| 435 | <strong>Host</strong> is started or stopped, you can declare it by |
||
| 436 | nesting a <strong>Listener</strong> element inside this element. The |
||
| 437 | class name you specify must implement the |
||
| 438 | <code>org.apache.catalina.LifecycleListener</code> interface, and |
||
| 439 | it will be notified about the occurrence of the corresponding |
||
| 440 | lifecycle events. Configuration of such a listener looks like this:</p> |
||
| 441 | |||
| 442 | <div class="codeBox"><pre><code><Host name="localhost" ...> |
||
| 443 | ... |
||
| 444 | <Listener className="com.mycompany.mypackage.MyListener" ... > |
||
| 445 | ... |
||
| 446 | </Host></code></pre></div> |
||
| 447 | |||
| 448 | <p>Note that a Listener can have any number of additional properties |
||
| 449 | that may be configured from this element. Attribute names are matched |
||
| 450 | to corresponding JavaBean property names using the standard property |
||
| 451 | method naming patterns.</p> |
||
| 452 | |||
| 453 | </div></div> |
||
| 454 | |||
| 455 | |||
| 456 | <div class="subsection"><h4 id="Request_Filters">Request Filters</h4><div class="text"> |
||
| 457 | |||
| 458 | <p>You can ask Catalina to check the IP address, or host name, on every |
||
| 459 | incoming request directed to the surrounding |
||
| 460 | <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or |
||
| 461 | <a href="context.html">Context</a> element. The remote address or name |
||
| 462 | will be checked against configured "accept" and/or "deny" |
||
| 463 | filters, which are defined using <code>java.util.regex</code> Regular |
||
| 464 | Expression syntax. Requests that come from locations that are |
||
| 465 | not accepted will be rejected with an HTTP "Forbidden" error. |
||
| 466 | Example filter declarations:</p> |
||
| 467 | |||
| 468 | <div class="codeBox"><pre><code><Host name="localhost" ...> |
||
| 469 | ... |
||
| 470 | <Valve className="org.apache.catalina.valves.RemoteHostValve" |
||
| 471 | allow=".*\.mycompany\.com|www\.yourcompany\.com"/> |
||
| 472 | <Valve className="org.apache.catalina.valves.RemoteCIDRValve" |
||
| 473 | deny="192.168.1.0/24"/> |
||
| 474 | ... |
||
| 475 | </Host></code></pre></div> |
||
| 476 | |||
| 477 | <p>See <a href="valve.html#Remote_Address_Filter">Remote Address Filter</a> |
||
| 478 | and <a href="valve.html#Remote_Host_Filter">Remote Host Filter</a> for |
||
| 479 | more information about the configuration options that are supported.</p> |
||
| 480 | |||
| 481 | </div></div> |
||
| 482 | |||
| 483 | |||
| 484 | <div class="subsection"><h4 id="Single_Sign_On">Single Sign On</h4><div class="text"> |
||
| 485 | |||
| 486 | <p>In many environments, but particularly in portal environments, it |
||
| 487 | is desirable to have a user challenged to authenticate themselves only |
||
| 488 | once over a set of web applications deployed on a particular virtual |
||
| 489 | host. This can be accomplished by nesting an element like this inside |
||
| 490 | the Host element for this virtual host:</p> |
||
| 491 | |||
| 492 | <div class="codeBox"><pre><code><Host name="localhost" ...> |
||
| 493 | ... |
||
| 494 | <Valve className="org.apache.catalina.authenticator.SingleSignOn"/> |
||
| 495 | ... |
||
| 496 | </Host></code></pre></div> |
||
| 497 | |||
| 498 | <p>The Single Sign On facility operates according to the following rules: |
||
| 499 | </p> |
||
| 500 | <ul> |
||
| 501 | <li>All web applications configured for this virtual host must share the |
||
| 502 | same <a href="realm.html">Realm</a>. In practice, that means you can |
||
| 503 | nest the Realm element inside this Host element (or the surrounding |
||
| 504 | <a href="engine.html">Engine</a> element), but not inside a |
||
| 505 | <a href="context.html">Context</a> element for one of the involved |
||
| 506 | web applications.</li> |
||
| 507 | <li>As long as the user accesses only unprotected resources in any of the |
||
| 508 | web applications on this virtual host, they will not be challenged |
||
| 509 | to authenticate themselves.</li> |
||
| 510 | <li>As soon as the user accesses a protected resource in |
||
| 511 | <strong>any</strong> web application associated with this virtual |
||
| 512 | host, the user will be challenged to authenticate himself or herself, |
||
| 513 | using the login method defined for the web application currently |
||
| 514 | being accessed.</li> |
||
| 515 | <li>Once authenticated, the roles associated with this user will be |
||
| 516 | utilized for access control decisions across <strong>all</strong> |
||
| 517 | of the associated web applications, without challenging the user |
||
| 518 | to authenticate themselves to each application individually.</li> |
||
| 519 | <li>As soon as the user logs out of one web application (for example, |
||
| 520 | by invalidating the corresponding session if form |
||
| 521 | based login is used), the user's sessions in <strong>all</strong> |
||
| 522 | web applications will be invalidated. Any subsequent attempt to |
||
| 523 | access a protected resource in any application will require the |
||
| 524 | user to authenticate himself or herself again.</li> |
||
| 525 | <li>The Single Sign On feature utilizes HTTP cookies to transmit a token |
||
| 526 | that associates each request with the saved user identity, so it can |
||
| 527 | only be utilized in client environments that support cookies.</li> |
||
| 528 | </ul> |
||
| 529 | |||
| 530 | </div></div> |
||
| 531 | |||
| 532 | |||
| 533 | <div class="subsection"><h4 id="User_Web_Applications">User Web Applications</h4><div class="text"> |
||
| 534 | |||
| 535 | <p>Many web servers can automatically map a request URI starting with |
||
| 536 | a tilde character ("~") and a username to a directory (commonly named |
||
| 537 | <code>public_html</code>) in that user's home directory on the server. |
||
| 538 | You can accomplish the same thing in Catalina by using a special |
||
| 539 | <strong>Listener</strong> element like this (on a Unix system that |
||
| 540 | uses the <code>/etc/passwd</code> file to identify valid users):</p> |
||
| 541 | |||
| 542 | <div class="codeBox"><pre><code><Host name="localhost" ...> |
||
| 543 | ... |
||
| 544 | <Listener className="org.apache.catalina.startup.UserConfig" |
||
| 545 | directoryName="public_html" |
||
| 546 | userClass="org.apache.catalina.startup.PasswdUserDatabase"/> |
||
| 547 | ... |
||
| 548 | </Host></code></pre></div> |
||
| 549 | |||
| 550 | <p>On a server where <code>/etc/passwd</code> is not in use, you can |
||
| 551 | request Catalina to consider all directories found in a specified base |
||
| 552 | directory (such as <code>c:\Homes</code> in this example) to be |
||
| 553 | considered "user home" directories for the purposes of this directive:</p> |
||
| 554 | |||
| 555 | <div class="codeBox"><pre><code><Host name="localhost" ...> |
||
| 556 | ... |
||
| 557 | <Listener className="org.apache.catalina.startup.UserConfig" |
||
| 558 | directoryName="public_html" |
||
| 559 | homeBase="c:\Homes" |
||
| 560 | userClass="org.apache.catalina.startup.HomesUserDatabase"/> |
||
| 561 | ... |
||
| 562 | </Host></code></pre></div> |
||
| 563 | |||
| 564 | <p>If a user home directory has been set up for a user named |
||
| 565 | <code>craigmcc</code>, then its contents will be visible from a |
||
| 566 | client browser by making a request to a URL like:</p> |
||
| 567 | |||
| 568 | <div class="codeBox"><pre><code>http://www.mycompany.com:8080/~craigmcc</code></pre></div> |
||
| 569 | |||
| 570 | <p>Successful use of this feature requires recognition of the following |
||
| 571 | considerations:</p> |
||
| 572 | <ul> |
||
| 573 | <li>Each user web application will be deployed with characteristics |
||
| 574 | established by the global and host level default context settings.</li> |
||
| 575 | <li>It is legal to include more than one instance of this Listener |
||
| 576 | element. This would only be useful, however, in circumstances |
||
| 577 | where you wanted to configure more than one "homeBase" directory.</li> |
||
| 578 | <li>The operating system username under which Catalina is executed |
||
| 579 | MUST have read access to each user's web application directory, |
||
| 580 | and all of its contents.</li> |
||
| 581 | </ul> |
||
| 582 | |||
| 583 | </div></div> |
||
| 584 | |||
| 585 | <div class="subsection"><h4 id="Custom_context.xml_and_web.xml">Custom context.xml and web.xml</h4><div class="text"> |
||
| 586 | <p>You can override the default values found in <code>conf/context.xml</code> and |
||
| 587 | <code>conf/web.xml</code> files from <code>$CATALINA_BASE</code> for each virtual host. |
||
| 588 | Tomcat will look for files named <code>context.xml.default</code> and <code>web.xml.default</code> |
||
| 589 | in the directory specified by <code>xmlBase</code> and merge the files into |
||
| 590 | those found in the default ones.</p> |
||
| 591 | </div></div> |
||
| 592 | |||
| 593 | </div></div></div></div></div><footer><div id="footer"> |
||
| 594 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 595 | <br> |
||
| 596 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 597 | are either registered trademarks or trademarks of the Apache Software |
||
| 598 | Foundation. |
||
| 599 | </div></footer></div></body></html> |