You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by rj...@apache.org on 2012/12/05 21:21:01 UTC
svn commit: r1417624 [19/38] - in /tomcat/site/trunk/docs/tomcat-8.0-doc: ./
api/ appdev/ appdev/sample/ appdev/sample/docs/ appdev/sample/src/
appdev/sample/src/mypackage/ appdev/sample/web/ appdev/sample/web/WEB-INF/
appdev/sample/web/images/ archite...
Added: tomcat/site/trunk/docs/tomcat-8.0-doc/config/valve.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/config/valve.html?rev=1417624&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-8.0-doc/config/valve.html (added)
+++ tomcat/site/trunk/docs/tomcat-8.0-doc/config/valve.html Wed Dec 5 20:20:35 2012
@@ -0,0 +1,1209 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 8 Configuration Reference (8.0.0-dev) - The Valve Component</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
+ .noPrint {display: none;}
+ td#mainBody {width: 100%;}
+ </style><style type="text/css">
+ code {background-color:rgb(224,255,255);padding:0 0.1em;}
+ code.attributeName, code.propertyName {background-color:transparent;}
+ </style><style type="text/css">
+ .wrapped-source code { display: block; background-color: transparent; }
+ .wrapped-source div { margin: 0 0 0 1.25em; }
+ .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
+ </style><style type="text/css">
+ p.notice {
+ border: 1px solid rgb(255, 0, 0);
+ background-color: rgb(238, 238, 238);
+ color: rgb(0, 51, 102);
+ padding: 0.5em;
+ margin: 1em 2em 1em 1em;
+ }
+ </style></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><h1><font face="arial,helvetica,sanserif">Apache Tomcat 8</font></h1><font face="arial,helvetica,sanserif">Version 8.0.0-dev, Dec 5 2012</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 size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executo
r</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/M
embership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Other</strong></p><ul><li><a href="filter.html">Filter</a></li><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Valve Component</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
+<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Access_Log_Valve">Access Log Valve</a><ol><li><a href="#Access_Log_Valve/Introduction">Introduction</a></li><li><a href="#Access_Log_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Extended_Access_Log_Valve">Extended Access Log Valve</a><ol><li><a href="#Extended_Access_Log_Valve/Introduction">Introduction</a></li><li><a href="#Extended_Access_Log_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Remote_Address_Filter">Remote Address Filter</a><ol><li><a href="#Remote_Address_Filter/Introduction">Introduction</a></li><li><a href="#Remote_Address_Filter/Attributes">Attributes</a></li><li><a href="#Example">Example</a></li></ol></li><li><a href="#Remote_Host_Filter">Remote Host Filter</a><ol><li><a href="#Remote_Host_Filter/Introduction">Introduction</a></li><li><a href="#Remote_Host_Filter/Attributes">Attributes</a></li></ol></li><li><a href="#Single_Sign_On_Valve">Single Sign On Valve<
/a><ol><li><a href="#Single_Sign_On_Valve/Introduction">Introduction</a></li><li><a href="#Single_Sign_On_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Basic_Authenticator_Valve">Basic Authenticator Valve</a><ol><li><a href="#Basic_Authenticator_Valve/Introduction">Introduction</a></li><li><a href="#Basic_Authenticator_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Digest_Authenticator_Valve">Digest Authenticator Valve</a><ol><li><a href="#Digest_Authenticator_Valve/Introduction">Introduction</a></li><li><a href="#Digest_Authenticator_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Form_Authenticator_Valve">Form Authenticator Valve</a><ol><li><a href="#Form_Authenticator_Valve/Introduction">Introduction</a></li><li><a href="#Form_Authenticator_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#SSL_Authenticator_Valve">SSL Authenticator Valve</a><ol><li><a href="#SSL_Authenticator_Valve/Introduction">Introduction</a></li><li
><a href="#SSL_Authenticator_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#SPNEGO_Valve">SPNEGO Valve</a><ol><li><a href="#SPNEGO_Valve/Introduction">Introduction</a></li><li><a href="#SPNEGO_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Remote_IP_Valve">Remote IP Valve</a><ol><li><a href="#Remote_IP_Valve/Introduction">Introduction</a></li><li><a href="#Remote_IP_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Crawler_Session_Manager_Valve">Crawler Session Manager Valve</a><ol><li><a href="#Crawler_Session_Manager_Valve/Introduction">Introduction</a></li><li><a href="#Crawler_Session_Manager_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Stuck_Thread_Detection_Valve">Stuck Thread Detection Valve</a><ol><li><a href="#Stuck_Thread_Detection_Valve/Introduction">Introduction</a></li><li><a href="#Stuck_Thread_Detection_Valve/Attributes">Attributes</a></li></ol></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="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>A <strong>Valve</strong> element represents a component 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>
+
+ <blockquote><em>
+ <p>The description below uses the variable name $CATALINA_BASE to refer the
+ base directory against which most relative paths are resolved. If you have
+ not configured Tomcat for multiple instances by setting a CATALINA_BASE
+ directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
+ the directory into which you have installed Tomcat.</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="Access Log Valve"><!--()--></a><a name="Access_Log_Valve"><strong>Access Log Valve</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="Access Log Valve/Introduction"><!--()--></a><a name="Access_Log_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <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 files produces by this <code>Valve</code>
+ are rolled over nightly at midnight. This <code>Valve</code>
+ may be associated with any Catalina container (<code>Context</code>,
+ <code>Host</code>, or <code>Engine</code>), and
+ will record ALL requests processed by that container.</p>
+
+ <p>Some requests may be handled by Tomcat before they are passed to a
+ container. These include redirects from /foo to /foo/ and the rejection of
+ invalid requests. Where Tomcat can identify the <code>Context</code> that
+ would have handled the request, the request/response will be logged in the
+ <code>AccessLog</code>(s) associated <code>Context</code>, <code>Host</code>
+ and <code>Engine</code>. Where Tomcat cannot identify the
+ <code>Context</code> that would have handled the request, e.g. in cases
+ where the URL is invalid, Tomcat will look first in the <code>Engine</code>,
+ then the default <code>Host</code> for the <code>Engine</code> and finally
+ the ROOT (or default) <code>Context</code> for the default <code>Host</code>
+ for an <code>AccessLog</code> implementation. Tomcat will use the first
+ <code>AccessLog</code> implementation found to log those requests that are
+ rejected before they are passed to a container.</p>
+
+ <p>The output file will be placed in the directory given by the
+ <code>directory</code> attribute. The name of the file is composed
+ by concatenation of the configured <code>prefix</code>, timestamp and
+ <code>suffix</code>. The format of the timestamp in the file name can be
+ set using the <code>fileDateFormat</code> attribute. This timestamp will
+ be omitted if the file rotation is switched off by setting
+ <code>rotatable</code> to <code>false</code>.</p>
+
+ <p><strong>Warning:</strong> If multiple AccessLogValve instances
+ are used, they should be configured to use different output files.</p>
+
+ <p>If sendfile is used, the response bytes will be written asynchronously
+ in a separate thread and the access log valve will not know how many bytes
+ were actually written. In this case, the number of bytes that was passed to
+ the sendfile thread for writing will be recorded in the access log valve.
+ </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 Log Valve/Attributes"><!--()--></a><a name="Access_Log_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Access Log Valve</strong> supports the following
+ configuration 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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.AccessLogValve</strong> to use the
+ default access log valve.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">directory</code></td><td align="left" valign="center">
+ <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_BASE. If
+ no directory attribute is specified, the default value is "logs"
+ (relative to $CATALINA_BASE).</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">prefix</code></td><td align="left" valign="center">
+ <p>The prefix added to the start of each log file's name. If not
+ specified, the default value is "access_log.".</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">suffix</code></td><td align="left" valign="center">
+ <p>The suffix added to the end of each log file's name. If not
+ specified, the default value is "" (a zero-length string),
+ meaning that no suffix will be added.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">fileDateFormat</code></td><td align="left" valign="center">
+ <p>Allows a customized timestamp in the access log file name.
+ The file is rotated whenever the formatted timestamp changes.
+ The default value is <code>.yyyy-MM-dd</code>.
+ If you wish to rotate every hour, then set this value
+ to <code>.yyyy-MM-dd.HH</code>.
+ The date format will always be localized
+ using the locale <code>en_US</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">rotatable</code></td><td align="left" valign="center">
+ <p>Flag to determine if log rotation should occur.
+ If set to <code>false</code>, then this file is never rotated and
+ <code>fileDateFormat</code> is ignored.
+ Default value: <code>true</code>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">renameOnRotate</code></td><td align="left" valign="center">
+ <p>By default for a rotatable log the active access log file name
+ will contain the current timestamp in <code>fileDateFormat</code>.
+ During rotation the file is closed and a new file with the next
+ timestamp in the name is created and used. When setting
+ <code>renameOnRotate</code> to <code>true</code>, the timestamp
+ is no longer part of the active log file name. Only during rotation
+ the file is closed and then renamed to include the timestamp.
+ This is similar to the behavior of most log frameworks when
+ doing time based rotation.
+ Default value: <code>false</code>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">pattern</code></td><td align="left" valign="center">
+ <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>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">encoding</code></td><td align="left" valign="center">
+ <p>Character set used to write the log file. An empty string means
+ to use the system default character set. Default value: use the
+ system default character set.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">locale</code></td><td align="left" valign="center">
+ <p>The locale used to format timestamps in the access log
+ lines. Any timestamps configured using an
+ explicit SimpleDateFormat pattern (<code>%{xxx}t</code>)
+ are formatted in this locale. By default the
+ default locale of the Java process is used. Switching the
+ locale after the AccessLogValve is initialized is not supported.
+ Any timestamps using the common log format
+ (<code>CLF</code>) are always formatted in the locale
+ <code>en_US</code>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">requestAttributesEnabled</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> to check for the existence of request
+ attributes (typically set by the RemoteIpValve and similar) that should
+ be used to override the values returned by the request for remote
+ address, remote host, server port and protocol. If the attributes are
+ not set, or this attribute is set to <code>false</code> then the values
+ from the request will be used. If not set, the default value of
+ <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">conditionIf</code></td><td align="left" valign="center">
+ <p>Turns on conditional logging. If set, requests will be
+ logged only if <code>ServletRequest.getAttribute()</code> is
+ not null. For example, if this value is set to
+ <code>important</code>, then a particular request will only be logged
+ if <code>ServletRequest.getAttribute("important") != null</code>.
+ The use of Filters is an easy way to set/unset the attribute
+ in the ServletRequest on many different requests.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">conditionUnless</code></td><td align="left" valign="center">
+ <p>Turns on conditional logging. If set, requests will be
+ logged only if <code>ServletRequest.getAttribute()</code> is
+ null. For example, if this value is set to
+ <code>junk</code>, then a particular request will only be logged
+ if <code>ServletRequest.getAttribute("junk") == null</code>.
+ The use of Filters is an easy way to set/unset the attribute
+ in the ServletRequest on many different requests.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">condition</code></td><td align="left" valign="center">
+ <p>The same as <code>conditionUnless</code>. This attribute is
+ provided for backwards compatibility.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">buffered</code></td><td align="left" valign="center">
+ <p>Flag to determine if logging will be buffered.
+ If set to <code>false</code>, then access logging will be written after each
+ request. Default value: <code>true</code>
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">maxLogMessageBufferSize</code></td><td align="left" valign="center">
+ <p>Log message buffers are usually recycled and re-used. To prevent
+ excessive memory usage, if a buffer grows beyond this size it will be
+ discarded. The default is <code>256</code> characters. This should be
+ set to larger than the typical access log message size.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">resolveHosts</code></td><td align="left" valign="center">
+ <p>This attribute is no longer supported. Use the connector
+ attribute <code>enableLookups</code> instead.</p>
+ <p>If you have <code>enableLookups</code> on the connector set to
+ <code>true</code> and want to ignore it, use <b>%a</b> instead of
+ <b>%h</b> in the value of <code>pattern</code>.</p>
+ </td></tr></table>
+
+ <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>enableLookups</code> for the connector 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>%S</b> - User session ID</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>
+ <li><b>%D</b> - Time taken to process the request, in millis</li>
+ <li><b>%T</b> - Time taken to process the request, in seconds</li>
+ <li><b>%I</b> - Current request thread name (can compare later with stacktraces)</li>
+ </ul>
+
+ <p>
+ There is also support to write information incoming or outgoing
+ headers, cookies, session or request attributes and special
+ timestamp formats.
+ It is modeled after the
+ <a href="http://httpd.apache.org/">Apache HTTP Server</a> log configuration
+ syntax:
+ <ul>
+ <li><b><code>%{xxx}i</code></b> for incoming headers</li>
+ <li><b><code>%{xxx}o</code></b> for outgoing response headers</li>
+ <li><b><code>%{xxx}c</code></b> for a specific cookie</li>
+ <li><b><code>%{xxx}r</code></b> xxx is an attribute in the ServletRequest</li>
+ <li><b><code>%{xxx}s</code></b> xxx is an attribute in the HttpSession</li>
+ <li><b><code>%{xxx}t</code></b> xxx is an enhanced SimpleDateFormat pattern</li>
+ </ul>
+ </p>
+
+ <p>All formats supported by SimpleDateFormat are allowed in <code>%{xxx}t</code>.
+ In addition the following extensions have been added:</p>
+ <ul>
+ <li><b><code>sec</code></b> - number of seconds since the epoch</li>
+ <li><b><code>msec</code></b> - number of milliseconds since the epoch</li>
+ <li><b><code>msec_frac</code></b> - millisecond fraction</li>
+ </ul>
+ <p>These formats can not be mixed with SimpleDateFormat formats in the same format
+ token.</p>
+
+ <p>Furthermore one can define whether to log the timestamp for the request start
+ time or the response finish time:</p>
+ <ul>
+ <li><b><code>begin</code></b> or prefix <b><code>begin:</code></b> chooses
+ the request start time</li>
+ <li><b><code>end</code></b> or prefix <b><code>end:</code></b> chooses
+ the response finish time</li>
+ </ul>
+ <p>By adding multiple <code>%{xxx}t</code> tokens to the pattern, one can
+ also log both timestamps.</p>
+
+ <p>The shorthand pattern <code>pattern="common"</code>
+ corresponds to the Common Log Format defined by
+ <strong>'%h %l %u %t "%r" %s %b'</strong>.</p>
+
+ <p>The shorthand pattern <code>pattern="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.</p>
+
+ </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="Extended Access Log Valve"><!--()--></a><a name="Extended_Access_Log_Valve"><strong>Extended Access Log Valve</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="Extended Access Log Valve/Introduction"><!--()--></a><a name="Extended_Access_Log_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Extended Access Log Valve</strong> is a variant of
+ the Access Log Valve. It is not a real extension of the standard
+ Access Log valve, instead it supports the so-called
+ <a href="http://www.w3.org/TR/WD-logfile.html">Extended Log File Format</a>
+ defined by the W3C. The main difference to the standard
+ <code>AccessLogValve</code> are the supported pattern values.</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="Extended Access Log Valve/Attributes"><!--()--></a><a name="Extended_Access_Log_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Extended Access Log Valve</strong> supports all
+ configuration attributes of the standard
+ <a href="#Access_Log_Valve">Access Log Valve.</a> Only the
+ values used for <code>className</code> and <code>pattern</code> differ.</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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.ExtendedAccessLogValve</strong> to
+ use the extended access log valve.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">pattern</code></td><td align="left" valign="center">
+ <p>A formatting layout identifying the various information fields
+ from the request and response to be logged.
+ See below for more information on configuring this attribute.</p>
+ </td></tr></table>
+
+ <p>Values for the <code>pattern</code> attribute are made up of
+ format tokens. Some of the tokens need an additional prefix. Possible
+ prefixes are <code>c</code> for "client", <code>s</code> for "server",
+ <code>cs</code> for "client to server", <code>sc</code> for
+ "server to client" or <code>x</code> for "application specific".
+ Furthermore some tokens are completed by an additional selector.
+ See the <a href="http://www.w3.org/TR/WD-logfile.html">W3C specification</a>
+ for more information about the format.</p>
+
+ <p>The following format tokens are supported:</p>
+ <ul>
+ <li><b>bytes</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li>
+ <li><b>c-dns</b> - Remote host name (or IP address if
+ <code>enableLookups</code> for the connector is false)</li>
+ <li><b>c-ip</b> - Remote IP address</li>
+ <li><b>cs-method</b> - Request method (GET, POST, etc.)</li>
+ <li><b>cs-uri</b> - Request URI</li>
+ <li><b>cs-uri-query</b> - Query string (prepended with a '?' if it exists)</li>
+ <li><b>cs-uri-stem</b> - Requested URL path</li>
+ <li><b>date</b> - The date in yyyy-mm-dd format for GMT</li>
+ <li><b>s-dns</b> - Local host name</li>
+ <li><b>s-ip</b> - Local IP address</li>
+ <li><b>sc-status</b> - HTTP status code of the response</li>
+ <li><b>time</b> - Time the request was served in HH:mm:ss format for GMT</li>
+ <li><b>time-taken</b> - Time (in seconds as floating point) taken to serve the request</li>
+ <li><b>x-threadname</b> - Current request thread name (can compare later with stacktraces)</li>
+ </ul>
+
+ <p>For any of the <code>x-H(XXX)</code> the following method will be called from the
+ HttpServletRequest object:</p>
+ <ul>
+ <li><b><code>x-H(authType)</code></b>: getAuthType </li>
+ <li><b><code>x-H(characterEncoding)</code></b>: getCharacterEncoding </li>
+ <li><b><code>x-H(contentLength)</code></b>: getContentLength </li>
+ <li><b><code>x-H(locale)</code></b>: getLocale</li>
+ <li><b><code>x-H(protocol)</code></b>: getProtocol </li>
+ <li><b><code>x-H(remoteUser)</code></b>: getRemoteUser</li>
+ <li><b><code>x-H(requestedSessionId)</code></b>: getRequestedSessionId</li>
+ <li><b><code>x-H(requestedSessionIdFromCookie)</code></b>:
+ isRequestedSessionIdFromCookie </li>
+ <li><b><code>x-H(requestedSessionIdValid)</code></b>:
+ isRequestedSessionIdValid</li>
+ <li><b><code>x-H(scheme)</code></b>: getScheme</li>
+ <li><b><code>x-H(secure)</code></b>: isSecure</li>
+ </ul>
+
+ <p>
+ There is also support to write information about headers
+ cookies, context, request or session attributes and request
+ parameters.
+ </p>
+ <ul>
+ <li><b><code>cs(XXX)</code></b> for incoming request headers with name XXX</li>
+ <li><b><code>sc(XXX)</code></b> for outgoing response headers with name XXX</li>
+ <li><b><code>x-A(XXX)</code></b> for the servlet context attribute with name XXX</li>
+ <li><b><code>x-C(XXX)</code></b> for the first cookie with name XXX</li>
+ <li><b><code>x-O(XXX)</code></b> for a concatenation of all outgoing response headers with name XXX</li>
+ <li><b><code>x-P(XXX)</code></b> for the URL encoded (using UTF-8) request parameter with name XXX</li>
+ <li><b><code>x-R(XXX)</code></b> for the request attribute with name XXX</li>
+ <li><b><code>x-S(XXX)</code></b> for the session attribute with name XXX</li>
+ </ul>
+
+ </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="Remote Address Filter"><!--()--></a><a name="Remote_Address_Filter"><strong>Remote Address Filter</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="Remote Address Filter/Introduction"><!--()--></a><a name="Remote_Address_Filter/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <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>
+
+ <p>The syntax for <em>regular expressions</em> is different than that for
+ 'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code>
+ package. Please consult the Java documentation for details of the
+ expressions supported.</p>
+
+ <p><strong>Note:</strong> There is a caveat when using this valve with
+ IPv6 addresses. Format of the IP address that this valve is processing
+ depends on the API that was used to obtain it. If the address was obtained
+ from Java socket using Inet6Address class, its format will be
+ <code>x:x:x:x:x:x:x:x</code>. That is, the IP address for localhost
+ will be <code>0:0:0:0:0:0:0:1</code> instead of the more widely used
+ <code>::1</code>. Consult your access logs for the actual value.</p>
+
+ <p>See also: <a href="#Remote_Host_Filter">Remote Host Filter</a>,
+ <a href="#Remote_IP_Valve">Remote IP Valve</a>.</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="Remote Address Filter/Attributes"><!--()--></a><a name="Remote_Address_Filter/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Remote Address Filter</strong> supports the following
+ configuration 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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.RemoteAddrValve</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">allow</code></td><td align="left" valign="center">
+ <p>A regular expression (using <code>java.util.regex</code>) 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
+ accepted UNLESS the remote address matches a <code>deny</code>
+ pattern.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">deny</code></td><td align="left" valign="center">
+ <p>A regular expression (using <code>java.util.regex</code>) 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>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">denyStatus</code></td><td align="left" valign="center">
+ <p>HTTP response status code that is used when rejecting denied
+ request. The default value is <code>403</code>. For example,
+ it can be set to the value <code>404</code>.</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="Example"><strong>Example</strong></a></font></td></tr><tr><td><blockquote>
+ <p>To allow access only for the clients connecting from localhost:</p>
+<pre>
+ <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+ allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1"/>
+</pre>
+ </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="Remote Host Filter"><!--()--></a><a name="Remote_Host_Filter"><strong>Remote Host Filter</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="Remote Host Filter/Introduction"><!--()--></a><a name="Remote_Host_Filter/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <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>
+
+ <p>The syntax for <em>regular expressions</em> is different than that for
+ 'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code>
+ package. Please consult the Java documentation for details of the
+ expressions supported.</p>
+
+ <p><strong>Note:</strong> This filter processes the value returned by
+ method <code>ServletRequest.getRemoteHost()</code>. To allow the method
+ to return proper host names, you have to enable "DNS lookups" feature on
+ a <strong>Connector</strong>.</p>
+
+ <p>See also: <a href="#Remote_Address_Filter">Remote Address Filter</a>,
+ <a href="http.html">HTTP Connector</a> configuration.</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="Remote Host Filter/Attributes"><!--()--></a><a name="Remote_Host_Filter/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Remote Host Filter</strong> supports the following
+ configuration 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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.RemoteHostValve</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">allow</code></td><td align="left" valign="center">
+ <p>A regular expression (using <code>java.util.regex</code>) 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
+ accepted UNLESS the remote hostname matches a <code>deny</code>
+ pattern.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">deny</code></td><td align="left" valign="center">
+ <p>A regular expression (using <code>java.util.regex</code>) 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>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">denyStatus</code></td><td align="left" valign="center">
+ <p>HTTP response status code that is used when rejecting denied
+ request. The default value is <code>403</code>. For example,
+ it can be set to the value <code>404</code>.</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="Single Sign On Valve"><!--()--></a><a name="Single_Sign_On_Valve"><strong>Single Sign On Valve</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="Single Sign On Valve/Introduction"><!--()--></a><a name="Single_Sign_On_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <em>Single Sign On Vale</em> is utilized when you wish to give users
+ the ability to sign on to any one of the web applications associated with
+ your virtual host, and then have their identity recognized by all other
+ web applications on the same virtual host.</p>
+
+ <p>See the <a href="host.html#Single Sign On">Single Sign On</a> special
+ feature on the <strong>Host</strong> element for more information.</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 Valve/Attributes"><!--()--></a><a name="Single_Sign_On_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Single Sign On</strong> Valve supports the following
+ configuration 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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.authenticator.SingleSignOn</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">requireReauthentication</code></td><td align="left" valign="center">
+ <p>Default false. Flag to determine whether each request needs to be
+ reauthenticated to the security <strong>Realm</strong>. If "true", this
+ Valve uses cached security credentials (username and password) to
+ reauthenticate to the <strong>Realm</strong> each request associated
+ with an SSO session. If "false", the Valve can itself authenticate
+ requests based on the presence of a valid SSO cookie, without
+ rechecking with the <strong>Realm</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cookieDomain</code></td><td align="left" valign="center">
+ <p>Sets the host domain to be used for sso cookies.</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="Basic Authenticator Valve"><!--()--></a><a name="Basic_Authenticator_Valve"><strong>Basic Authenticator Valve</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="Basic Authenticator Valve/Introduction"><!--()--></a><a name="Basic_Authenticator_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Basic Authenticator Valve</strong> is automatically added to
+ any <a href="context.html">Context</a> that is configured to use BASIC
+ authentication.</p>
+
+ <p>If any non-default settings are required, the valve may be configured
+ within <a href="context.html">Context</a> element with the required
+ values.</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="Basic Authenticator Valve/Attributes"><!--()--></a><a name="Basic_Authenticator_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Basic Authenticator Valve</strong> supports the following
+ configuration 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"><code class="attributeName">alwaysUseSession</code></td><td align="left" valign="center">
+ <p>Should a session always be used once a user is authenticated? This
+ may offer some performance benefits since the session can then be used
+ to cache the authenticated Principal, hence removing the need to
+ authenticate the user via the Realm on every request. This may be of
+ help for combinations such as BASIC authentication used with the
+ JNDIRealm or DataSourceRealms. However there will also be the
+ performance cost of creating and GC'ing the session. If not set, the
+ default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cache</code></td><td align="left" valign="center">
+ <p>Should we cache authenticated Principals if the request is part of an
+ HTTP session? If not specified, the default value of <code>true</code>
+ will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
+ <p>Controls if the session ID is changed if a session exists at the
+ point where users are authenticated. This is to prevent session fixation
+ attacks. If not set, the default value of <code>true</code> will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.authenticator.BasicAuthenticator</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">disableProxyCaching</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers but will also cause secured pages to be
+ cached by proxies which will almost certainly be a security issue.
+ <code>securePagesWithPragma</code> offers an alternative, secure,
+ workaround for browser caching issues. If not set, the default value of
+ <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">securePagesWithPragma</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers by using
+ <code>Cache-Control: private</code> rather than the default of
+ <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
+ If not set, the default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center">
+ <p>Name of the algorithm to use to create the
+ <code>java.security.SecureRandom</code> instances that generate session
+ IDs. If an invalid algorithm and/or provider is specified, the platform
+ default provider and the default algorithm will be used. If not
+ specified, the default algorithm of SHA1PRNG will be used. If the
+ default algorithm is not supported, the platform default will be used.
+ To specify that the platform default should be used, do not set the
+ secureRandomProvider attribute and set this attribute to the empty
+ string.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center">
+ <p>Name of the Java class that extends
+ <code>java.security.SecureRandom</code> to use to generate SSO session
+ IDs. If not specified, the default value is
+ <code>java.security.SecureRandom</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center">
+ <p>Name of the provider to use to create the
+ <code>java.security.SecureRandom</code> instances that generate SSO
+ session IDs. If an invalid algorithm and/or provider is specified, the
+ platform default provider and the default algorithm will be used. If not
+ specified, the platform default provider will be used.</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="Digest Authenticator Valve"><!--()--></a><a name="Digest_Authenticator_Valve"><strong>Digest Authenticator Valve</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="Digest Authenticator Valve/Introduction"><!--()--></a><a name="Digest_Authenticator_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Digest Authenticator Valve</strong> is automatically added to
+ any <a href="context.html">Context</a> that is configured to use DIGEST
+ authentication.</p>
+
+ <p>If any non-default settings are required, the valve may be configured
+ within <a href="context.html">Context</a> element with the required
+ values.</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="Digest Authenticator Valve/Attributes"><!--()--></a><a name="Digest_Authenticator_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Digest Authenticator Valve</strong> supports the following
+ configuration 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"><code class="attributeName">alwaysUseSession</code></td><td align="left" valign="center">
+ <p>Should a session always be used once a user is authenticated? This
+ may offer some performance benefits since the session can then be used
+ to cache the authenticated Principal, hence removing the need to
+ authenticate the user via the Realm on every request. This may be of
+ help for combinations such as BASIC authentication used with the
+ JNDIRealm or DataSourceRealms. However there will also be the
+ performance cost of creating and GC'ing the session. If not set, the
+ default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cache</code></td><td align="left" valign="center">
+ <p>Should we cache authenticated Principals if the request is part of an
+ HTTP session? If not specified, the default value of <code>false</code>
+ will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
+ <p>Controls if the session ID is changed if a session exists at the
+ point where users are authenticated. This is to prevent session fixation
+ attacks. If not set, the default value of <code>true</code> will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.authenticator.DigestAuthenticator</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">disableProxyCaching</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers but will also cause secured pages to be
+ cached by proxies which will almost certainly be a security issue.
+ <code>securePagesWithPragma</code> offers an alternative, secure,
+ workaround for browser caching issues. If not set, the default value of
+ <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">key</code></td><td align="left" valign="center">
+ <p>The secret key used by digest authentication. If not set, a secure
+ random value is generated. This should normally only be set when it is
+ necessary to keep key values constant either across server restarts
+ and/or across a cluster.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">nonceCacheSize</code></td><td align="left" valign="center">
+ <p>To protect against replay attacks, the DIGEST authenticator tracks
+ server nonce and nonce count values. This attribute controls the size
+ of that cache. If not specified, the default value of 1000 is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">nonceCountWindowSize</code></td><td align="left" valign="center">
+ <p>Client requests may be processed out of order which in turn means
+ that the nonce count values may be processed out of order. To prevent
+ authentication failures when nonce counts are presented out of order
+ the authenticator tracks a window of nonce count values. This attribute
+ controls how big that window is. If not specified, the default value of
+ 100 is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">nonceValidity</code></td><td align="left" valign="center">
+ <p>The time, in milliseconds, that a server generated nonce will be
+ considered valid for use in authentication. If not specified, the
+ default value of 300000 (5 minutes) will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">opaque</code></td><td align="left" valign="center">
+ <p>The opaque server string used by digest authentication. If not set, a
+ random value is generated. This should normally only be set when it is
+ necessary to keep opaque values constant either across server restarts
+ and/or across a cluster.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">securePagesWithPragma</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers by using
+ <code>Cache-Control: private</code> rather than the default of
+ <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
+ If not set, the default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center">
+ <p>Name of the algorithm to use to create the
+ <code>java.security.SecureRandom</code> instances that generate session
+ IDs. If an invalid algorithm and/or provider is specified, the platform
+ default provider and the default algorithm will be used. If not
+ specified, the default algorithm of SHA1PRNG will be used. If the
+ default algorithm is not supported, the platform default will be used.
+ To specify that the platform default should be used, do not set the
+ secureRandomProvider attribute and set this attribute to the empty
+ string.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center">
+ <p>Name of the Java class that extends
+ <code>java.security.SecureRandom</code> to use to generate SSO session
+ IDs. If not specified, the default value is
+ <code>java.security.SecureRandom</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center">
+ <p>Name of the provider to use to create the
+ <code>java.security.SecureRandom</code> instances that generate SSO
+ session IDs. If an invalid algorithm and/or provider is specified, the
+ platform default provider and the default algorithm will be used. If not
+ specified, the platform default provider will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">validateUri</code></td><td align="left" valign="center">
+ <p>Should the URI be validated as required by RFC2617? If not specified,
+ the default value of <code>true</code> will be used. This should
+ normally only be set when Tomcat is located behind a reverse proxy and
+ the proxy is modifying the URI passed to Tomcat such that DIGEST
+ authentication always fails.</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="Form Authenticator Valve"><!--()--></a><a name="Form_Authenticator_Valve"><strong>Form Authenticator Valve</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="Form Authenticator Valve/Introduction"><!--()--></a><a name="Form_Authenticator_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Form Authenticator Valve</strong> is automatically added to
+ any <a href="context.html">Context</a> that is configured to use FORM
+ authentication.</p>
+
+ <p>If any non-default settings are required, the valve may be configured
+ within <a href="context.html">Context</a> element with the required
+ values.</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="Form Authenticator Valve/Attributes"><!--()--></a><a name="Form_Authenticator_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Form Authenticator Valve</strong> supports the following
+ configuration 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"><code class="attributeName">changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
+ <p>Controls if the session ID is changed if a session exists at the
+ point where users are authenticated. This is to prevent session fixation
+ attacks. If not set, the default value of <code>true</code> will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">characterEncoding</code></td><td align="left" valign="center">
+ <p>Character encoding to use to read the username and password parameters
+ from the request. If not set, the encoding of the request body will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.authenticator.FormAuthenticator</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">disableProxyCaching</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers but will also cause secured pages to be
+ cached by proxies which will almost certainly be a security issue.
+ <code>securePagesWithPragma</code> offers an alternative, secure,
+ workaround for browser caching issues. If not set, the default value of
+ <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">landingPage</code></td><td align="left" valign="center">
+ <p>Controls the behavior of the FORM authentication process if the
+ process is misused, for example by directly requesting the login page
+ or delaying logging in for so long that the session expires. If this
+ attribute is set, rather than returning an error response code, Tomcat
+ will redirect the user to the specified landing page if the login form
+ is submitted with valid credentials. For the login to be processed, the
+ landing page must be a protected resource (i.e. one that requires
+ authentication). If the landing page does not require authentication
+ then the user will not be logged in and will be prompted for their
+ credentials again when they access a protected page.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">securePagesWithPragma</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers by using
+ <code>Cache-Control: private</code> rather than the default of
+ <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
+ If not set, the default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center">
+ <p>Name of the algorithm to use to create the
+ <code>java.security.SecureRandom</code> instances that generate session
+ IDs. If an invalid algorithm and/or provider is specified, the platform
+ default provider and the default algorithm will be used. If not
+ specified, the default algorithm of SHA1PRNG will be used. If the
+ default algorithm is not supported, the platform default will be used.
+ To specify that the platform default should be used, do not set the
+ secureRandomProvider attribute and set this attribute to the empty
+ string.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center">
+ <p>Name of the Java class that extends
+ <code>java.security.SecureRandom</code> to use to generate SSO session
+ IDs. If not specified, the default value is
+ <code>java.security.SecureRandom</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center">
+ <p>Name of the provider to use to create the
+ <code>java.security.SecureRandom</code> instances that generate SSO
+ session IDs. If an invalid algorithm and/or provider is specified, the
+ platform default provider and the default algorithm will be used. If not
+ specified, the platform default provider will be used.</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="SSL Authenticator Valve"><!--()--></a><a name="SSL_Authenticator_Valve"><strong>SSL Authenticator Valve</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="SSL Authenticator Valve/Introduction"><!--()--></a><a name="SSL_Authenticator_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>SSL Authenticator Valve</strong> is automatically added to
+ any <a href="context.html">Context</a> that is configured to use SSL
+ authentication.</p>
+
+ <p>If any non-default settings are required, the valve may be configured
+ within <a href="context.html">Context</a> element with the required
+ values.</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="SSL Authenticator Valve/Attributes"><!--()--></a><a name="SSL_Authenticator_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>SSL Authenticator Valve</strong> supports the following
+ configuration 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"><code class="attributeName">cache</code></td><td align="left" valign="center">
+ <p>Should we cache authenticated Principals if the request is part of an
+ HTTP session? If not specified, the default value of <code>true</code>
+ will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.authenticator.SSLAuthenticator</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
+ <p>Controls if the session ID is changed if a session exists at the
+ point where users are authenticated. This is to prevent session fixation
+ attacks. If not set, the default value of <code>true</code> will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">disableProxyCaching</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers but will also cause secured pages to be
+ cached by proxies which will almost certainly be a security issue.
+ <code>securePagesWithPragma</code> offers an alternative, secure,
+ workaround for browser caching issues. If not set, the default value of
+ <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">securePagesWithPragma</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers by using
+ <code>Cache-Control: private</code> rather than the default of
+ <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
+ If not set, the default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center">
+ <p>Name of the algorithm to use to create the
+ <code>java.security.SecureRandom</code> instances that generate session
+ IDs. If an invalid algorithm and/or provider is specified, the platform
+ default provider and the default algorithm will be used. If not
+ specified, the default algorithm of SHA1PRNG will be used. If the
+ default algorithm is not supported, the platform default will be used.
+ To specify that the platform default should be used, do not set the
+ secureRandomProvider attribute and set this attribute to the empty
+ string.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center">
+ <p>Name of the Java class that extends
+ <code>java.security.SecureRandom</code> to use to generate SSO session
+ IDs. If not specified, the default value is
+ <code>java.security.SecureRandom</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center">
+ <p>Name of the provider to use to create the
+ <code>java.security.SecureRandom</code> instances that generate SSO
+ session IDs. If an invalid algorithm and/or provider is specified, the
+ platform default provider and the default algorithm will be used. If not
+ specified, the platform default provider will be used.</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="SPNEGO Valve"><!--()--></a><a name="SPNEGO_Valve"><strong>SPNEGO Valve</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="SPNEGO Valve/Introduction"><!--()--></a><a name="SPNEGO_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>SPNEGO Authenticator Valve</strong> is automatically added to
+ any <a href="context.html">Context</a> that is configured to use SPNEGO
+ authentication.</p>
+
+ <p>If any non-default settings are required, the valve may be configured
+ within <a href="context.html">Context</a> element with the required
+ values.</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="SPNEGO Valve/Attributes"><!--()--></a><a name="SPNEGO_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>SPNEGO Authenticator Valve</strong> supports the following
+ configuration 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"><code class="attributeName">alwaysUseSession</code></td><td align="left" valign="center">
+ <p>Should a session always be used once a user is authenticated? This
+ may offer some performance benefits since the session can then be used
+ to cache the authenticated Principal, hence removing the need to
+ authenticate the user on every request. This will also help with clients
+ that assume that the server will cache the authenticated user. However
+ there will also be the performance cost of creating and GC'ing the
+ session. For an alternative solution see
+ <code>noKeepAliveUserAgents</code>. If not set, the default value of
+ <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">cache</code></td><td align="left" valign="center">
+ <p>Should we cache authenticated Principals if the request is part of an
+ HTTP session? If not specified, the default value of <code>true</code>
+ will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.authenticator.SpnegoAuthenticator</strong>.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
+ <p>Controls if the session ID is changed if a session exists at the
+ point where users are authenticated. This is to prevent session fixation
+ attacks. If not set, the default value of <code>true</code> will be
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">disableProxyCaching</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers but will also cause secured pages to be
+ cached by proxies which will almost certainly be a security issue.
+ <code>securePagesWithPragma</code> offers an alternative, secure,
+ workaround for browser caching issues. If not set, the default value of
+ <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">loginConfigName</code></td><td align="left" valign="center">
+ <p>The name of the JAAS login configuration to be used to login as the
+ service. If not specified, the default of
+ <code>com.sun.security.jgss.krb5.accept</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">noKeepAliveUserAgents</code></td><td align="left" valign="center">
+ <p>Some clients (not most browsers) expect the server to cache the
+ authenticated user information for a connection and do not resend the
+ credentials with every request. Tomcat will not do this unless an HTTP
+ session is available. A session will be availble if either the
+ application creates one or if <code>alwaysUseSession</code> is enabled
+ for this Authenticator.</p>
+ <p>As an alternative to creating a session, this attribute may be used
+ to define the user agents for which HTTP keep-alive is disabled. This
+ means that a connection will only used for a single request and hence
+ there is no ability to cache authenticated user information per
+ connection. There will be a performance cost in disabling HTTP
+ keep-alive.</p>
+ <p>The attribute should be a regular expression that matches the entire
+ user-agent string, e.g. <code>.*Chrome.*</code>. If not specified, no
+ regular expression will be defined and no user agents will have HTTP
+ keep-alive disabled.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">securePagesWithPragma</code></td><td align="left" valign="center">
+ <p>Controls the caching of pages that are protected by security
+ constraints. Setting this to <code>false</code> may help work around
+ caching issues in some browsers by using
+ <code>Cache-Control: private</code> rather than the default of
+ <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
+ If not set, the default value of <code>false</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomAlgorithm</code></td><td align="left" valign="center">
+ <p>Name of the algorithm to use to create the
+ <code>java.security.SecureRandom</code> instances that generate session
+ IDs. If an invalid algorithm and/or provider is specified, the platform
+ default provider and the default algorithm will be used. If not
+ specified, the default algorithm of SHA1PRNG will be used. If the
+ default algorithm is not supported, the platform default will be used.
+ To specify that the platform default should be used, do not set the
+ secureRandomProvider attribute and set this attribute to the empty
+ string.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomClass</code></td><td align="left" valign="center">
+ <p>Name of the Java class that extends
+ <code>java.security.SecureRandom</code> to use to generate SSO session
+ IDs. If not specified, the default value is
+ <code>java.security.SecureRandom</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">secureRandomProvider</code></td><td align="left" valign="center">
+ <p>Name of the provider to use to create the
+ <code>java.security.SecureRandom</code> instances that generate SSO
+ session IDs. If an invalid algorithm and/or provider is specified, the
+ platform default provider and the default algorithm will be used. If not
+ specified, the platform default provider will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">storeDelegatedCredential</code></td><td align="left" valign="center">
+ <p>Controls if the user' delegated credential will be stored in
+ the user Principal. If available, the delegated credential will be
+ available to applications (e.g. for onward authentication to external
+ services) via the <code>org.apache.catalina.realm.GSS_CREDENTIAL</code>
+ request attribute. If not set, the default value of <code>true</code>
+ will be used.</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="Remote IP Valve"><!--()--></a><a name="Remote_IP_Valve"><strong>Remote IP Valve</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="Remote IP Valve/Introduction"><!--()--></a><a name="Remote_IP_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>Tomcat port of
+ <a href="http://httpd.apache.org/docs/trunk/mod/mod_remoteip.html">mod_remoteip</a>,
+ this valve replaces the apparent client remote IP address and hostname for
+ the request with the IP address list presented by a proxy or a load balancer
+ via a request headers (e.g. "X-Forwarded-For").</p>
+
+ <p>Another feature of this valve is to replace the apparent scheme
+ (http/https), server port and <code>request.secure</code> with the scheme presented
+ by a proxy or a load balancer via a request header
+ (e.g. "X-Forwarded-Proto").</p>
+
+ <p>This Valve may be used at the <code>Engine</code>, <code>Host</code> or
+ <code>Context</code> level as required. Normally, this Valve would be used
+ at the <code>Engine</code> level.</p>
+
+ <p>If used in conjunction with Remote Address/Host valves then this valve
+ should be defined first to ensure that the correct client IP address is
+ presented to the Remote Address/Host valves.</p>
+
+ <p><strong>Note:</strong> By default this valve has no effect on the
+ values that are written into access log. The original values are restored
+ when request processing leaves the valve and that always happens earlier
+ than access logging. To pass the remote address, remote host, server port
+ and protocol values set by this valve to the access log,
+ they are put into request attributes. Publishing these values here
+ is enabled by default, but <code>AccessLogValve</code> should be explicitly
+ configured to use them. See documentation for
+ <code>requestAttributesEnabled</code> attribute of
+ <code>AccessLogValve</code>.</p>
+
+ <p>The names of request attributes that are set by this valve
+ and can be used by access logging are the following:</p>
+
+ <ul>
+ <li><code>org.apache.catalina.AccessLog.RemoteAddr</code></li>
+ <li><code>org.apache.catalina.AccessLog.RemoteHost</code></li>
+ <li><code>org.apache.catalina.AccessLog.Protocol</code></li>
+ <li><code>org.apache.catalina.AccessLog.ServerPort</code></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="Remote IP Valve/Attributes"><!--()--></a><a name="Remote_IP_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Remote IP Valve</strong> supports the
+ following configuration 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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.RemoteIpValve</strong>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">remoteIpHeader</code></td><td align="left" valign="center">
+ <p>Name of the HTTP Header read by this valve that holds the list of
+ traversed IP addresses starting from the requesting client. If not
+ specified, the default of <code>x-forwarded-for</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">internalProxies</code></td><td align="left" valign="center">
+ <p>Regular expression (using <code>java.util.regex</code>) that a
+ proxy's IP address must match to be considered an internal proxy.
+ Internal proxies that appear in the <strong>remoteIpHeader</strong> will
+ be trusted and will not appear in the <strong>proxiesHeader</strong>
+ value. If not specified the default value of <code>
+ 10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}
+ </code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">proxiesHeader</code></td><td align="left" valign="center">
+ <p>Name of the HTTP header created by this valve to hold the list of
+ proxies that have been processed in the incoming
+ <strong>remoteIpHeader</strong>. If not specified, the default of
+ <code>x-forwarded-by</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">requestAttributesEnabled</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> to set the request attributes used by
+ AccessLog implementations to override the values returned by the
+ request for remote address, remote host, server port and protocol.
+ If not set, the default value of <code>true</code> will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">trustedProxies</code></td><td align="left" valign="center">
+ <p>Regular expression (using <code>java.util.regex</code>) that a
+ proxy's IP address must match to be considered an trusted proxy.
+ Trusted proxies that appear in the <strong>remoteIpHeader</strong> will
+ be trusted and will appear in the <strong>proxiesHeader</strong> value.
+ If not specified, no proxies will be trusted.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">protocolHeader</code></td><td align="left" valign="center">
+ <p>Name of the HTTP Header read by this valve that holds the protocol
+ used by the client to connect to the proxy. If not specified, the
+ default of <code>null</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">portHeader</code></td><td align="left" valign="center">
+ <p>Name of the HTTP Header read by this valve that holds the port
+ used by the client to connect to the proxy. If not specified, the
+ default of <code>null</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">protocolHeaderHttpsValue</code></td><td align="left" valign="center">
+ <p>Value of the <strong>protocolHeader</strong> to indicate that it is
+ an HTTPS request. If not specified, the default of <code>https</code> is
+ used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">httpServerPort</code></td><td align="left" valign="center">
+ <p>Value returned by <code>ServletRequest.getServerPort()</code>
+ when the <strong>protocolHeader</strong> indicates <code>http</code>
+ protocol and no <strong>portHeader</strong> is present. If not
+ specified, the default of <code>80</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">httpsServerPort</code></td><td align="left" valign="center">
+ <p>Value returned by <code>ServletRequest.getServerPort()</code>
+ when the <strong>protocolHeader</strong> indicates <code>https</code>
+ protocol and no <strong>portHeader</strong> is present. If not
+ specified, the default of <code>443</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">changeLocalPort</code></td><td align="left" valign="center">
+ <p>If <code>true</code>, the value returned by
+ <code>ServletRequest.getLocalPort()</code> and
+ <code>ServletRequest.getServerPort()</code> is modified by the this
+ valve. If not specified, the default of <code>false</code> is used.</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="Crawler Session Manager Valve"><!--()--></a><a name="Crawler_Session_Manager_Valve"><strong>Crawler Session Manager Valve</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="Crawler Session Manager Valve/Introduction"><!--()--></a><a name="Crawler_Session_Manager_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>Web crawlers can trigger the creation of many thousands of sessions as
+ they crawl a site which may result in significant memory consumption. This
+ Valve ensures that crawlers are associated with a single session - just like
+ normal users - regardless of whether or not they provide a session token
+ with their requests.</p>
+
+ <p>This Valve may be used at the <code>Engine</code>, <code>Host</code> or
+ <code>Context</code> level as required. Normally, this Valve would be used
+ at the <code>Engine</code> level.</p>
+
+ <p>If used in conjunction with Remote IP valve then the Remote IP valve
+ should be defined before this valve to ensure that the correct client IP
+ address is presented to this valve.</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="Crawler Session Manager Valve/Attributes"><!--()--></a><a name="Crawler_Session_Manager_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Crawler Session Manager Valve</strong> supports the
+ following configuration 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 class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This MUST be set to
+ <strong>org.apache.catalina.valves.CrawlerSessionManagerValve</strong>.
+ </p>
[... 79 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org