You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@apache.org on 2001/01/14 05:17:05 UTC
cvs commit: jakarta-tomcat-4.0/catalina/docs/config categories.html context.html engine.html host.html http11.html
craigmcc 01/01/13 20:17:05
Modified: catalina/docs/config categories.html context.html
engine.html host.html http11.html
Log:
Major update to the configuration documentation for Tomcat 4.0.
TODO: Flesh out the information on the WARP connector, and create
documentation for the various utility components.
Revision Changes Path
1.2 +21 -16 jakarta-tomcat-4.0/catalina/docs/config/categories.html
Index: categories.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/config/categories.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- categories.html 2000/08/11 05:21:04 1.1
+++ categories.html 2001/01/14 04:17:05 1.2
@@ -5,36 +5,41 @@
<body bgcolor="sky blue" link="black" vlink="black">
<font size="2">
+<h3>Home</h3>
+<ul>
+<li><a target="_TOP" href="../index.html">Home</a></li>
+</ul>
+
<h3>Overview</h3>
<ul>
-<li><a target="MAIN" href="main.html">Title Page</a>
-<li><a target="MAIN" href="introduction.html">Introduction</a>
-<li><a target="MAIN" href="example.html">Example</a>
+<li><a target="MAIN" href="main.html">Title Page</a></li>
+<li><a target="MAIN" href="introduction.html">Introduction</a></li>
+<li><a target="MAIN" href="example.html">Example</a></li>
</ul>
<h3>Connectors</h3>
<ul>
-<li><a target="MAIN" href="connector.html">Overview</a>
-<li><a target="MAIN" href="http11.html">HTTP/1.1</a>
+<li><a target="MAIN" href="http11.html">HTTP/1.1</a></li>
+<li><a target="MAIN" href="warp.html">WARP</a></li>
</ul>
<h3>Containers</h3>
<ul>
-<li><a target="MAIN" href="container.html">Overview</a>
-<li><a target="MAIN" href="engine.html">Engine</a>
-<li><a target="MAIN" href="host.html">Host</a>
-<li><a target="MAIN" href="context.html">Context</a>
+<li><a target="MAIN" href="server.html">Server</a></li>
+<li><a target="MAIN" href="service.html">Service</a></li>
+<li><a target="MAIN" href="engine.html">Engine</a></li>
+<li><a target="MAIN" href="host.html">Host</a></li>
+<li><a target="MAIN" href="context.html">Context</a></li>
</ul>
<h3>Utilities</h3>
<ul>
-<li><a target="MAIN" href="utility.html">Overview</a>
-<li><a target="MAIN" href="listener.html">Listener</a>
-<li><a target="MAIN" href="loader.html">Loader</a>
-<li><a target="MAIN" href="manager.html">Manager</a>
-<li><a target="MAIN" href="realm.html">Realm</a>
-<li><a target="MAIN" href="resources.html">Resources</a>
-<li><a target="MAIN" href="valve.html">Valve</a>
+<li><a target="MAIN" href="loader.html">Loader</a></li>
+<li><a target="MAIN" href="logger.html">Logger</a></li>
+<li><a target="MAIN" href="manager.html">Manager</a></li>
+<li><a target="MAIN" href="realm.html">Realm</a></li>
+<li><a target="MAIN" href="resources.html">Resources</a></li>
+<li><a target="MAIN" href="valve.html">Valve</a></li>
</ul>
</font>
1.2 +88 -70 jakarta-tomcat-4.0/catalina/docs/config/context.html
Index: context.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/config/context.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- context.html 2000/08/11 05:21:04 1.1
+++ context.html 2001/01/14 04:17:05 1.2
@@ -19,37 +19,43 @@
<a name="Introduction"></a>
<h2>Introduction</h2>
-<p>A <b>Context</b> component represents an individual web application that
-is running within a particular <a href="host.html">Host</a>. Such a web
-application is based on a directory whose organization is described in the
-Servlet API Specification, version 2.2 -- including the web application
-deployment descriptor file, found in "WEB-INF/web.xml".</p>
+<p>A <strong>Context</strong> component represents an individual web
+application that is running within a particular <a href="host.html">Host</a>.
+Such a web application is based on a directory whose organization is described
+in the Servlet API Specification, version 2.2 -- including the web application
+deployment descriptor file, found in <code>"WEB-INF/web.xml"</code>.</p>
<p>The web application used to process a particular request is selected by
Catalina based on matching the longest possible prefix of the request URI
-against the "context path" of each defined Context. Once selected, that
+against the <em>context path</em> of each defined Context. Once selected, that
Context will select an appropriate servlet to process the incoming request,
-based on the request mapping rules that are also found in the servlet
-specification.</p>
-
-<p>You may define as many <b>Context</b> components as you wish, nested
-within a <b>Host</b> component in the <code>conf/server.xml</code> file.
-Each such Context must have a unique context path, defined by the
-<code>path</code> attribute. In addition, you <b>must</b> define a context
-with a path equal to a zero-length string, which becomes the default
-web application to process requests when a different context cannot be
-matched. There are also special features of the
+according to the servlet mappings defined in the web application deployment
+descriptor, based on the request mapping rules that are also found in the
+servlet specification.</p>
+
+<p>You may define as many <strong>Context</strong> components as you wish,
+nested within a <a href="host.html">Host</a> component in the
+<code>conf/server.xml</code> file. Each such Context must have a unique
+context path, defined by the <code>path</code> attribute. In addition,
+you <strong>must</strong> define a context with a path equal to a zero-length
+string, which becomes the default web application to process requests when a
+different context cannot be matched. There are also special features of the
<a href="host.html#Special Features">Host</a> configuration that enable
-automatic creation of <b>Context</b> components without having to explicitly
-mention them.</p>
+automatic creation of <strong>Context</strong> components without having
+to explicitly mention them.</p>
+
+<p>Request processing <a href="valve.html">Valves</a> that are nested
+here will be executed for every request received for processing by this
+web application.</p>
<br>
+
<a name="Common Attributes"></a>
<h2>Common Attributes</h2>
-<p>All implementations of the <b>Context</b> component support the following
-attributes, which can be defined in a <code><Context></code> element:</p>
+<p>All implementations of the <strong>Context</strong> component support the
+following attributes:</p>
<table border="1" width="100%">
@@ -61,9 +67,9 @@
<tr>
<td><code>className</code></td>
<td>Java class name of the implementation to use. This class must
- implement the <code>org.apache.tomcat.Context</code> interface. If
+ implement the <code>org.apache.catalina.Context</code> interface. If
no class name is specified, the standard implementation will be
- used (<code>org.apache.tomcat.core.StandardContext</code>).
+ used (<code>org.apache.catalina.core.StandardContext</code>).
</td>
</tr>
@@ -79,6 +85,18 @@
</tr>
<tr>
+ <td><code>crossContext</code></td>
+ <td>
+ Set to <code>true</code> of you want calls from within this application
+ to <code>ServletContext.getContext()</code> to successfully return the
+ <code>ServletContext</code> for other web applications running in this
+ host. Set to <code>false</code> in security conscious environments, so
+ that <code>getContext()</code> calls will return <code>null</code>. The
+ default value is <code>false</code>.
+ </td>
+ </tr>
+
+ <tr>
<td><code>docBase</code></td>
<td>
The "document base" directory for this web application. This is the
@@ -118,10 +136,10 @@
<tr>
<td><code>wrapperClass</code></td>
<td>
- Java class name of the <code>org.apache.tomcat.Wrapper</code>
+ Java class name of the <code>org.apache.catalina.Wrapper</code>
implementation class that will be used for servlets managed by this
Context. If not specified, the standard value
- (<code>org.apache.tomcat.core.StandardWrapper</code>) will be used.
+ (<code>org.apache.catalina.core.StandardWrapper</code>) will be used.
</td>
</tr>
@@ -132,9 +150,8 @@
<a name="Standard Implementation Attributes"></a>
<h2>Standard Implementation Attributes</h2>
-<p>The standard implementation of the <b>Context</b> component supports the
-following attributes in addition to those supported by all implementations:
-</p>
+<p>The standard implementation of the <strong>Context</strong> component
+also supports the following attributes:</p>
<table border="1" width="100%">
@@ -146,9 +163,10 @@
<tr>
<td><code>debug</code></td>
<td>
- The level of debugging detail logged by this Engine to the associated
- Logger, with higher numbers generating more detailed output. If not
- specified, the debugging detail level will be set to zero (0).
+ The level of debugging detail logged by this <strong>Context</strong>
+ to the associated Logger, with higher numbers generating more detailed
+ output. If not specified, the debugging detail level will be set to
+ zero (0).
</td>
</tr>
@@ -174,22 +192,24 @@
<h2>Utility Components</h2>
<p>You can attach one or more of the following utility components by nesting
-a corresponding declaration element inside your <b>Context</b> element. If
-you do not specify a utility component element, your Context will inherit the
-corresponding component (if any) from its parent Host.</p>
+a corresponding declaration inside your <strong>Host</strong> element.
+Unless overridden by a utility component of the same name being nested in a
+<a href="context.html">Context</a> element,
+the utility components you declare here will be shared among all
+web applications running in this <strong>Host</strong>:</p>
+
<ul>
<li><a href="loader.html">Loader</a> - Configure a class loader associated
- with this <b>Context</b>.
+ with this <strong>Context</strong>.
<li><a href="logger.html">Logger</a> - Configure a logger that will receive
- all log messages from this <b>Context</b>, as well as from all servlets
- running within this <b>Context</b>.</li>
+ all log messages from this <strong>Context</strong>.</li>
<li><a href="manager.html">Manager</a> - Configure a session manager
- for the sessions associated with this <b>Context</b>.</li>
+ for the sessions associated with this <strong>Context</strong>.</li>
<li><a href="realm.html">Realm</a> - Configure a realm that will allow your
- database of users, and their associated roles, to be looked up as needed
- by the web application running in this <b>Context</b>.</li>
+ database of users, and their associated roles, to be unique to this
+ particular web application.</li>
<li><a href="resources.html">Resources</a> - Configure access to the static
- resources associated with this <b>Context</b></li>
+ resources associated with this <strong>Context</strong></li>
</ul>
<br>
@@ -206,44 +226,44 @@
implementation that can create access logs in the same standard format
created by web servers, or in any custom format desired.</p>
-<p>You can ask Catalina to create an access log for all requests to the
-web application running within this <b>Context</b>, by nesting an element
-like this inside your <b>Context</b> element:</p>
+<p>You can ask Catalina to create an access log for all requests to this
+web application, by nesting an element like this inside your
+<strong>Context</strong> element:</p>
<pre>
<Context path="/myapp" ...>
...
- <Valve className="org.apache.tomcat.valves.AccessLogValve"
- prefix="localhost_myapp_access_log." suffix=".txt"
+ <Valve className="org.apache.catalina.valves.AccessLogValve"
+ prefix="myapp_access_log." suffix=".txt"
pattern="common"/>
...
- </Context>
+ </Host>
</pre>
-<p>See <a href="valve.html#FIXME">Access Log Valve</a> for more
+<p>See <a href="valve.html#AccessLogValve">Access Log Valve</a> for more
information on the configuration options that are supported.</p>
<h3>Automatic Context Configuration</h3>
-<p>If you use the standard <b>Context</b> implementation, the following
-configuration occurs automatically when Catalina is started, or whenever
-this web application is restarted. No special configuration is necessary
-to enable this activity.</p>
+<p>If you use the standard <strong>Context</strong> implementation, the
+following configuration occurs automatically when Catalina is started, or
+whenever this web application is restarted. No special configuration is
+necessary to enable this activity.</p>
<ul>
<li>If you have not declared your own <a href="loader.html">Loader</a>
to be installed, an instance of the standard Loader implementation class
- (<code>org.apache.tomcat.loader.StandardLoader</code>) will be
+ (<code>org.apache.catalina.loader.StandardLoader</code>) will be
installed and configured.</li>
<li>If you have not declared your own <a href="manager.html">Manager</a>
to be installed, an instance of the standard Manager implementation class
- (<code>org.apache.tomcat.session.StandardManager</code>) will be
+ (<code>org.apache.catalina.session.StandardManager</code>) will be
installed and configured.</li>
<li>If you have not declared your own <a href="resources.html">Resources</a>
to be installed, an instance of the standard Resources implementation class
- (<code>org.apache.tomcat.resources.StandardResources</code>) will be
+ (<code>org.apache.catalina.resources.StandardResources</code>) will be
installed and configured.</li>
-<li>The web application properties for this application will be initialized
+<li>The web application properties for this application will be defaulted
from the <code>conf/web.xml</code> file. This deployment descriptor can
therefore be used to establish defaults for servlet mappings (such as the
JSP servlet) and MIME types for all applications running in Catalina.</li>
@@ -264,12 +284,12 @@
<h3>Lifecycle Listeners</h3>
-<p>If you have implemented a Java object that needs to know when this Context
-is started or stopped, you can declare it by nesting a
+<p>If you have implemented a Java object that needs to know when this
+<strong>Context</strong> is started or stopped, you can declare it by nesting a
<code><Listener></code> element inside the <code><Context></code>
element. The class you specify in the <code>className</code> attribute
of this Listener must implement the
-<code>org.apache.tomcat.LifecycleListener</code> interface, and it will be
+<code>org.apache.catalina.LifecycleListener</code> interface, and it will be
notified about the occurrence of the corresponding lifecycle events.</p>
<p>Configuration for such a listener might look like this:</p>
@@ -277,38 +297,36 @@
<Context path="/myapp" ...>
...
- <Listener className="com.mycompany.MyContextListener"/>
+ <Listener className="com.mycompany.MyAppListener"/>
...
</Context>
</pre>
-<p>See <a href="listener.html">Listeners</a> for more information about
-lifecycle listeners.</p>
-
<h3>Request Filters</h3>
<p>You can ask Catalina to check the IP address, or host name, of an
-incoming request for this particular web application
+incoming request for this web application
against a list of "accept" and "deny" filters, which are
defined using the Regular Expression syntax supported by the jakarta-regexp
regular expression library system. Requests that come from remote locations
-that are not accepted will be rejected with an HTTP "Forbidden" error. An
-example configuration that rejects requests from any domain
-except "mycompany.com" would be:</p>
+that are not accepted will be rejected with an HTTP "Forbidden" error.
+Example filter declarations:</p>
<pre>
<Context path="/myapp" ...>
...
- <Valve className="org.apache.tomcat.valves.RemoteHostValve"
- allow="*.mycompany.com"/>
+ <Valve className="org.apache.catalina.valves.RemoteHostValve"
+ allow="*.mycompany.com,www.yourcompany.com"/>
+ <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+ deny="192.168.1.*"
...
</Context>
</pre>
-<p>See <a href="valve.html#FIXME">Request Filter Valve</a> for more
-information on the syntax of the filters, and the logic that is applied
+<p>See <a href="valve.html#RequestFilterValve">Request Filter Valve</a> for
+more information on the syntax of the filters, and the logic that is applied
when they are executed.</p>
<br>
1.2 +52 -52 jakarta-tomcat-4.0/catalina/docs/config/engine.html
Index: engine.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/config/engine.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- engine.html 2000/08/11 05:21:05 1.1
+++ engine.html 2001/01/14 04:17:05 1.2
@@ -19,23 +19,26 @@
<a name="Introduction"></a>
<h2>Introduction</h2>
-<p>An <b>Engine</b> component represents the entire Catalina servlet
-container. Normally, a single instance of an <b>Engine</b> component
-is configured to receive all requests received by one or more
-<a href="connector.html">Connector</a> components. This element will
-be nested immediately after the <code><Connector></code> elements,
-inside a <code><Server></code> element.</p>
+<p>An <strong>Engine</strong> component represents the entire Catalina servlet
+container. A single instance of an <b>Engine</b> component
+is configured for each <a href="service.html">Service</a>, to receive
+all requests received by one or more <strong>Connector</strong>
+components. This element must be nested immediately after the
+<strong>Connector</strong> elements, inside the owning
+<a href="service.html">Service</a> element.</p>
+
+<p>Request processing <a href="valve.html">Valves</a> that are nested
+here will be executed for every request received from every
+<strong>Connector</strong> configured within this service.</p>
-<p>Request processing <a href="valve.html">Valves</a> that are specified
-here will be executed for every request received from every connector.</p>
-
<br>
+
<a name="Common Attributes"></a>
<h2>Common Attributes</h2>
-<p>All implementations of the <b>Engine</b> component support the following
-attributes, which are configured in an <code><Engine></code> element:</p>
+<p>All implementations of the <strong>Engine</strong> component support the
+following attributes:</p>
<table border="1" width="100%">
@@ -47,9 +50,17 @@
<tr>
<td><code>className</code></td>
<td>Java class name of the implementation to use. This class must
- implement the <code>org.apache.tomcat.Engine</code> interface. If
+ implement the <code>org.apache.catalina.Engine</code> interface. If
no class name is specified, the standard implementation will be
- used (<code>org.apache.tomcat.core.StandardEngine</code>).
+ used (<code>org.apache.catalina.core.StandardEngine</code>).
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>defaultHost</code></td>
+ <td>The default host name, identifying the
+ <a href="host.html">Host</a> to which requests from unidentified
+ remote hosts will be directed.
</td>
</tr>
@@ -64,12 +75,12 @@
<br>
+
<a name="Standard Implementation Attributes"></a>
<h2>Standard Implementation Attributes</h2>
-<p>The standard implementation of the <b>Engine</b> component supports the
-following attributes in addition to those supported by all implementations:
-</p>
+<p>The standard implementation of the <strong>Engine</strong> component also
+supports the following attributes:</p>
<table border="1" width="100%">
@@ -81,41 +92,32 @@
<tr>
<td><code>debug</code></td>
<td>
- The level of debugging detail logged by this Engine to the associated
- Logger, with higher numbers generating more detailed output. If not
- specified, the debugging detail level will be set to zero (0).
+ The level of debugging detail logged by this <strong>Engine</strong>
+ to the associated Logger, with higher numbers generating more detailed
+ output. If not specified, the debugging detail level will be set to
+ zero (0).
</td>
</tr>
- <tr>
- <td><code>defaultHost</code></td>
- <td>Normally, requests which specify a <code>Host:</code> HTTP
- header are forwarded to a <a href="host.html">Host</a> with
- a matching name or alias. If a request is received with a
- requested host name that is not recognized, it will be
- forwarded to the <b>Host</b> named here. If not specified,
- such requests will be returned with an HTTP error instead.
- </td>
- </tr>
-
</table>
<br>
+
<a name="Utility Components"></a>
<h2>Utility Components</h2>
<p>You can attach one or more of the following utility components by nesting
-a corresponding declaration element inside your <b>Host</b> element. Unless
-overridden by a utility component of the same name being nested in a
-<a href="context.html">Context</a> element, the utility components you
-declare here will be shared among all web applications running in this
-<b>Host</b>:</p>
+a corresponding declaration inside your <strong>Engine</strong> element.
+Unless overridden by a utility component of the same name being nested in a
+<a href="host.html">Host</a> or <a href="context.html">Context</a> element,
+the utility components you declare here will be shared among all virtual
+hosts and web applications running in this <strong>Engine</strong>:</p>
<ul>
<li><a href="logger.html">Logger</a> - Configure a logger that will receive
- all log messages from this <b>Engine</b>, plus log messages from
- <a href="connector.html">Connectors</a> attached to this Engine. In
+ all log messages from this <strong>Engine</strong>, plus log messages
+ from <strong>Connectors</strong> attached to this Engine. In
addition, this Logger will log messages from subordinate
<a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>,
unless overridden by a Logger configuration at a lower level.
@@ -141,13 +143,13 @@
created by web servers, or in any custom format desired.</p>
<p>You can ask Catalina to create an access log for all requests to any
-web application for any <b>Host</b>, by nesting an element like this inside
-your <b>Engine</b> element:</p>
+web application for any <strong>Host</strong>, by nesting an element like
+this inside your <b>Engine</b> element:</p>
<pre>
<Engine name="engine" ...>
...
- <Valve className="org.apache.tomcat.valves.AccessLogValve"
+ <Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="catalina_access_log." suffix=".txt"
pattern="common"/>
...
@@ -155,7 +157,7 @@
</pre>
-<p>See <a href="valve.html#FIXME">Access Log Valve</a> for more
+<p>See <a href="valve.html#AccessLogValve">Access Log Valve</a> for more
information on the configuration options that are supported.</p>
<h3>Lifecycle Listeners</h3>
@@ -165,7 +167,7 @@
<code><Listener></code> element inside the <code><Engine></code>
element. The class you specify in the <code>className</code> attribute
of this Listener must implement the
-<code>org.apache.tomcat.LifecycleListener</code> interface, and it will be
+<code>org.apache.catalina.LifecycleListener</code> interface, and it will be
notified about the occurrence of the corresponding lifecycle events.</p>
<p>Configuration for such a listener might look like this:</p>
@@ -179,9 +181,6 @@
</pre>
-<p>See <a href="listener.html">Listeners</a> for more information about
-lifecycle listeners.</p>
-
<h3>Request Filters</h3>
<p>You can ask Catalina to check the IP address, or host name, of an
@@ -189,22 +188,23 @@
against a list of "accept" and "deny" filters, which are
defined using the Regular Expression syntax supported by the jakarta-regexp
regular expression library system. Requests that come from remote locations
-that are not accepted will be rejected with an HTTP "Forbidden" error. An
-example configuration that rejects requests from any domain except
-"mycompany.com") would be:</p>
+that are not accepted will be rejected with an HTTP "Forbidden" error.
+Example filter declarations:</p>
<pre>
<Engine name="engine" ...>
...
- <Valve className="org.apache.tomcat.valves.RemoteHostValve"
- allow="*.mycompany.com"/>
+ <Valve className="org.apache.catalina.valves.RemoteHostValve"
+ allow="*.mycompany.com,www.yourcompany.com"/>
+ <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+ deny="192.168.1.*"
...
</Engine>
</pre>
-<p>See <a href="valve.html#FIXME">Request Filter Valve</a> for more
-information on the syntax of the filters, and the logic that is applied
+<p>See <a href="valve.html#RequestFilterValve">Request Filter Valve</a> for
+more information on the syntax of the filters, and the logic that is applied
when they are executed.</p>
<br>
1.2 +73 -80 jakarta-tomcat-4.0/catalina/docs/config/host.html
Index: host.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/config/host.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- host.html 2000/08/11 05:21:05 1.1
+++ host.html 2001/01/14 04:17:05 1.2
@@ -19,33 +19,34 @@
<a name="Introduction"></a>
<h2>Introduction</h2>
-<p>A <b>Host</b> component represents a "virtual host" that is running in
-an instance of Catalina, possibly in conjunction with many other virtual
-hosts. Each virtual host can be running one or more web applications, each
-represented by a <a href="context.html">Context</a> component.</p>
+<p>A <strong>Host</strong> component represents a "virtual host" that is
+running in an instance of Catalina, possibly in conjunction with many other
+virtual hosts. Each virtual host can be running one or more web applications,
+each represented by a <a href="context.html">Context</a> component.</p>
<p>In order for a client, such as a web browser, to successfully send a
request to a web application running in a particular virtual host, the client
must specify a hostname that is mapped, in the Domain Name Service (DNS) to
the server that Catalina is running on, and a port number on which you have
-defined a <a href="connector.html">Connector</a> to be listening.</p>
+defined a <strong>Connector</strong> to be listening.</p>
-<p>Normally, you will define at least one <b>Host</b> component named
-<code>localhost</code>, to receive requests sent from a client running on
-the same server. Often, you will also want this <b>Host</b> to receive all
-requests for a host name that does not match one of the other defined Hosts
-for this server. You indicate this by setting the <code>defaultHost</code>
-attribute of the <a href="engine.html">Engine</a> component to the
-<code>localhost</code> (or whatever other Host name you wish to receive
-requests for unknown hosts).</p>
+<p>You must define at least one <strong>Host</strong> component nested inside
+each <a href="engine.html">Engine</a> element. Typically, this Host will be
+named <code>localhost</code>, and will be declared as the default host for
+the owning Engine.</p>
+
+<p>Request processing <a href="valve.html">Valves</a> that are nested
+here will be executed for every request received for processing by this
+virtual host.</p>
<br>
+
<a name="Common Attributes"></a>
<h2>Common Attributes</h2>
-<p>All implementations of the <b>Host</b> component support the following
-attributes, which can be defined in a <code><Host></code> element:</p>
+<p>All implementations of the <strong>Host</strong> component support the
+following attributes:</p>
<table border="1" width="100%">
@@ -71,9 +72,9 @@
<tr>
<td><code>className</code></td>
<td>Java class name of the implementation to use. This class must
- implement the <code>org.apache.tomcat.Host</code> interface. If
+ implement the <code>org.apache.catalina.Host</code> interface. If
no class name is specified, the standard implementation will be
- used (<code>org.apache.tomcat.core.StandardHost</code>).
+ used (<code>org.apache.catalina.core.StandardHost</code>).
</td>
</tr>
@@ -82,7 +83,8 @@
<td>The host name of this virtual host. This name must match the
name submitted on the <code>Host:</code> header in incoming
requests. This attribute is required, and must be unique among
- the virtual hosts running in this servlet container.
+ the virtual hosts running in this servlet container. Note that
+ hostname matching is <strong>not</strong> case sensitive.
</td>
</tr>
@@ -93,9 +95,8 @@
<a name="Standard Implementation Attributes"></a>
<h2>Standard Implementation Attributes</h2>
-<p>The standard implementation of the <b>Host</b> component supports the
-following attributes in addition to those supported by all implementations:
-</p>
+<p>The standard implementation of the <strong>Host</strong> component also
+supports the following attributes:</p>
<table border="1" width="100%">
@@ -107,20 +108,10 @@
<tr>
<td><code>debug</code></td>
<td>
- The level of debugging detail logged by this Engine to the associated
- Logger, with higher numbers generating more detailed output. If not
- specified, the debugging detail level will be set to zero (0).
- </td>
- </tr>
-
- <tr>
- <td><code>root</code></td>
- <td>Boolean attribute stating whether calls to
- <code>ServletContext.getContext()</code> on web applications
- running in this virtual host should allow one application to gain
- access to the ServletContext of another. Set to <code>false</code>
- to disallow such access. If not specified, the default value
- (<code>false</code>) will be used.
+ The level of debugging detail logged by this <strong>Host</strong>
+ to the associated Logger, with higher numbers generating more detailed
+ output. If not specified, the debugging detail level will be set to
+ zero (0).
</td>
</tr>
@@ -128,25 +119,24 @@
<br>
+
<a name="Utility Components"></a>
<h2>Utility Components</h2>
<p>You can attach one or more of the following utility components by nesting
-a corresponding declaration element inside your <b>Host</b> element. Unless
-overridden by a utility component of the same name being nested in a
-<a href="context.html">Context</a> element, the utility components you
-declare here will be shared among all web applications running in this
-<b>Host</b>:</p>
+a corresponding declaration inside your <strong>Host</strong> element.
+Unless overridden by a utility component of the same name being nested in a
+<a href="context.html">Context</a> element,
+the utility components you declare here will be shared among all
+web applications running in this <strong>Host</strong>:</p>
<ul>
<li><a href="logger.html">Logger</a> - Configure a logger that will receive
- all log messages from this <b>Host</b>, as well as from all web
- applications running on this <b>Host</b>.
- </li>
+ all log messages from this <strong>Host</strong>, as well as from all web
+ applications running on this <strong>Host</strong>.</li>
<li><a href="realm.html">Realm</a> - Configure a realm that will allow your
database of users, and their associated roles, to be shared across all
- of the web applications running within this <b>Host</b>.
- </li>
+ of the web applications running within this <strong>Host</strong>.</li>
</ul>
<br>
@@ -164,13 +154,13 @@
created by web servers, or in any custom format desired.</p>
<p>You can ask Catalina to create an access log for all requests to any
-web application for this <b>Host</b>, by nesting an element like this inside
-your <b>Host</b> element:</p>
+web application for this <strong>Host</strong>, by nesting an element
+like this inside your <strong>Host</strong> element:</p>
<pre>
- <Host name="www.mycompany.com" ...>
+ <Host name="localhost" ...>
...
- <Valve className="org.apache.tomcat.valves.AccessLogValve"
+ <Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log." suffix=".txt"
pattern="common"/>
...
@@ -178,30 +168,33 @@
</pre>
-<p>See <a href="valve.html#FIXME">Access Log Valve</a> for more
+<p>See <a href="valve.html#AccessLogValve">Access Log Valve</a> for more
information on the configuration options that are supported.</p>
<h3>Automatic Application Deployment</h3>
-<p>If you are using the standard Host implementation, the following actions
-take place automatically when Catalina is first started. All processing takes
-place in the application base directory configured by the <code>appBase</code>
-attribute. No special configuration is required to enable these activities.
+<p>If you are using the standard <strong>Host</strong> implementation,
+the following actions take place automatically when Catalina is first
+started. All processing takes place in the application base directory
+configured by the <code>appBase</code> property.
+No special configuration is required to enable these activities.
</p>
<ul>
<li>Any web application archive file (that is, a JAR file whose name ends
- with ".war"), that does not have a corresponding diretory of the same
+ with ".war"), that does not have a corresponding directory of the same
name without the extension, will be automatically expanded. The assumption
is that this is a web application archive being deployed on this virtual
host. (If you wish to redeploy an updated WAR file, be sure to delete
- the automatically expanded directory first).
+ the automatically expanded directory first).</li>
<li>Any subdirectory within the <code>appBase</code> directory that appears
to be an unpacked web application (i.e. it contains a
<code>WEB-INF/web.xml</code> file), receives an automatically generated
<a href="context.html">Context</a> element, even if this directory is
not specifically mentioned in the <code>conf/server.xml</code> file.
The context path for this application will be a slash character ("/")
- followed by the directory name.
+ followed by the directory name, unless the directory name is
+ <code>ROOT</code>, in which case the context path will be "" (the
+ empty string).</li>
</ul>
<p>The net effect of this feature is that you need not specifically mention
@@ -213,7 +206,7 @@
<p>In many server environments, the system administrator has set up more
than one host name in the Domain Name Service (DNS) entries for a company,
-and you would like all of these names to access the same <b>Host</b>
+and you would like all of these names to access the same <strong>Host</strong>
component (and therefore execute the same web applications), no matter
which host name was actually used in the request.</p>
@@ -230,7 +223,7 @@
</pre>
<p>With this setup, both of the following URLs will resolve to the same
-web application (assuming my <a href="connector.html">Connector</a>
+web application (assuming your <strong>Connector</strong>
is listening on port 8080):
<pre>
http://mycompany.com:8080
@@ -239,12 +232,12 @@
<h3>Lifecycle Listeners</h3>
-<p>If you have implemented a Java object that needs to know when this Host
-is started or stopped, you can declare it by nesting a
+<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
<code><Listener></code> element inside the <code><Host></code>
element. The class you specify in the <code>className</code> attribute
of this Listener must implement the
-<code>org.apache.tomcat.LifecycleListener</code> interface, and it will be
+<code>org.apache.catalina.LifecycleListener</code> interface, and it will be
notified about the occurrence of the corresponding lifecycle events.</p>
<p>Configuration for such a listener might look like this:</p>
@@ -258,32 +251,30 @@
</pre>
-<p>See <a href="listener.html">Listeners</a> for more information about
-lifecycle listeners.</p>
-
<h3>Request Filters</h3>
<p>You can ask Catalina to check the IP address, or host name, of an
-incoming request for this particular host
+incoming request for this virtual host
against a list of "accept" and "deny" filters, which are
defined using the Regular Expression syntax supported by the jakarta-regexp
regular expression library system. Requests that come from remote locations
-that are not accepted will be rejected with an HTTP "Forbidden" error. An
-example configuration that rejects requests from any domain
-except "mycompany.com" would be:</p>
+that are not accepted will be rejected with an HTTP "Forbidden" error.
+Example filter declarations:</p>
<pre>
- <Host name="www.mycompany.com" ...>
+ <Host name="localhost" ...>
...
- <Valve className="org.apache.tomcat.valves.RemoteHostValve"
- allow="*.mycompany.com"/>
+ <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>
-<p>See <a href="valve.html#FIXME">Request Filter Valve</a> for more
-information on the syntax of the filters, and the logic that is applied
+<p>See <a href="valve.html#RequestFilterValve">Request Filter Valve</a> for
+more information on the syntax of the filters, and the logic that is applied
when they are executed.</p>
<h3>User Web Applications</h3>
@@ -298,9 +289,9 @@
<Host name="www.mycompany.com" ...>
...
- <Listener className="org.apache.tomcat.startup.UserConfig"
+ <Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
- userClass="org.apache.tomcat.startup.PasswdUserDatabase"/>
+ userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
...
</Host>
@@ -313,17 +304,19 @@
<Host name="www.mycompany.com" ...>
...
- <Listener className="org.apache.tomcat.startup.UserConfig"
+ <Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
homeBase="c:\Homes"
- userClass="org.apache.tomcat.startup.HomesUserDatabase"/>
+ userClass="org.apache.catalina.startup.HomesUserDatabase"/>
...
</Host>
</pre>
<p>It is also acceptable to include more than one instance of this listener,
if you have more than one home base directory containing user home
-directories.</p>
+directories. In all cases, the <a href="context.html">Context</a> that is
+set up for user directories will have default values, just as is the case
+for Automatic Application Deployment, described above.</p>
<p>With either setup, if my username on the server is <code>craigmcc</code>,
and I have a web application installed in a <code>public_html</code>
@@ -332,7 +325,7 @@
<pre>
http://www.mycompany.com:8080/~craigmcc
</pre>
-<p>assuming my <a href="connector.html">Connector</a> is listening on
+<p>assuming my <strong>Connector</strong> is listening on
port 8080.</p>
<p><b>IMPORTANT NOTE</b>: The operating system username under which
1.2 +91 -10 jakarta-tomcat-4.0/catalina/docs/config/http11.html
Index: http11.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/config/http11.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- http11.html 2000/08/11 05:21:05 1.1
+++ http11.html 2001/01/14 04:17:05 1.2
@@ -17,21 +17,20 @@
<a name="Introduction"></a>
<h2>Introduction</h2>
-<p>The <b>HTTP/1.1 Connector</b> component is a
-<a href="connector.html">Connector</a> implementation that supports the
+<p>The <strong>HTTP/1.1 Connector</strong> component is a
+<strong>Connector</strong> implementation that supports the
HTTP/1.1 protocol. It enables Catalina to
function as a stand-alone web server, in addition to its ability to execute
servlets and serve JSP pages. A particular instance of this component
listens for connections on a configured TCP/IP port number on the server.
One or more such connectors can be configured, each forwarding requests to
-a particular <a href="container.html">Container</a> for processing.</p>
+a particular <a href="engine.html">Engine</a> for processing.</p>
<p>This Connector is configured by including a
<code><Connector></code> element in your <code>conf/server.xml</code>
-configuration file, nested inside the <code><Server></code> element.
+configuration file, nested inside a <a href="service.html">Service</a> element.
All connectors that you have configured are automatically attached to the
-first container that is specified after the connector (typically with an
-<code><Engine></code> element).</p>
+<a href="engine.html">Engine</a> that is specified after the connector.</p>
<p>At server startup time, this Connector will create a number of processor
threads (based on the value of the <code>minProcessors</code> property). Each
@@ -44,11 +43,12 @@
<br>
+
<a name="Component Attributes"></a>
<h2>Component Attributes</h2>
-<p>The <b>HTTP/1.1 Connector</b> supports the following attributes, which are
-defined in a <code><Connector></code> element:</p>
+<p>The <strong>HTTP/1.1 Connector</strong> supports the following attributes:
+</p>
<table border="1" width="100%">
@@ -138,6 +138,7 @@
<br>
+
<a name="Special Features"></a>
<h2>Special Features</h2>
@@ -146,7 +147,7 @@
<p>This Connector supports all of the required features of the HTTP/1.1
protocol as described in RFC 2616, including persistent connections and
chunked encoding. If the client (typically a browser) supports only HTTP/1.0,
-this Connector gracefully falls back to supporting this as well, so that
+the Connector gracefully falls back to supporting this as well, so that
interoperability is maximized. No special configuration is required to
enable this support.</p>
@@ -154,8 +155,88 @@
<p>Any debugging or exception logging information generated by this Connector
will be sent to the <a href="logger.html">Logger</a> associated with the
-<a href="container.html">Container</a> which is used to process requests for
+<a href="engine.html">Engine</a> which is used to process requests for
this Connector.</p>
+
+<h3>SSL Support</h3>
+
+<p>You can enable SSL support for an instance of this
+<strong>Connector</strong> by configuring an appropriate socket factory,
+as follows:</p>
+
+<table border="1" width="100%">
+
+ <tr>
+ <th width="15%">Attribute</th>
+ <th width="85%">Description</th>
+ </tr>
+
+ <tr>
+ <td><code>algorithm</code></td>
+ <td>
+ The certificate encoding algorithm to be used. If not specified, the
+ default value is <code>SunX509</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>className</code></td>
+ <td>
+ The fully qualified Java class name of the SSL socket factory. With the
+ standard <strong>HTTP 1.1</strong> connectory, you must specify
+ <code>org.apache.catalina.net.SSLServerSocketFactory</code> here.
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>clientAuth</code></td>
+ <td>
+ Set to <code>true</code> if you want the SSL stack to require a valid
+ certificate chain from the client before accepting a connection. A
+ <code>false</code> value (which is the default) will not require such
+ a certificate chain.
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>keystoreFile</code></td>
+ <td>
+ The pathname of the keystore file from which the server certificate is
+ loaded. By default, the pathname is the file ".keystore" in the home
+ directory of the operating system username that is running Tomcat.
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>keystorePass</code></td>
+ <td>
+ The password used to access the server certificate from the keystore
+ file identified above. If not specified, the default value is
+ "changeit".
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>keystoreType</code></td>
+ <td>
+ The type of keystore file to be used for the server certificate. If
+ not specified, the default value is "JKS".
+ </td>
+ </tr>
+
+ <tr>
+ <td><code>protocol</code></td>
+ <td>
+ The version of the SSL protocol to use. If not specified, the default
+ value is "TLS".
+ </td>
+ </tr>
+
+</table>
+
+<p>Successful use of SSL support requires that you have installed the JAR
+files from the Java Secure Sockets Extension (JSSE) package into your
+<code>conf/server</code> directory.</p>
<br>