Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 67d615191938bb60e9b73af6701f5339749950ca / . / tomcat-cas / webapps / docs / config / host.html
blob: cc66f0345e6a231c615fa8ebf32a67da2ab9947f [file] [log] [blame]
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.41) - The Host Container</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Remy Maucherat"><meta name="author" content="Yoav Shapira"><style type="text/css" media="print">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
5 The Apache Tomcat Servlet/JSP Container
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><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><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</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="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><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><p><strong>web.xml</strong></p><ul><li><a href="filter.html">Filter</a></li></ul><p><strong>Other</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat Configuration Reference</h1><h2>The Host Container</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]7<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></ol></li></ul>
8</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
9
10 <p>The <strong>Host</strong> element represents a <em>virtual host</em>,
11 which is an association of a network name for a server (such as
12 "www.mycompany.com" with the particular server on which Catalina is
13 running. In order to be effective, this name must be registered in the
14 <em>Domain Name Service</em> (DNS) server that manages the Internet
15 domain you belong to - contact your Network Administrator for more
16 information.</p>
17
18 <p>In many cases, System Administrators wish to associate more than
19 one network name (such as <code>www.mycompany.com</code> and
20 <code>company.com</code>) with the same virtual host and applications.
21 This can be accomplished using the <a href="#Host Name Aliases">Host
22 Name Aliases</a> feature discussed below.</p>
23
24 <p>One or more <strong>Host</strong> elements are nested inside an
25 <a href="engine.html">Engine</a> element. Inside the Host element, you
26 can nest <a href="context.html">Context</a> elements for the web
27 applications associated with this virtual host. Exactly one of the Hosts
28 associated with each Engine MUST have a name matching the
29 <code>defaultHost</code> attribute of that Engine.</p>
30
31 <blockquote><em>
32 <p>The description below uses the variable name $CATALINA_BASE to refer the
33 base directory against which most relative paths are resolved. If you have
34 not configured Tomcat for multiple instances by setting a CATALINA_BASE
35 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
36 the directory into which you have installed Tomcat.</p>
37 </em></blockquote>
38
39</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
40
41 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
42
43 <p>All implementations of <strong>Host</strong>
44 support the following attributes:</p>
45
46 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code>appBase</code></strong></td><td align="left" valign="center">
47 <p>The <em>Application Base</em> directory for this virtual host.
48 This is the pathname of a directory that may contain web applications
49 to be deployed on this virtual host. You may specify an
50 absolute pathname, or a pathname that is relative to the
51 <code>$CATALINA_BASE</code> directory. See
52 <a href="#Automatic_Application_Deployment">Automatic Application
53 Deployment</a> for more information on automatic recognition and
54 deployment of web applications. If not specified, the default of
55 <code>webapps</code> will be used.</p>
56 </td></tr><tr><td align="left" valign="center"><code>autoDeploy</code></td><td align="left" valign="center">
57 <p>This flag value indicates if Tomcat should check periodically for new
58 or updated web applications while Tomcat is running. If true, Tomcat
59 periodically checks the <code>appBase</code> and
60 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code>
61 directories and deploys any new web applications or context XML
62 descriptors found. Updated web applications or context XML descriptors
63 will trigger a reload of the web application. The flag's value defaults
64 to true. See
65 <a href="#Automatic_Application_Deployment">Automatic Application
66 Deployment</a> for more information.</p>
67 </td></tr><tr><td align="left" valign="center"><code>backgroundProcessorDelay</code></td><td align="left" valign="center">
68 <p>This value represents the delay in seconds between the
69 invocation of the backgroundProcess method on this host and
70 its child containers, including all contexts.
71 Child containers will not be invoked if their delay value is not
72 negative (which would mean they are using their own processing
73 thread). Setting this to a positive value will cause
74 a thread to be spawn. After waiting the specified amount of time,
75 the thread will invoke the backgroundProcess method on this host
76 and all its child containers. A host will use background processing to
77 perform live web application deployment related tasks. If not
78 specified, the default value for this attribute is -1, which means
79 the host will rely on the background processing thread of its parent
80 engine.</p>
81 </td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
82 <p>Java class name of the implementation to use. This class must
83 implement the <code>org.apache.catalina.Host</code> interface.
84 If not specified, the standard value (defined below) will be used.</p>
85 </td></tr><tr><td align="left" valign="center"><code>deployIgnore</code></td><td align="left" valign="center">
86 <p>A regular expression defining paths to ignore when
87 <code>autoDeploy</code> and <code>deployOnStartup</code> are set. This
88 allows you to keep your configuration in a version control system, for
89 example, and not deploy a .svn or CVS folder that happens to be in the
90 <code>appBase</code>.</p>
91 <p>This regular expression is relative to <code>appBase</code>. It is
92 also <em>anchored</em>, meaning the match is performed against the
93 entire file/directory name. So, <code>foo</code> matches only a file or
94 directory named <code>foo</code> but not <code>foo.war</code>,
95 <code>foobar</code>, or <code>myfooapp</code>. To match anything with
96 "foo", you could use <code>.*foo.*</code>.</p>
97 <p>See <a href="#Automatic_Application_Deployment">Automatic Application
98 Deployment</a> for more information.</p>
99 </td></tr><tr><td align="left" valign="center"><code>deployOnStartup</code></td><td align="left" valign="center">
100 <p>This flag value indicates if web applications from this host should
101 be automatically deployed when Tomcat starts. The flag's value defaults
102 to true. See
103 <a href="#Automatic_Application_Deployment">Automatic Application
104 Deployment</a> for more information.</p>
105 </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
106 <p>Network name of this virtual host, as registered in your
107 <em>Domain Name Service</em> server. Regardless of the case used to
108 specify the hostname, Tomcat will convert it to lower case internally.
109 One of the Hosts nested within an <a href="engine.html">Engine</a> MUST
110 have a name that matches the <code>defaultHost</code> setting for that
111 Engine. See <a href="#Host Name Aliases">Host Name Aliases</a> for
112 information on how to assign more than one network name to the same
113 virtual host.</p>
114 </td></tr></table>
115
116 </blockquote></td></tr></table>
117
118
119 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
120
121 <p>The standard implementation of <strong>Host</strong> is
122 <strong>org.apache.catalina.core.StandardHost</strong>.
123 It supports the following additional attributes (in addition to the
124 common attributes listed above):</p>
125
126 <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>deployXML</code></td><td align="left" valign="center">
127 <p>Set to <code>false</code> if you want to disable parsing the context
128 XML descriptor embedded inside the application (located at
129 <code>/META-INF/context.xml</code>). Security conscious environments
130 should set this to <code>false</code> to prevent applications from
131 interacting with the container's configuration. The administrator will
132 then be responsible for providing an external context configuration
133 file, and putting it in
134 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code>. The flag's
135 value defaults to <code>true</code>.</p>
136 </td></tr><tr><td align="left" valign="center"><code>errorReportValveClass</code></td><td align="left" valign="center">
137 <p>Java class name of the error reporting valve which will be used
138 by this Host. The responsibility of this valve is to output error
139 reports. Setting this property allows to customize the look of the
140 error pages which will be generated by Tomcat. This class must
141 implement the
142 <code>org.apache.catalina.Valve</code> interface. If none is specified,
143 the value <code>org.apache.catalina.valves.ErrorReportValve</code>
144 will be used by default.</p>
145 </td></tr><tr><td align="left" valign="center"><code>unpackWARs</code></td><td align="left" valign="center">
146 <p>Set to <code>true</code> if you want web applications that are
147 placed in the <code>appBase</code> directory as web application
148 archive (WAR) files to be unpacked into a corresponding disk directory
149 structure, <code>false</code> to run such web applications directly
150 from a WAR file. WAR files located outside of the Host's
151 <strong>appBase</strong> will not be expanded. See
152 <a href="#Automatic_Application_Deployment">Automatic Application
153 Deployment</a> for more information.</p>
154 </td></tr><tr><td align="left" valign="center"><code>workDir</code></td><td align="left" valign="center">
155 <p>Pathname to a scratch directory to be used by applications for
156 this Host. Each application will have its own sub directory with
157 temporary read-write use. Configuring a Context workDir will override
158 use of the Host workDir configuration. This directory will be made
159 visible to servlets in the web application by a servlet context
160 attribute (of type <code>java.io.File</code>) named
161 <code>javax.servlet.context.tempdir</code> as described in the
162 Servlet Specification. If not specified, a suitable directory
163 underneath <code>$CATALINA_BASE/work</code> will be provided.</p>
164 </td></tr></table>
165
166 </blockquote></td></tr></table>
167
168
169</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
170
171 <p>You can nest one or more <a href="context.html">Context</a> elements
172 inside this <strong>Host</strong> element, each representing a different web
173 application associated with this virtual host.</p>
174
175 <p>You can nest at most one instance of the following utility components
176 by nesting a corresponding element inside your <strong>Host</strong>
177 element:</p>
178 <ul>
179 <li><a href="realm.html"><strong>Realm</strong></a> -
180 Configure a realm that will allow its
181 database of users, and their associated roles, to be shared across all
182 <a href="context.html">Contexts</a> nested inside this Host (unless
183 overridden by a <a href="realm.html">Realm</a> configuration
184 at a lower level).</li>
185 </ul>
186
187</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
188
189
190 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote>
191
192 <p>A host is associated with the
193 <code>org.apache.catalina.core.ContainerBase.[engine_name].[host_name]</code>
194 log category. Note that the brackets are part of the name,
195 don't omit them.</p>
196
197 </blockquote></td></tr></table>
198
199
200 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access Logs"><!--()--></a><a name="Access_Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote>
201
202 <p>When you run a web server, one of the output files normally generated
203 is an <em>access log</em>, which generates one line of information for
204 each request processed by the server, in a standard format. Catalina
205 includes an optional <a href="valve.html">Valve</a> implementation that
206 can create access logs in the same standard format created by web servers,
207 or in any number of custom formats.</p>
208
209 <p>You can ask Catalina to create an access log for all requests
210 processed by an <a href="engine.html">Engine</a>,
211 <a href="host.html">Host</a>, or <a href="context.html">Context</a>
212 by nesting a <a href="valve.html">Valve</a> element like this:</p>
213
214<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
215&lt;Host name="localhost" ...&gt;
216 ...
217 &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
218 prefix="localhost_access_log." suffix=".txt"
219 pattern="common"/&gt;
220 ...
221&lt;/Host&gt;
222</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
223
224 <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
225 for more information on the configuration attributes that are
226 supported.</p>
227
228 </blockquote></td></tr></table>
229
230
231 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Automatic Application Deployment"><!--()--></a><a name="Automatic_Application_Deployment"><strong>Automatic Application Deployment</strong></a></font></td></tr><tr><td><blockquote>
232
233 <p>If you are using the standard <strong>Host</strong> implementation,
234 the following actions take place automatically when Catalina is first
235 started, if the <code>deployOnStartup</code> property is set to
236 <code>true</code> (which is the default value):</p>
237 <ul>
238 <li>Any XML file in
239 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> is
240 assumed to be a context XML descriptor containing a
241 <a href="context.html">Context</a> element (and its associated
242 sub-elements) for a single web application. The web applications
243 associated with each of these context XML descriptor files will be
244 deployed first.<br>
245 The <code>docBase</code> attribute of this <code>&lt;Context&gt;</code>
246 element must only be set if the docBase is outside the Host's
247 <code>appBase</code>. For web applications located inside the Host's
248 <code>appBase</code>, the <code>docBase</code> will be the name of the
249 XML file with ".xml" replaced with ".war" for a web application archive
250 or the name of the XML file with ".xml" removed for a directory.<br>
251 The <code>path</code> attribute must not be set. The context path used
252 will be a slash character ("/") followed by the name of the XML file
253 (less the .xml extension). Multi-level context paths may be defined
254 using #, e.g. <code>foo#bar.xml</code> for a context path of
255 <code>/foo/bar</code>. The default web application that has a context
256 path of <code>/</code> may be defined by using a file called
257 <code>ROOT.xml</code>.</li>
258 <li>Any web application archive file within the Host's <code>appBase</code>
259 directory that has not already been deployed as a result of a context
260 XML descriptor, does not have a corresponding directory of the same
261 name (without the ".war" extension), and is not excluded by
262 <code>deployIgnore</code> will be deployed next. The context path
263 used will be a slash character ("/") followed by the web application
264 archive name less the ".war" extension. The one exception to this rule
265 is that a web application archive named "ROOT.war" will be deployed with
266 a context path of <code>/</code>. Multi-level contexts may be defined by
267 using #, e.g. use a WAR named <code>foo#bar.war</code> for a context
268 path of <code>/foo/bar</code>.<br>
269 If the <code>unpackWARs</code> attribute is <code>true</code>, the web
270 application archive file will be expanded to a directory of the same
271 name (without the ".war" extension".<br>
272 Note: If you re-deploy an updated WAR file while Tomcat is stopped, be
273 sure to delete the associated expanded directory before restarting
274 Tomcat, so that the updated WAR file will be re-expanded when Tomcat
275 restarts.<br>
276 Any web application archive file within the Hosts's <code>appBase</code>
277 directory that does not have a corresponding context XML descriptor
278 (with a ".xml" extension rather than a ".war" extension) in
279 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> will be
280 scanned to see if it contains a context XML descriptor (located at
281 <code>/META-INF/context.xml</code>) and if one is found the descriptor
282 will be copied to the
283 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> directory and
284 renamed.
285 </li>
286 <li>Finally, any sub-directory within the Host's <code>appBase</code> that
287 has not already been deployed as a result of a context XML descriptor
288 and is not excluded by <code>deployIgnore</code> will be deployed.
289 The context path used will be a slash character ("/") followed by the
290 directory name, unless the directory name is ROOT, in which case the
291 context path will <code>/</code>. Multi-level contexts may be defined by
292 using #, e.g. use a directory named <code>foo#bar</code> for a context
293 path of <code>/foo/bar</code>.<br>
294 Any directory within the Hosts's <code>appBase</code> directory that
295 does not have a corresponding context XML descriptor in
296 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> will be
297 scanned to see if it contains a context XML descriptor (located at
298 <code>/META-INF/context.xml</code>) and if one is found the descriptor
299 will be copied to
300 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> and renamed.
301 </li>
302 </ul>
303
304 <p>In addition to the automatic deployment that occurs at startup time,
305 you can also request that new XML configuration files, WAR files, or
306 sub-directories that are dropped in to the <code>appBase</code> (or
307 <code>$CATALINA_BASE/conf/[engine_name]/[host_name]</code> in the case of
308 an XML configuration file) directory while Tomcat is running will be
309 automatically deployed, according to the rules described above. The
310 auto deployer will also track web applications for the following changes:
311 <ul>
312 <li>An update to the WEB-INF/web.xml file will trigger a reload of the
313 web application</li>
314 <li>Deleting a WAR file will trigger an undeploy of the application with
315 the removal of any associated expanded directory, context file and
316 work directory. Any current user sessions will not be persisted.</li>
317 <li>Deleting a directory will trigger an undeploy of the application
318 with the removal of any associated context file and work directory.
319 Any current user sessions will not be persisted. If there is an
320 associated WAR file, it will not be deleted and the application will
321 be redeployed from the WAR file the next time the auto deployer checks
322 for changes.</li>
323 <li>Deleting a context file will trigger an undeploy of the application
324 with the removal of any associated work directory. Any current user
325 sessions will not be persisted. If there is an associated WAR file
326 and/or directory, they will not be deleted and the application will be
327 redeployed from the WAR file (or from directory if there is no WAR
328 file) the next time the auto deployer checks for changes.</li>
329 <li>Updating a WAR file will trigger an undeploy of the application with
330 the removal of any associated expanded directory, context file and
331 work directory. Any current user sessions will not be persisted.</li>
332 <li>Updating a directory (not the directory contents) will trigger an
333 undeploy of the application with the removal of any associated context
334 file and work directory. Any current user sessions will not be
335 persisted. The application will be redeployed the next time the auto
336 deployer checks for changes.</li>
337 <li>Updating a context file will trigger an undeploy of the application
338 with the removal of any associated work directory. Any current user
339 sessions will not be persisted. The application will be redeployed the
340 next time the auto deployer checks for changes.</li>
341 </ul>
342 </p>
343
344 <p>When using automatic deployment, the <code>docBase</code> defined by
345 an XML <a href="context.html">Context</a> file should be outside of the
346 <code>appBase</code> directory. If this is not the case, difficulties
347 may be experienced deploying the web application or the application may
348 be deployed twice. The <code>deployIgnore</code> attribute can be used
349 to avoid this situation.</p>
350
351 <p>Finally, note that if you are defining contexts explicitly in server.xml,
352 you should probably turn off automatic application deployment or specify
353 <code>deployIgnore</code> carefully. Otherwise, the web applications
354 will each be deployed twice, and that may cause problems for the
355 applications.</p>
356
357 </blockquote></td></tr></table>
358
359
360 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Host Name Aliases"><!--()--></a><a name="Host_Name_Aliases"><strong>Host Name Aliases</strong></a></font></td></tr><tr><td><blockquote>
361
362 <p>In many server environments, Network Administrators have configured
363 more than one network name (in the <em>Domain Name Service</em> (DNS)
364 server), that resolve to the IP address of the same server. Normally,
365 each such network name would be configured as a separate
366 <strong>Host</strong> element in <code>conf/server.xml</code>, each
367 with its own set of web applications.</p>
368
369 <p>However, in some circumstances, it is desirable that two or more
370 network names should resolve to the <strong>same</strong> virtual host,
371 running the same set of applications. A common use case for this
372 scenario is a corporate web site, where it is desirable that users
373 be able to utilize either <code>www.mycompany.com</code> or
374 <code>company.com</code> to access exactly the same content and
375 applications.</p>
376
377 <p>This is accomplished by utilizing one or more <strong>Alias</strong>
378 elements nested inside your <strong>Host</strong> element. For
379 example:</p>
380<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
381&lt;Host name="www.mycompany.com" ...&gt;
382 ...
383 &lt;Alias&gt;mycompany.com&lt;/Alias&gt;
384 ...
385&lt;/Host&gt;
386</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
387
388 <p>In order for this strategy to be effective, all of the network names
389 involved must be registered in your DNS server to resolve to the
390 same computer that is running this instance of Catalina.</p>
391
392 </blockquote></td></tr></table>
393
394
395 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Lifecycle Listeners"><!--()--></a><a name="Lifecycle_Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
396
397 <p>If you have implemented a Java object that needs to know when this
398 <strong>Host</strong> is started or stopped, you can declare it by
399 nesting a <strong>Listener</strong> element inside this element. The
400 class name you specify must implement the
401 <code>org.apache.catalina.LifecycleListener</code> interface, and
402 it will be notified about the occurrence of the corresponding
403 lifecycle events. Configuration of such a listener looks like this:</p>
404
405<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
406&lt;Host name="localhost" ...&gt;
407 ...
408 &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
409 ...
410&lt;/Host&gt;
411</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
412
413 <p>Note that a Listener can have any number of additional properties
414 that may be configured from this element. Attribute names are matched
415 to corresponding JavaBean property names using the standard property
416 method naming patterns.</p>
417
418 </blockquote></td></tr></table>
419
420
421 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Filters"><!--()--></a><a name="Request_Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
422
423 <p>You can ask Catalina to check the IP address, or host name, on every
424 incoming request directed to the surrounding
425 <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
426 <a href="context.html">Context</a> element. The remote address or name
427 will be checked against a configured list of "accept" and/or "deny"
428 filters, which are defined using <code>java.util.regex</code> Regular
429 Expression syntax. Requests that come from locations that are
430 not accepted will be rejected with an HTTP "Forbidden" error.
431 Example filter declarations:</p>
432
433<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
434&lt;Host name="localhost" ...&gt;
435 ...
436 &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
437 allow=".*\.mycompany\.com|www\.yourcompany\.com"/&gt;
438 &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
439 deny="192\.168\.1\.\d+"/&gt;
440 ...
441&lt;/Host&gt;
442</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
443
444 <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
445 and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
446 more information about the configuration options that are supported.</p>
447
448 </blockquote></td></tr></table>
449
450
451 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Single Sign On"><!--()--></a><a name="Single_Sign_On"><strong>Single Sign On</strong></a></font></td></tr><tr><td><blockquote>
452
453 <p>In many environments, but particularly in portal environments, it
454 is desireable to have a user challenged to authenticate themselves only
455 once over a set of web applications deployed on a particular virtual
456 host. This can be accomplished by nesting an element like this inside
457 the Host element for this virtual host:</p>
458
459<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
460&lt;Host name="localhost" ...&gt;
461 ...
462 &lt;Valve className="org.apache.catalina.authenticator.SingleSignOn"/&gt;
463 ...
464&lt;/Host&gt;
465</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
466
467 <p>The Single Sign On facility operates according to the following rules:
468 </p>
469 <ul>
470 <li>All web applications configured for this virtual host must share the
471 same <a href="realm.html">Realm</a>. In practice, that means you can
472 nest the Realm element inside this Host element (or the surrounding
473 <a href="engine.html">Engine</a> element), but not inside a
474 <a href="context.html">Context</a> element for one of the involved
475 web applications.</li>
476 <li>As long as the user accesses only unprotected resources in any of the
477 web applications on this virtual host, they will not be challenged
478 to authenticate themselves.</li>
479 <li>As soon as the user accesses a protected resource in
480 <strong>any</strong> web application associated with this virtual
481 host, the user will be challenged to authenticate himself or herself,
482 using the login method defined for the web application currently
483 being accessed.</li>
484 <li>Once authenticated, the roles associated with this user will be
485 utilized for access control decisions across <strong>all</strong>
486 of the associated web applications, without challenging the user
487 to authenticate themselves to each application individually.</li>
488 <li>As soon as the user logs out of one web application (for example,
489 by invalidating the corresponding session if form
490 based login is used), the user's sessions in <strong>all</strong>
491 web applications will be invalidated. Any subsequent attempt to
492 access a protected resource in any application will require the
493 user to authenticate himself or herself again.</li>
494 <li>The Single Sign On feature utilizes HTTP cookies to transmit a token
495 that associates each request with the saved user identity, so it can
496 only be utilized in client environments that support cookies.</li>
497 </ul>
498
499 </blockquote></td></tr></table>
500
501
502 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="User Web Applications"><!--()--></a><a name="User_Web_Applications"><strong>User Web Applications</strong></a></font></td></tr><tr><td><blockquote>
503
504 <p>Many web servers can automatically map a request URI starting with
505 a tilde character ("~") and a username to a directory (commonly named
506 <code>public_html</code>) in that user's home directory on the server.
507 You can accomplish the same thing in Catalina by using a special
508 <strong>Listener</strong> element like this (on a Unix system that
509 uses the <code>/etc/passwd</code> file to identify valid users):</p>
510
511<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
512&lt;Host name="localhost" ...&gt;
513 ...
514 &lt;Listener className="org.apache.catalina.startup.UserConfig"
515 directoryName="public_html"
516 userClass="org.apache.catalina.startup.PasswdUserDatabase"/&gt;
517 ...
518&lt;/Host&gt;
519</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
520
521 <p>On a server where <code>/etc/passwd</code> is not in use, you can
522 request Catalina to consider all directories found in a specified base
523 directory (such as <code>c:\Homes</code> in this example) to be
524 considered "user home" directories for the purposes of this directive:</p>
525
526<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
527&lt;Host name="localhost" ...&gt;
528 ...
529 &lt;Listener className="org.apache.catalina.startup.UserConfig"
530 directoryName="public_html"
531 homeBase=c:\Homes"
532 userClass="org.apache.catalina.startup.HomesUserDatabase"/&gt;
533 ...
534&lt;/Host&gt;
535</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
536
537 <p>If a user home directory has been set up for a user named
538 <code>craigmcc</code>, then its contents will be visible from a
539 client browser by making a request to a URL like:</p>
540
541<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
542http://www.mycompany.com:8080/~craigmcc
543</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
544
545 <p>Successful use of this feature requires recognition of the following
546 considerations:</p>
547 <ul>
548 <li>Each user web application will be deployed with characteristics
549 established by the global and host level default context settings.</li>
550 <li>It is legal to include more than one instance of this Listener
551 element. This would only be useful, however, in circumstances
552 where you wanted to configure more than one "homeBase" directory.</li>
553 <li>The operating system username under which Catalina is executed
554 MUST have read access to each user's web application directory,
555 and all of its contents.</li>
556 </ul>
557
558 </blockquote></td></tr></table>
559
560
561</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
562 Copyright &copy; 1999-2014, Apache Software Foundation
563 </em></font></div></td></tr></table></body></html>