source: nutchez-0.1/tomcat/webapps/docs/config/host.html @ 81

Last change on this file since 81 was 66, checked in by waue, 15 years ago

NutchEz - an easy way to nutch

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