482 lines
37 KiB
HTML
482 lines
37 KiB
HTML
|
<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><!--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"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></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>
|
||
|
|
<Host name="localhost" ...>
|
||
|
|
...
|
||
|
|
<Valve className="org.apache.catalina.valves.AccessLogValve"
|
||
|
|
prefix="localhost_access_log." suffix=".txt"
|
||
|
|
pattern="common"/>
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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><Context></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>
|
||
|
|
<Host name="www.mycompany.com" ...>
|
||
|
|
...
|
||
|
|
<Alias>mycompany.com</Alias>
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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>
|
||
|
|
<Host name="localhost" ...>
|
||
|
|
...
|
||
|
|
<Listener className="com.mycompany.mypackage.MyListener" ... >
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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>
|
||
|
|
<Host name="localhost" ...>
|
||
|
|
...
|
||
|
|
<Valve className="org.apache.catalina.valves.RemoteHostValve"
|
||
|
|
allow="*.mycompany.com,www.yourcompany.com"/>
|
||
|
|
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
|
||
|
|
deny="192.168.1.*"/>
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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>
|
||
|
|
<Host name="localhost" ...>
|
||
|
|
...
|
||
|
|
<Valve className="org.apache.catalina.authenticator.SingleSignOn"
|
||
|
|
debug="0"/>
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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>
|
||
|
|
<Host name="localhost" ...>
|
||
|
|
...
|
||
|
|
<Listener className="org.apache.catalina.startup.UserConfig"
|
||
|
|
directoryName="public_html"
|
||
|
|
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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>
|
||
|
|
<Host name="localhost" ...>
|
||
|
|
...
|
||
|
|
<Listener className="org.apache.catalina.startup.UserConfig"
|
||
|
|
directoryName="public_html"
|
||
|
|
homeBase=c:\Homes"
|
||
|
|
userClass="org.apache.catalina.startup.HomesUserDatabase"/>
|
||
|
|
...
|
||
|
|
</Host>
|
||
|
|
</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 © 1999-2006, Apache Software Foundation
|
||
|
|
</em></font></div></td></tr></table></body></html>
|