olivier/cours0708
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
master
cours0708/P51/apache-tomcat-6.0.14/webapps/docs/config/host.html
olivier 3e719157ea Grosse MàJ
2008-11-25 22:11:16 +01:00

483 lines
39 KiB
HTML
Raw Permalink Blame History

<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Host Container</title><meta name="author" value="Craig R. McClanahan"><meta name="email" value="craigmcc@apache.org"><meta name="author" value="Remy Maucherat"><meta name="email" value="remm@apache.org"><meta name="author" value="Yoav Shapira"><meta name="email" value="yoavs@apache.org"></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="
The Apache Tomcat Servlet/JSP Container
" border="0"></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 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="true"><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></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>Apache Tomcat Configuration Reference</h1><h2>The Host Container</h2></td><td align="right" valign="top" nowrap="true"><small><a href="printer/host.html"><img src="../images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
</a></small></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>
<p>The <strong>Host</strong> element represents a <em>virtual host</em>,
which is an association of a network name for a server (such as
"www.mycompany.com" with the particular server on which Catalina is
running. In order to be effective, this name must be registered in the
<em>Domain Name Service</em> (DNS) server that manages the Internet
domain you belong to - contact your Network Administrator for more
information.</p>
<p>In many cases, System Administrators wish to associate more than
one network name (such as <code>www.mycompany.com</code> and
<code>company.com</code>) with the same virtual host and applications.
This can be accomplished using the <a href="#Host Name Aliases">Host
Name Aliases</a> feature discussed below.</p>
<p>One or more <strong>Host</strong> elements are nested inside an
<a href="engine.html">Engine</a> element. Inside the Host element, you
can nest <a href="context.html">Context</a> elements for the web
applications associated with this virtual host. Exactly one of the Hosts
associated with each Engine MUST have a name matching the
<code>defaultHost</code> attribute of that Engine.</p>
<blockquote><em>
<p>The description below uses the variable name $CATALINA_HOME
to refer to the directory into which you have installed Tomcat 6,
and is the base directory against which most relative paths are
resolved. However, if you have configured Tomcat 6 for multiple
instances by setting a CATALINA_BASE directory, you should use
$CATALINA_BASE instead of $CATALINA_HOME for each of these
references.</p>
</em></blockquote>
</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>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
<p>All implementations of <strong>Host</strong>
support the following attributes:</p>
<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">
<p>The <em>Application Base</em> directory for this virtual host.
This is the pathname of a directory that may contain web applications
to be deployed on this virtual host. You may specify an
absolute pathname for this directory, or a pathname that is relative
to the <code>$CATALINA_BASE</code> directory. See
<a href="#Automatic Application Deployment">Automatic Application
Deployment</a> for more information on automatic recognition and
deployment of web applications to be deployed automatically.</p>
</td></tr><tr><td align="left" valign="center"><code>autoDeploy</code></td><td align="left" valign="center">
<p>This flag value indicates if new web applications, dropped in to
the <code>appBase</code> directory while Tomcat is running, should
be automatically deployed. The flag's value defaults to true. See
<a href="#Automatic Application Deployment">Automatic Application
Deployment</a> for more information.</p>
</td></tr><tr><td align="left" valign="center"><code>backgroundProcessorDelay</code></td><td align="left" valign="center">
<p>This value represents the delay in seconds between the
invocation of the backgroundProcess method on this host and
its child containers, including all contexts.
Child containers will not be invoked if their delay value is not
negative (which would mean they are using their own processing
thread). Setting this to a positive value will cause
a thread to be spawn. After waiting the specified amount of time,
the thread will invoke the backgroundProcess method on this host
and all its child containers. A host will use background processing to
perform live web application deployment related tasks. If not
specified, the default value for this attribute is -1, which means
the host will rely on the background processing thread of its parent
engine.</p>
</td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Host</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</td></tr><tr><td align="left" valign="center"><code>deployOnStartup</code></td><td align="left" valign="center">
<p>This flag value indicates if web applications from this host should
be automatically deployed by the host configurator.
The flag's value defaults to true. See
<a href="#Automatic Application Deployment">Automatic Application
Deployment</a> for more information.</p>
</td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
<p>Network name of this virtual host, as registered in your
<em>Domain Name Service</em> server. One of the Hosts nested within
an <a href="engine.html">Engine</a> MUST have a name that matches the
<code>defaultHost</code> setting for that Engine. See
<a href="#Host Name Aliases">Host Name Aliases</a> for information
on how to assign more than one network name to the same
virtual host.</p>
</td></tr></table>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
<p>The standard implementation of <strong>Host</strong> is
<strong>org.apache.catalina.core.StandardHost</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<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">
<p>Set to <code>false</code> if you want to disable parsing the context.xml
file embedded inside the application (located at <code>/META-INF/context.xml</code>).
Security consious environments should set this to <code>false</code> to prevent
applications from interacting with the container's configuration. The
administrator will then be responsible for providing an external context
configuration file, and put it in
<code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code>.
The flag's value defaults to <code>true</code>.</p>
</td></tr><tr><td align="left" valign="center"><code>errorReportValveClass</code></td><td align="left" valign="center">
<p>Java class name of the error reporting valve which will be used
by this Host. The responsability of this valve is to output error
reports. Setting this property allows to customize the look of the
error pages which will be generated by Tomcat. This class must
implement the
<code>org.apache.catalina.Valve</code> interface. If none is specified,
the value <code>org.apache.catalina.valves.ErrorReportValve</code>
will be used by default.</p>
</td></tr><tr><td align="left" valign="center"><code>unpackWARs</code></td><td align="left" valign="center">
<p>Set to <code>true</code> if you want web applications that are
placed in the <code>appBase</code> directory as web application
archive (WAR) files to be unpacked into a corresponding disk directory
structure, <code>false</code> to run such web applications directly
from a WAR file. See
<a href="#Automatic Application Deployment">Automatic Application
Deployment</a> for more information.</p>
</td></tr><tr><td align="left" valign="center"><code>workDir</code></td><td align="left" valign="center">
<p>Pathname to a scratch directory to be used by applications for
this Host. Each application will have its own sub directory with
temporary read-write use. Configuring a Context workDir will override
use of the Host workDir configuration. This directory will be made
visible to servlets in the web application by a servlet context
attribute (of type <code>java.io.File</code>) named
<code>javax.servlet.context.tempdir</code> as described in the
Servlet Specification. If not specified, a suitable directory
underneath <code>$CATALINA_HOME/work</code> will be provided.</p>
</td></tr></table>
</blockquote></td></tr></table>
</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"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
<p>You can nest one or more <a href="context.html">Context</a> elements
inside this <strong>Host</strong> element, each representing a different web
application associated with this virtual host.</p>
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Host</strong>
element:</p>
<ul>
<li><a href="realm.html"><strong>Realm</strong></a> -
Configure a realm that will allow its
database of users, and their associated roles, to be shared across all
<a href="context.html">Contexts</a> nested inside this Host (unless
overridden by a <a href="realm.html">Realm</a> configuration
at a lower level).</li>
</ul>
</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"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
<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>
<p>A host is associated with the
<code>org.apache.catalina.core.ContainerBase.[enginename].[hostname]</code>
log category. Note that the brackets are actuall part of the name,
don't omit them.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote>
<p>When you run a web server, one of the output files normally generated
is an <em>access log</em>, which generates one line of information for
each request processed by the server, in a standard format. Catalina
includes an optional <a href="valve.html">Valve</a> implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.</p>
<p>You can ask Catalina to create an access log for all requests
processed by an <a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="localhost" ...&gt;
...
&lt;Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log." suffix=".txt"
pattern="common"/&gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
for more information on the configuration attributes that are
supported.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Automatic Application Deployment"><strong>Automatic Application Deployment</strong></a></font></td></tr><tr><td><blockquote>
<p>If you are using the standard <strong>Host</strong> implementation,
the following actions take place automatically when Catalina is first
started, if the <code>deployOnStartup</code> property is set to
<code>true</code> (which is the default value):</p>
<ul>
<li>Any XML file in the
<code>$CATALINA_HOME/conf/[engine_name]/[host_name]</code> directory is
assumed to contain a
<a href="context.html">Context</a> element (and its associated
subelements) for a single web application. The <code>docBase</code>
attribute of this <code>&lt;Context&gt;</code> element will typically
be the absolute pathname to a web application directory, or the
absolute pathname of a web application archive (WAR) file (which
will not be expanded). The path attribute will be automatically set
as defined in the <a href="context.html">Context</a> documentation.</li>
<li>Any web application archive file within the application base (appBase)
directory that does not have a corresponding
directory of the same name (without the ".war" extension) will be
automatically expanded, unless the <code>unpackWARs</code> property
is set to <code>false</code>. If you redeploy an updated WAR file,
be sure to delete the expanded directory when restarting Tomcat, so
that the updated WAR file will be re-expanded (note that the auto
deployer, if enabled, will automatically expand the updated WAR file
once the previously expanded directory is removed).</li>
<li>Any subdirectory within the <em>application base directory</em>
will receive an automatically generated <a href="context.html">
Context</a> element, even if this directory is not mentioned in the
<code>conf/server.xml</code> file.
This generated Context entry will be configured according to the
properties set in any <a href="defaultcontext.html">DefaultContext</a>
element nested in this Host element. The context path for this
deployed Context will be a slash character ("/") followed by the
directory name, unless the directory name is ROOT, in which case
the context path will be an empty string ("").</li>
</ul>
<p>In addition to the automatic deployment that occurs at startup time,
you can also request that new XML configuration files, WAR files, or
subdirectories that are dropped in to the <code>appBase</code> (or
<code>$CATALINA_HOME/conf/[engine_name]/[host_name]</code> in the case of
an XML configuration file) directory while Tomcat is running will be
automatically deployed, according to the rules described above. The
auto deployer will also track web applications for the following changes:
<ul>
<li>An update to the WEB-INF/web.xml file will trigger a reload of the
web application</li>
<li>An update to a WAR which has been expanded will trigger
an undeploy (<strong>with a removal of the expanded webapp</strong>),
followed by a deployment</li>
<li>An update to a XML configuration file will trigger an undeploy
(without the removal of any expanded directory), followed by
a deployment of the associated web application</li>
</ul>
</p>
<p>When using automatic deployment, the <code>docBase</code> defined by
an XML <a href="context.html">Context</a> file should be outside of the
<code>appBase</code> directory. If this is not the case difficulties
may be experienced deploying the web application or the application may
be deployed twice.</p>
<p>Finally, note that if you are defining contexts explicitly, you should
probably turn off automatic application deployment. Otherwise, your context
will be deployed twice each, and that may cause problems for your app.
</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Host Name Aliases"><strong>Host Name Aliases</strong></a></font></td></tr><tr><td><blockquote>
<p>In many server environments, Network Administrators have configured
more than one network name (in the <em>Domain Name Service</em> (DNS)
server), that resolve to the IP address of the same server. Normally,
each such network name would be configured as a separate
<strong>Host</strong> element in <code>conf/server.xml</code>, each
with its own set of web applications.</p>
<p>However, in some circumstances, it is desireable that two or more
network names should resolve to the <strong>same</strong> virtual host,
running the same set of applications. A common use case for this
scenario is a corporate web site, where it is desireable that users
be able to utilize either <code>www.mycompany.com</code> or
<code>company.com</code> to access exactly the same content and
applications.</p>
<p>This is accomplished by utilizing one or more <strong>Alias</strong>
elements nested inside your <strong>Host</strong> element. For
example:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="www.mycompany.com" ...&gt;
...
&lt;Alias&gt;mycompany.com&lt;/Alias&gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>In order for this strategy to be effective, all of the network names
involved must be registered in your DNS server to resolve to the
same computer that is running this instance of Catalina.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Lifecycle Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
<p>If you have implemented a Java object that needs to know when this
<strong>Host</strong> is started or stopped, you can declare it by
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
it will be notified about the occurrence of the coresponding
lifecycle events. Configuration of such a listener looks like this:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="localhost" ...&gt;
...
&lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
<p>You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a> element. The remote address or name
will be checked against a configured list of "accept" and/or "deny"
filters, which are defined using the Regular Expression syntax supported
by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
regular expression library. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="localhost" ...&gt;
...
&lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
allow="*.mycompany.com,www.yourcompany.com"/&gt;
&lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192.168.1.*"/&gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Single Sign On"><strong>Single Sign On</strong></a></font></td></tr><tr><td><blockquote>
<p>In many environments, but particularly in portal environments, it
is desireable to have a user challenged to authenticate themselves only
once over a set of web applications deployed on a particular virtual
host. This can be accomplished by nesting an element like this inside
the Host element for this virtual host:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="localhost" ...&gt;
...
&lt;Valve className="org.apache.catalina.authenticator.SingleSignOn"
debug="0"/&gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>The Single Sign On facility operates according to the following rules:
</p>
<ul>
<li>All web applications configured for this virtual host must share the
same <a href="realm.html">Realm</a>. In practice, that means you can
nest the Realm element inside this Host element (or the surrounding
<a href="engine.html">Engine</a> element), but not inside a
<a href="context.html">Context</a> element for one of the involved
web applications.</li>
<li>As long as the user accesses only unprotected resources in any of the
web applications on this virtual host, they will not be challenged
to authenticate themselves.</li>
<li>As soon as the user accesses a protected resource in
<strong>any</strong> web application associated with this virtual
host, the user will be challenged to authenticate himself or herself,
using the login method defined for the web application currently
being accessed.</li>
<li>Once authenticated, the roles associated with this user will be
utilized for access control decisions across <strong>all</strong>
of the associated web applications, without challenging the user
to authenticate themselves to each application individually.</li>
<li>As soon as the user logs out of one web application (for example,
by invalidating the corresponding session if form
based login is used), the user's sessions in <strong>all</strong>
web applications will be invalidated. Any subsequent attempt to
access a protected resource in any application will require the
user to authenticate himself or herself again.</li>
<li>The Single Sign On feature utilizes HTTP cookies to transmit a token
that associates each request with the saved user identity, so it can
only be utilized in client environments that support cookies.</li>
</ul>
</blockquote></td></tr></table>
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="User Web Applications"><strong>User Web Applications</strong></a></font></td></tr><tr><td><blockquote>
<p>Many web servers can automatically map a request URI starting with
a tilde character ("~") and a username to a directory (commonly named
<code>public_html</code>) in that user's home directory on the server.
You can accomplish the same thing in Catalina by using a special
<strong>Listener</strong> element like this (on a Unix system that
uses the <code>/etc/passwd</code> file to identify valid users):</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="localhost" ...&gt;
...
&lt;Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
userClass="org.apache.catalina.startup.PasswdUserDatabase"/&gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>On a server where <code>/etc/passwd</code> is not in use, you can
request Catalina to consider all directories found in a specified base
directory (such as <code>c:\Homes</code> in this example) to be
considered "user home" directories for the purposes of this directive:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;Host name="localhost" ...&gt;
...
&lt;Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
homeBase=c:\Homes"
userClass="org.apache.catalina.startup.HomesUserDatabase"/&gt;
...
&lt;/Host&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>If a user home directory has been set up for a user named
<code>craigmcc</code>, then its contents will be visible from a
client browser by making a request to a URL like:</p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
http://www.mycompany.com:8080/~craigmcc
</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" 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" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
<p>Successful use of this feature requires recognition of the following
considerations:</p>
<ul>
<li>Each user web application will be deployed with characteristics
established by any <a href="defaultcontext.html">DefaultContext</a>
element you have configured for this Host.</li>
<li>It is legal to include more than one instance of this Listener
element. This would only be useful, however, in circumstances
where you wanted to configure more than one "homeBase" directory.</li>
<li>The operating system username under which Catalina is executed
MUST have read access to each user's web application directory,
and all of its contents.</li>
</ul>
</blockquote></td></tr></table>
</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>
Copyright &copy; 1999-2006, Apache Software Foundation
</em></font></div></td></tr></table></body></html>
Reference in New Issue View Git Blame Copy Permalink