craigmcc 01/08/25 13:06:31
Modified: webapps/tomcat-docs/config context.xml project.xml
Added: webapps/tomcat-docs/config defaultcontext.xml loader.xml
logger.xml manager.xml realm.xml valve.xml
Log:
Finish converting the contents of the Server Configuration Reference
manual to the new documentation format.
Revision Changes Path
1.2 +1 -1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml
Index: context.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- context.xml 2001/08/25 03:37:39 1.1
+++ context.xml 2001/08/25 20:06:30 1.2
@@ -59,7 +59,7 @@
<subsection name="Common Attributes">
- <p>All implementations of <strong>Host</strong>
+ <p>All implementations of <strong>Context</strong>
support the following attributes:</p>
<attributes>
1.4 +2 -3 jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- project.xml 2001/08/25 01:14:13 1.3
+++ project.xml 2001/08/25 20:06:30 1.4
@@ -36,9 +36,8 @@
<item name="Default Context" href="defaultcontext.html"/>
<item name="Loader" href="loader.html"/>
<item name="Logger" href="logger.html"/>
- <item name="Manager" href="manager.html"/>
- <item name="Realm" href="realm.htlm"/>
- <item name="Resources" href="resources.html"/>
+ <item name="Manager" href="manager.html"/>
+ <item name="Realm" href="realm.html"/>
<item name="Valve" href="valve.html"/>
</menu>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/defaultcontext.xml
Index: defaultcontext.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The DefaultContext Component</title>
</properties>
<body>
<section name="Introduction">
<p>The <strong>DefaultContext</strong> element represents a subset of
the configuration settings for a <a href="context.html">Context</a>,
and can be nested inside an <a href="engine.html">Engine</a> or
<a href="host.html">Host</a> element to represent <em>default
configuration properties</em> for Contexts that are automatically
created.</p>
<p>See <a href="host.html#Automatic Application Deployment">Automatic
Application Deployment</a> and
<a href="host.html#User Web Applications">User Web Applications</a>
for more information about the circumstances in which Catalina will
automatically create Contexts for you, based on the configuration
properties that are stored here.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Host</strong>
support the following attributes:</p>
<attributes>
<attribute name="cookies" required="false">
<p>Set to <code>true</code> if you want cookies to be used for
session identifier communication if supported by the client (this
is the default). Set to <code>false</code> if you want to disable
the use of cookies for session identifier communication, and rely
only on URL rewriting by the application.</p>
</attribute>
<attribute name="crossContext" required="false">
<p>Set to <code>true</code> if you want calls within this application
to <code>ServletContext.getContext()</code> to successfully return a
request dispatcher for other web applications running on this virtual
host. Set to <code>false</code> (the default) in security
conscious environments, to make <code>getContext()</code> always
return <code>null</code>.</p>
</attribute>
<attribute name="reloadable" required="false">
<p>Set to <code>true</code> if you want Catalina to monitor classes in
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
changes, and automatically reload the web application if a change
is detected. This feature is very useful during application
development, but it requires significant runtime overhead and is
not recommended for use on deployed production applications. You
can use the <a href="../manager-howto.html">Manager</a> web
application, however, to trigger reloads of deployed applications
on demand.</p>
</attribute>
<attribute name="useNaming" required="false">
<p>Set to <code>true</code> (the default) to have Catalina enable a
JNDI <code>InitialContext</code> for this web application that is
compatible with Java2 Enterprise Edition (J2EE) platform
conventions.</p>
</attribute>
<attribute name="wrapperClass" required="false">
<p>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, a standard default value will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>DefaultContext</strong> is
<strong>org.apache.catalina.core.DefaultContext</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<!--
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your
<strong>DefaultContext</strong> element:</p>
<ul>
<li><a href="loader.html"><strong>Loader</strong></a> -
Configure the web application class loader that will be used to load
servlet and bean classes for each web application. Normally, the
default configuration of the class loader will be sufficient.</li>
<li><a href="logger.html"><strong>Logger</strong></a> -
Configure a logger that will receive
and process all log messages for each <strong>Context</strong>. This
includes application messages logged via calls to
<code>ServletContext.log()</code>.</li>
<li><a href="manager.html"><strong>Manager</strong></a> -
Configure the session manager that will be used to create, destroy,
and persist HTTP sessions for each web application. Normally, the
default configuration of the session manager will be sufficient.</li>
<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 utilized solely
for each particular web application. If not specified, this web
application will utilize the Realm associated with the owning
<a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
<li><a href="resources.html"><strong>Resources</strong></a> -
Configure the resource manager that will be used to access the static
resources associated with each web application. Normally, the
default configuration of the resource manager will be sufficient.</li>
</ul>
-->
</section>
<section name="Special Features">
<subsection name="Lifecycle Listeners">
<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 <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>
<source>
<DefaultContext ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</DefaultContext>
</source>
<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>
</subsection>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/loader.xml
Index: loader.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Loader Component</title>
</properties>
<body>
<section name="Introduction">
<p>The <strong>Loader</strong> element represents the <em>web
application class loader</em> that will be used to load Java
classes and resources for your web application. Such
a class loader must follow the requirements of the Servlet
Specification, and load classes from the following locations:</p>
<ul>
<li>From the <code>/WEB-INF/classes</code> directory inside your
web application.</li>
<li>From JAR files in the <code>/WEB-INF/lib</code> directory
inside your web application.</li>
<li>From resources made available by Catalina to all web
applications globally.</li>
</ul>
<p>A Loader element MAY be nested inside a <a href="context.html">Context</a>
component. If it is not included, a default Loader configuration will be
created automatically, which is sufficient for most requirements.</p>
<p>For a more in-depth description of the class loader hierarchy
that is implemented by Catalina, see <strong>FIXME - Reference</strong>.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Loader</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Loader</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="delegate" required="false">
<p>Set to <code>true</code> if you want the class loader to follow
the standard Java2 delegation model, and attempt to load classes from
parent class loaders <strong>before</strong> looking inside the web
application. Set to <code>false</code> (the default) to have the
class loader look inside the web application first, before asking
parent class loaders to find requested classes or resources.</p>
</attribute>
<attribute name="reloadable" required="false">
<p>Set to <code>true</code> if you want Catalina to monitor classes in
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
changes, and automatically reload the web application if a change
is detected. This feature is very useful during application
development, but it requires significant runtime overhead and is
not recommended for use on deployed production applications. You
can use the <a href="../manager-howto.html">Manager</a> web
application, however, to trigger reloads of deployed applications
on demand.</p>
<p><strong>NOTE</strong> - The value for this property will be
inherited from the <code>reloadable</code> attribute you set on
the surrounding <a href="context.html">Context</a> component,
and any value you explicitly set here will be replaced.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Loader</strong> is
<strong>org.apache.catalina.loader.WebappLoader</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="checkInterval" required="false">
<p>The number of seconds between checks for modified classes and
resources, if <code>reloadable</code> has been set to
<code>true</code>. The default is 15 seconds.</p>
</attribute>
<attribute name="debug" required="false">
<p>The level of debugging detail logged by this <strong>Engine</strong>
to the associated <a href="logger.html">Logger</a>. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).</p>
</attribute>
<attribute name="loaderClass" required="false">
<p>Java class name of the <code>java.lang.ClassLoader</code>
implementation class to use. If not specified, the default value is
<code>org.apache.catalina.loader.WebappClassLoader</code>.</p>
</attribute>
<attribute name="workDir" required="false">
<p>Pathname to a scratch directory to be provided by this Context
for temporary read-write use by servlets within the associated web
application. 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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Loader</strong> element.</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Loader</strong>
element.</p>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/logger.xml
Index: logger.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Logger Component</title>
</properties>
<body>
<section name="Introduction">
<p>A <strong>Logger</strong> element represents a destination for
logging, debugging, and error messages (including stack tracebacks)
for a Catalina container (<a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>).
In addition, Loggers associated with an Engine or a Host are automatically
inherited by lower-level containers, unless explicitly overridden.</p>
<p>For a more in-depth description of the class loader hierarchy
that is implemented by Catalina, see <strong>FIXME - Reference</strong>.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Logger</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Logger</code> interface.</p>
</attribute>
<attribute>
<p>The verbosity level for this logger. Messages with a higher
verbosity level than the specified value will be silently ignored.
Available levels are 0 (fatal messages only), 1 (errors), 2
(warnings), 3 (information), and 4 (debug). If not specified, the
default value will be 1 (error).</p>
<p><strong>NOTE</strong> - Only messages logged with an explicit
verbosity level are compared to this value. Messages logged with
no explicit verbosity level are logged unconditionally.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>Unlike most Catalina components, there are several standard
<strong>Logger</strong> implementations available. As a result,
the <code>className</code> attribute MUST be used to select the
implementation you wish to use.</p>
<h3>File Logger (org.apache.catalina.logger.FileLogger)</h3>
<p>The <strong>File Logger</strong> records all logged messages to
disk file(s) in a specified directory. The actual filenames of the
log files are created from a configured prefix, the current date in
YYYY-MM-DD format, and a configured suffix. On the first logged
message after midnight each day, the current log file will be closed
and a new file opened for the new date, without having to shut down
Catalina in order to perform this switch.</p>
<p>The File Logger supports the following attributes:</p>
<attributes>
<attribute name="directory" required="false">
<p>Absolute or relative pathname of a directory in which log files
created by this logger will be placed. If a relative path is
specified, it is interpreted as relative to $CATALINA_HOME. If
no directory attribute is specified, the default value is "logs"
(relative to $CATALINA_HOME).</p>
</attribute>
<attribute name="prefix" required="false">
<p>The prefix added to the start of each log file's name. If not
specified, the default value is "catalina.". To specify no prefix,
use a zero-length string.</p>
</attribute>
<attribute name="suffix" required="false">
<p>The suffix added to the end of each log file's name. If not
specified, the default value is ".log". To specify no suffix,
use a zero-length string.</p>
</attribute>
<attribute name="timestamp" required="false">
<p>Set to <code>true</code> to cause all logged messages to be
date and time stamped. Set to <code>false</code> (the default)
to skip date/time stamping.</p>
</attribute>
</attributes>
<h3>Standard Error Logger (org.apache.catalina.logger.SystemErrLogger)</h3>
<p>The <strong>Standard Error Logger</strong> records all logged messages
to whatever stream the standard error output of Catalina is pointed at.
The default Catalina startup script points this at file
<code>logs/catalina.out</code> relative to $CATALINA_HOME. This
logger supports no additional attributes.</p>
<h3>Standard Output Logger (org.apache.catalina.logger.SystemOutLogger)</h3>
<p>The <strong>Standard Output Logger</strong> records all logged messages
to whatever stream the standard output of Catalina is pointed at.
The default Catalina startup script points this at file
<code>logs/catalina.out</code> relative to $CATALINA_HOME. This
logger supports no additional attributes.</p>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Logger</strong> element.</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Logger</strong>
element.</p>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/manager.xml
Index: manager.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Manager Component</title>
</properties>
<body>
<section name="Introduction">
<p>The <strong>Manager</strong> element represents the <em>session
manager</em> that will be used to create and maintain HTTP sessions
as requested by the associated web application.</p>
<p>A Manager element MAY be nested inside a
<a href="context.html">Context</a> component. If it is not included,
a default Manager configuration will be created automatically, which
is sufficient for most requirements.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Manager</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Manager</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="distributable" required="false">
<p>Set to <code>true</code> to ask the session manager to enforce
the restrictions described in the Servlet Specification on
distributable applications (primarily, this would mean that all
session attributes must implement <code>java.io.Serializable</code>).
Set to <code>false</code> (the default) to not enforce these
restrictions.</p>
<p><strong>NOTE</strong> - The value for this property is inherited
automatically based on the presence or absence of the
<code><distributable></code> element in the web application
deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
</attribute>
<attribute name="maxInactiveInterval" required="false">
<p>The default maximum inactive interval (in minutes) for Sessions
created by this Manager. If not specified, the default value is
sixty (60) minutes.</p>
<p><strong>NOTE</strong> - The value for this property is inherited
automatically if you specify a <code><session-timeout></code>
element in the web application deployment descriptor
(<code>/WEB-INF/web.xml</code>).</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Manager</strong> is
<strong>org.apache.catalina.session.StandardManager</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="algorithm" required="false">
<p>Name of the <em>Message Digest</em> algorithm used to calculate
session identifiers produced by this Manager. This value must
be supported by the <code>java.security.MessageDigest</code> class.
If not specified, the default value is "MD5".</p>
</attribute>
<attribute name="checkInterval" required="false">
<p>The number of seconds between checks for expired sessions
for this manager. The default value is 60 seconds.</p>
</attribute>
<attribute name="debug" required="false">
<p>The level of debugging detail logged by this <strong>Engine</strong>
to the associated <a href="logger.html">Logger</a>. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).</p>
</attribute>
<attribute name="entropy" required="false">
<p>A String value that is utilized when seeding the random number
generator used to create session identifiers for this Manager.
If not specified, a semi-useful value is calculated, but a long
String value should be specified in security-conscious
environments.</p>
</attribute>
<attribute name="maxActiveSessions" required="false">
<p>The maximum number of active sessions that will be created by
this Manager, or -1 (the default) for no limit.</p>
</attribute>
<attribute name="pathname" required="false">
<p>Absolute or relative (to the work directory for this Context)
pathname of the file in which session state will be preserved
across application restarts, if possible. The default is
"SESSIONS.ser". See <a href="#Restart Persistence">Restart
Persistence</a> for more information.</p>
</attribute>
<attribute name="randomClass" required="false">
<p>Java class name of the <code>java.util.Random</code>
implementation class to use. If not specified, the default value is
<code>java.security.SecureRandom</code>.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Manager</strong> element.</p>
</section>
<section name="Special Features">
<subsection name="Restart Persistence">
<p>Whenver Catalina is shut down normally and restarted, or when an
application reload is triggered, the standard Manager implementation
will attempt to serialize all currently active sessions to a disk
file located via the <code>pathname</code> attribute. All such saved
sessions will then be deserialized and activated (assuming they have
not expired in the mean time) when the application reload is completed.</p>
<p>In order to successfully restore the state of session attributes,
all such attributes MUST implement the <code>java.io.Serializable</code>
interface. You MAY cause the Manager to enforce this restriction by
including the <code><distributable></code> element in your web
application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/realm.xml
Index: realm.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Realm Component</title>
</properties>
<body>
<section name="Introduction">
<p>A <strong>Realm</strong> element represents a "database" of usernames,
passwords, and <em>roles</em> (similar to Unix <em>groups</em>) assigned
to those users. Different implementations of Realm allow Catalina to be
integrated into environments where such authentication information is already
being created and maintained, and then utilize that information to implement
<em>Container Managed Security</em> as described in the Servlet
Specification.</p>
<p>You may nest a Realm inside any Catalina container
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a>). In addition, Realms associated with
an Engine or a Host are automatically inherited by lower-level
containers, unless explicitly overridden.</p>
<p>For more in-depth information about container managed security in web
applications, see <strong>FIXME - link to "Container Managed Security Guide"
in the application developer's section</strong>. For more in-depth
information about configuing and using the standard Realm component
implementations, see <strong>FIXME - link to "Realm Configuration HOW-TO"
in the administrator's section</strong>.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Realm</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Realm</code> interface.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>Unlike most Catalina components, there are several standard
<strong>Realm</strong> implementations available. As a result,
the <code>className</code> attribute MUST be used to select the
implementation you wish to use.</p>
<h3>JDBC Database Realm (org.apache.catalina.realm.JDBCRealm)</h3>
<p>The <strong>JDBC Database Realm</strong> connects Catalina to
a relational database, accessed through an appropriate JDBC driver,
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
changes to the database will be immediately reflected in the
information used to authenticate new logins.</p>
<p>A rich set of additional attributes lets you configure the required
connection to the underlying database, as well as the table and
column names used to retrieve the required information:</p>
<attributes>
<attribute name="connectionName" required="true">
<p>The database username to use when establishing the JDBC
connection.</p>
</attribute>
<attribute name="connectionPassword" required="true">
<p>The database password to use when establishing the JDBC
connection.</p>
</attribute>
<attribute name="connectionURL" required="true">
<p>The connection URL to be passed to the JDBC driver when
establishing a database connection.</p>
</attribute>
<attribute name="digest" required="false">
<p>The name of the <code>MessageDigest</code> algorithm used
to encode user passwords stored in the database. If not specified,
user passwords are assumed to be stored in clear-text.</p>
</attribute>
<attribute name="driverName" required="true">
<p>Fully qualified Java class name of the JDBC driver to be
used to connect to the authentication database.</p>
</attribute>
<attribute name="roleNameCol" required="true">
<p>Name of the column, in the "user roles" table, which contains
a role name assigned to the corresponding user.</p>
</attribute>
<attribute name="userCredCol" required="true">
<p>Name of the column, in the "users" table, which contains
the user's credentials (i.e. password(. If a value for the
<code>digest</code> attribute is specified, this component
will assume that the passwords have been encoded with the
specified algorithm. Otherwise, they will be assumed to be
in clear text.</p>
</attribute>
<attribute name="userNameCol" required="true">
<p>Name of the column, in the "users" and "user roles" table,
that contains the user's username.</p>
</attribute>
<attribute name="userRoleTable" required="true">
<p>Name of the "user roles" table, which must contain columns
named by the <code>userNameCol</code> and <code>roleNameCol</code>
attributes.</p>
</attribute>
<attribute name="userTable" required="true">
<p>Name of the "users" table, which must contain columns named
by the <code>userNameCol</code> and <code>userCredCol</code>
attributes.</p>
</attribute>
</attributes>
<p>See <strong>FIXME - Nested pointer into HOW-TO</strong> for more
information on setting up container managed security using the
JDBC Database Realm component.</p>
<h3>JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)</h3>
<p>The <strong>JNDI Directory Realm</strong> connects Catalina to
an LDAP Directory, accessed through an appropriate JNDI driver,
to perform lookups of usernames, passwords, and their associated
roles. Because the lookup is done each time that it is required,
changes to the directory will be immediately reflected in the
information used to authenticate new logins.</p>
<p>A rich set of additional attributes lets you configure the required
connection to the underlying directory, as well as the element and
attribute names used to retrieve the required information:</p>
<attributes>
<attribute name="connectionName" required="true">
<p>The directory username to use when establishing the JNDI
connection.</p>
</attribute>
<attribute name="connectionPassword" required="true">
<p>The directory password to use when establishing the JNDI
connection.</p>
</attribute>
<attribute name="connectionURL" required="true">
<p>The connection URL to be passed to the JNDI driver when
establishing a connection to the directory.</p>
</attribute>
<attribute name="contextFactory" required="false">
<p>Fully qualified Java class name of the factory class used
to acquire our JNDI <code>InitialContext</code>. By default,
assumes that the standard JNDI LDAP provider will be utilized.</p>
</attribute>
<attribute name="roleBase" required="true">
<p>The base directory element for performing role searches.</p>
</attribute>
<attribute name="roleName" required="true">
<p>The name of the directory attribute to retrieve when selecting
the assigned roles for a user.</p>
</attribute>
<attribute name="roleSearch" required="true">
<p>The LDAP search expression to use when selecting roles for a
particular user, with <code>{0}</code> marking where the actual
username should be inserted.</p>
</attribute>
<attribute name="roleSubtree" required="true">
<p>Set to <code>true</code> to search subtrees of the elements
selected by the <code>roleSearch</code> search expression. Set
to <code>false</code> to not search subtrees.</p>
</attribute>
<attribute name="userPassword" required="true">
<p>Name of the LDAP element containing the user's password.</p>
</attribute>
<attribute name="userPattern" required="true">
<p>The LDAP search expression to use when retrieving the attributes
of a particular user, with <code>{0}</code> marking where the
actual username should be inserted.</p>
</attribute>
</attributes>
<p>See <strong>FIXME - Nested pointer into HOW-TO</strong> for more
information on setting up container managed security using the
JNDI Directory Realm component.</p>
<h3>Memory Based Realm (org.apache.catalina.realm.MemoryRealm)</h3>
<p>The <strong>Memory Based Realm</strong> is a simple Realm implementation
that reads user information from an XML format, and represents it as a
collection of Java objects in memory. This implementation is intended
solely to get up and running with container managed security - it is NOT
intended for production use. As such, there are no mechanisms for
updating the in-memory collection of users when the content of the
underlying data file is changed.</p>
<p>The Memory Based Realm implementation supports the following
additional attributes:</p>
<attributes>
<attribute name="pathname" required="false">
<p>Absolute or relative (to $CATALINA_HOME) pathname to the XML file
containing our user information. See below for details on the
XML element format required. If no pathname is specified, the
default value is <code>conf/tomcat-users.xml</code>.</p>
</attribute>
</attributes>
<p>The XML document referenced by the <code>pathname</code> attribute must
conform to the following requirements:</p>
<ul>
<li>The root (outer) element must be <code><tomcat-users></code>.
</li>
<li>Each authorized user must be represented by a single XML element
<code><user></code>, nested inside the root element.</li>
<li>Each <code><user></code> element must have the following
attributes:
<ul>
<li><strong>name</strong> - Username of this user (must be unique
within this file).</li>
<li><strong>password</strong> - Password of this user (in
clear text).</li>
<li><strong>roles</strong> - Comma-delimited list of the role names
assigned to this user.</li>
</ul></li>
</ul>
<p>See <strong>FIXME - Nested pointer into HOW-TO</strong> for more
information on setting up container managed security using the
Memory Based Realm component.</p>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Realm</strong> element.</p>
</section>
<section name="Special Features">
<p>See <a href="host.html">Single Sign On</a> for information about
configuring Single Sign On support for a virtual host.</p>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/valve.xml
Index: valve.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Valve Component</title>
</properties>
<body>
<section name="Introduction">
<p>A <strong>Valve</strong> element represents a comonent that will be
inserted into the request processing pipeline for the associated
Catalina container (<a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>).
Individual Valves have distinct processing capabilities, and are
described individually below.</p>
</section>
<section name="Access Log Valve">
<subsection name="Introduction">
<p>The <strong>Access Log Valve</strong> creates log files in the same
format as those created by standard web servers. These logs can later
be analyzed by standard log analysis tools to track page hit counts,
user session activity, and so on. The Access Log Valve shares many
configuration and behavior characteristics of the
<a href="logger.html#Standard Implementation">File Logger</a>, including
the automatic rollover of log files at midnight each night. An
Access Log Valve can be associated with any Catalina container, and
will record ALL requests processed by that container.</p>
</subsection>
<subsection name="Attributes">
<p>The <strong>Access Log Valve</strong> supports the following
configuration attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This MUST be set to
<strong>org.apache.catalina.valve.AccessLogValve</strong>.</p>
</attribute>
<attribute name="directory" required="false">
<p>Absolute or relative pathname of a directory in which log files
created by this valve will be placed. If a relative path is
specified, it is interpreted as relative to $CATALINA_HOME. If
no directory attribute is specified, the default value is "logs"
(relative to $CATALINA_HOME).</p>
</attribute>
<attribute name="pattern" required="false">
<p>A formatting layout identifying the various information fields
from the request and response to be logged, or the word
<code>common</code> or <code>combined</code> to select a
standard format. See below for more information on configuring
this attribute.</p>
</attribute>
<attribute name="prefix" required="false">
<p>The prefix added to the start of each log file's name. If not
specified, the default value is "access_log.". To specify no prefix,
use a zero-length string.</p>
</attribute>
<attribute name="resolveHosts" required="false">
<p>Set to <code>true</code> to convert the IP address of the remote
host into the corresponding host name via a DNS lookup. Set to
<code>false</code> to skip this lookup, and report the remote IP
address instead.</p>
</attribute>
<attribute name="suffix" required="false">
<p>The suffix added to the end of each log file's name. If not
specified, the default value is "". To specify no suffix,
use a zero-length string.</p>
</attribute>
</attributes>
<p>Values for the <code>pattern</code> attribute are made up of literal
text strings, combined with pattern identifiers prefixed by the "%"
character to cause replacement by the corresponding variable value from
the current request and response. The following pattern codes are
supported:</p>
<ul>
<li><b>%a</b> - Remote IP address</li>
<li><b>%A</b> - Local IP address</li>
<li><b>%b</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li>
<li><b>%B</b> - Bytes sent, excluding HTTP headers</li>
<li><b>%h</b> - Remote host name (or IP address if
<code>resolveHosts</code> is false)</li>
<li><b>%H</b> - Request protocol</li>
<li><b>%l</b> - Remote logical username from identd (always returns
'-')</li>
<li><b>%m</b> - Request method (GET, POST, etc.)</li>
<li><b>%p</b> - Local port on which this request was received</li>
<li><b>%q</b> - Query string (prepended with a '?' if it exists)</li>
<li><b>%r</b> - First line of the request (method and request URI)</li>
<li><b>%s</b> - HTTP status code of the response</li>
<li><b>%t</b> - Date and time, in Common Log Format</li>
<li><b>%u</b> - Remote user that was authenticated (if any), else '-'</li>
<li><b>%U</b> - Requested URL path</li>
<li><b>%v</b> - Local server name</li>
</ul>
<p>The shorthand pattern name <code>common</code> (which is also the
default) corresponds to <strong>%h %l %u %t "%r" %s %b"</strong>.</p>
<p>The shorthand pattern name <code>combined</code> appends the
values of the <code>Referer</code> and <code>User-Agent</code> headers,
each in double quotes, to the <code>common</code> pattern
described in the previous paragraph.</p>
</subsection>
</section>
<section name="Remote Address Filter">
<subsection name="Introduction">
<p>The <strong>Remote Address Filter</strong> allows you to compare the
IP address of the client that submitted this request against one or more
<em>regular expressions</em>, and either allow the request to continue
or refuse to process the request from this client. A Remote Address
Filter can be associated with any Catalina container
(<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a>), and must accept any request
presented to this container for processing before it will be passed on.</p>
</subsection>
<subsection name="Attributes">
<p>The <strong>Remote Address Filter</strong> supports the following
configuration attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This MUST be set to
<strong>org.apache.catalina.valve.RemoteAddrValve</strong>.</p>
</attribute>
<attribute name="accept" required="false">
<p>A comma-separated list of <em>regular expression</em> patterns
that the remote client's IP address is compared to. If this attribute
is specified, the remote address MUST match for this request to be
accepted. If this attribute is not specified, all requests will be
excepted UNLESS the remote address matches a <code>deny</code>
pattern.</p>
</attribute>
<attribute name="deny" required="false">
<p>A comma-separated list of <em>regular expression</em> patterns
that the remote client's IP address is compared to. If this attribute
is specified, the remote address MUST NOT match for this request to be
accepted. If this attribute is not specified, request acceptance is
governed solely by the <code>accept</code> attribute.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Remote Host Filter">
<subsection name="Introduction">
<p>The <strong>Remote Host Filter</strong> allows you to compare the
hostname of the client that submitted this request against one or more
<em>regular expressions</em>, and either allow the request to continue
or refuse to process the request from this client. A Remote Host
Filter can be associated with any Catalina container
(<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a>), and must accept any request
presented to this container for processing before it will be passed on.</p>
</subsection>
<subsection name="Attributes">
<p>The <strong>Remote Host Filter</strong> supports the following
configuration attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This MUST be set to
<strong>org.apache.catalina.valve.RemoteHostValve</strong>.</p>
</attribute>
<attribute name="accept" required="false">
<p>A comma-separated list of <em>regular expression</em> patterns
that the remote client's hostname is compared to. If this attribute
is specified, the remote hostname MUST match for this request to be
accepted. If this attribute is not specified, all requests will be
excepted UNLESS the remote hostname matches a <code>deny</code>
pattern.</p>
</attribute>
<attribute name="deny" required="false">
<p>A comma-separated list of <em>regular expression</em> patterns
that the remote client's hostname is compared to. If this attribute
is specified, the remote hostname MUST NOT match for this request to be
accepted. If this attribute is not specified, request acceptance is
governed solely by the <code>accept</code> attribute.</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>
