Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 67d615191938bb60e9b73af6701f5339749950ca / . / tomcat-uidm / webapps / docs / config / valve.html
blob: 615d32edc1be992406b74e01e9beef83debdbeb4 [file] [log] [blame]
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.41) - The Valve Component</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </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="
5 The Apache Tomcat Servlet/JSP Container
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="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></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="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/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>web.xml</strong></p><ul><li><a href="filter.html">Filter</a></li></ul><p><strong>Other</strong></p><ul><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>Apache Tomcat Configuration Reference</h1><h2>The Valve Component</h2><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>
7<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="#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></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="#Request_Dumper_Valve">Request Dumper Valve</a><ol><li><a href="#Request_Dumper_Valve/Introduction">Introduction</a></li><li><a href="#Request_Dumper_Valve/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="#WebDAV_Fix_Valve">WebDAV Fix Valve</a><ol><li><a href="#WebDAV_Fix_Valve/Introduction">Introduction</a></li><li><a href="#WebDAV_Fix_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="#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><li><a href="#SSL_Valve">SSL Valve</a><ol><li><a href="#SSL_Valve/Introduction">Introduction</a></li><li><a href="#SSL_Valve/Attributes">Attributes</a></li></ol></li></ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]8</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>
9
10 <p>A <strong>Valve</strong> element represents a component that will be
11 inserted into the request processing pipeline for the associated
12 Catalina container (<a href="engine.html">Engine</a>,
13 <a href="host.html">Host</a>, or <a href="context.html">Context</a>).
14 Individual Valves have distinct processing capabilities, and are
15 described individually below.</p>
16
17 <blockquote><em>
18 <p>The description below uses the variable name $CATALINA_BASE to refer the
19 base directory against which most relative paths are resolved. If you have
20 not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
21 directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
22 the directory into which you have installed Tomcat 6.</p>
23 </em></blockquote>
24
25</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>
26
27 <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>
28
29 <p>The <strong>Access Log Valve</strong> creates log files in the same
30 format as those created by standard web servers. These logs can later
31 be analyzed by standard log analysis tools to track page hit counts,
32 user session activity, and so on. The files produces by this <code>Valve</code>
33 are rolled over nightly at midnight. This <code>Valve</code>
34 may be associated with any Catalina container (<code>Context</code>,
35 <code>Host</code>, or <code>Engine</code>), and
36 will record ALL requests processed by that container.</p>
37
38 <p>Some requests may be handled by Tomcat before they are passed to a
39 container. These include redirects from /foo to /foo/ and the rejection of
40 invalid requests. Where Tomcat can identify the <code>Context</code> that
41 would have handled the request, the request/response will be logged in the
42 <code>AccessLog</code>(s) associated <code>Context</code>, <code>Host</code>
43 and <code>Engine</code>. Where Tomcat cannot identify the
44 <code>Context</code> that would have handled the request, e.g. in cases
45 where the URL is invalid, Tomcat will look first in the <code>Engine</code>,
46 then the default <code>Host</code> for the <code>Engine</code> and finally
47 the ROOT (or default) <code>Context</code> for the default <code>Host</code>
48 for an <code>AccessLog</code> implementation. Tomcat will use the first
49 <code>AccessLog</code> implementation found to log those requests that are
50 rejected before they are passed to a container.</p>
51
52 </blockquote></td></tr></table>
53
54 <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>
55
56 <p>The <strong>Access Log Valve</strong> supports the following
57 configuration attributes:</p>
58
59 <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>className</code></strong></td><td align="left" valign="center">
60 <p>Java class name of the implementation to use. This MUST be set to
61 <strong>org.apache.catalina.valves.AccessLogValve</strong> to use the
62 default access log valve.</p>
63 </td></tr><tr><td align="left" valign="center"><code>directory</code></td><td align="left" valign="center">
64 <p>Absolute or relative pathname of a directory in which log files
65 created by this valve will be placed. If a relative path is
66 specified, it is interpreted as relative to $CATALINA_BASE. If
67 no directory attribute is specified, the default value is "logs"
68 (relative to $CATALINA_BASE).</p>
69 </td></tr><tr><td align="left" valign="center"><code>encoding</code></td><td align="left" valign="center">
70 <p>Character set used to write the log file. An empty string means
71 to use the system default character set. Default value: use the
72 system default character set.
73 </p>
74 </td></tr><tr><td align="left" valign="center"><code>pattern</code></td><td align="left" valign="center">
75 <p>A formatting layout identifying the various information fields
76 from the request and response to be logged, or the word
77 <code>common</code> or <code>combined</code> to select a
78 standard format. See below for more information on configuring
79 this attribute. Note that the optimized access does only support
80 <code>common</code> and <code>combined</code> as the value for this
81 attribute.</p>
82 </td></tr><tr><td align="left" valign="center"><code>prefix</code></td><td align="left" valign="center">
83 <p>The prefix added to the start of each log file's name. If not
84 specified, the default value is "access_log.". To specify no prefix,
85 use a zero-length string.</p>
86 </td></tr><tr><td align="left" valign="center"><code>resolveHosts</code></td><td align="left" valign="center">
87 <p>Set to <code>true</code> to convert the IP address of the remote
88 host into the corresponding host name via a DNS lookup. Set to
89 <code>false</code> to skip this lookup, and report the remote IP
90 address instead.</p>
91 </td></tr><tr><td align="left" valign="center"><code>suffix</code></td><td align="left" valign="center">
92 <p>The suffix added to the end of each log file's name. If not
93 specified, the default value is "". To specify no suffix,
94 use a zero-length string.</p>
95 </td></tr><tr><td align="left" valign="center"><code>rotatable</code></td><td align="left" valign="center">
96 <p>Flag to determine if log rotation should occur.
97 If set to <code>false</code>, then this file is never rotated and
98 <code>fileDateFormat</code> is ignored. Use with caution!
99 Default value: <code>true</code>
100 </p>
101 </td></tr><tr><td align="left" valign="center"><code>condition</code></td><td align="left" valign="center">
102 <p>Turns on conditional logging. If set, requests will be
103 logged only if <code>ServletRequest.getAttribute()</code> is
104 null. For example, if this value is set to
105 <code>junk</code>, then a particular request will only be logged
106 if <code>ServletRequest.getAttribute("junk") == null</code>.
107 The use of Filters is an easy way to set/unset the attribute
108 in the ServletRequest on many different requests.
109 </p>
110 </td></tr><tr><td align="left" valign="center"><code>fileDateFormat</code></td><td align="left" valign="center">
111 <p>Allows a customized date format in the access log file name.
112 The date format also decides how often the file is rotated.
113 If you wish to rotate every hour, then set this value
114 to: <code>yyyy-MM-dd.HH</code>
115 </p>
116 </td></tr><tr><td align="left" valign="center"><code>buffered</code></td><td align="left" valign="center">
117 <p>Flag to determine if logging will be buffered.
118 If set to <code>false</code>, then access logging will be written after each
119 request. Default value: <code>true</code>
120 </p>
121 </td></tr></table>
122
123 <p>Values for the <code>pattern</code> attribute are made up of literal
124 text strings, combined with pattern identifiers prefixed by the "%"
125 character to cause replacement by the corresponding variable value from
126 the current request and response. The following pattern codes are
127 supported:</p>
128 <ul>
129 <li><b>%a</b> - Remote IP address</li>
130 <li><b>%A</b> - Local IP address</li>
131 <li><b>%b</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li>
132 <li><b>%B</b> - Bytes sent, excluding HTTP headers</li>
133 <li><b>%h</b> - Remote host name (or IP address if
134 <code>resolveHosts</code> is false)</li>
135 <li><b>%H</b> - Request protocol</li>
136 <li><b>%l</b> - Remote logical username from identd (always returns
137 '-')</li>
138 <li><b>%m</b> - Request method (GET, POST, etc.)</li>
139 <li><b>%p</b> - Local port on which this request was received</li>
140 <li><b>%q</b> - Query string (prepended with a '?' if it exists)</li>
141 <li><b>%r</b> - First line of the request (method and request URI)</li>
142 <li><b>%s</b> - HTTP status code of the response</li>
143 <li><b>%S</b> - User session ID</li>
144 <li><b>%t</b> - Date and time, in Common Log Format</li>
145 <li><b>%u</b> - Remote user that was authenticated (if any), else '-'</li>
146 <li><b>%U</b> - Requested URL path</li>
147 <li><b>%v</b> - Local server name</li>
148 <li><b>%D</b> - Time taken to process the request, in millis</li>
149 <li><b>%T</b> - Time taken to process the request, in seconds</li>
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]150 <li><b>%I</b> - Current request thread name (can compare later with stacktraces)</li>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]151 </ul>
152
153 <p>
154 There is also support to write information from the cookie, incoming
155 header, the Session or something else in the ServletRequest.
156 It is modeled after the
157 <a href="http://httpd.apache.org/">Apache HTTP Server</a> log configuration
158 syntax:</p>
159 <ul>
160 <li><b><code>%{xxx}i</code></b> for incoming headers</li>
161 <li><b><code>%{xxx}o</code></b> for outgoing response headers</li>
162 <li><b><code>%{xxx}c</code></b> for a specific cookie</li>
163 <li><b><code>%{xxx}r</code></b> xxx is an attribute in the ServletRequest</li>
164 <li><b><code>%{xxx}s</code></b> xxx is an attribute in the HttpSession</li>
165 </ul>
166
167
168 <p>The shorthand pattern name <code>common</code> (which is also the
169 default) corresponds to <strong>'%h %l %u %t "%r" %s %b'</strong>.</p>
170
171 <p>The shorthand pattern name <code>combined</code> appends the
172 values of the <code>Referer</code> and <code>User-Agent</code> headers,
173 each in double quotes, to the <code>common</code> pattern
174 described in the previous paragraph.</p>
175
176 </blockquote></td></tr></table>
177
178</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>
179
180 <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>
181
182 <p>The <strong>Remote Address Filter</strong> allows you to compare the
183 IP address of the client that submitted this request against one or more
184 <em>regular expressions</em>, and either allow the request to continue
185 or refuse to process the request from this client. A Remote Address
186 Filter can be associated with any Catalina container
187 (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
188 <a href="context.html">Context</a>), and must accept any request
189 presented to this container for processing before it will be passed on.</p>
190
191 <p>The syntax for <em>regular expressions</em> is different than that for
192 'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code>
193 package. Please consult the Java documentation for details of the
194 expressions supported.</p>
195
196 <p>See also: <a href="#Remote_Host_Filter">Remote Host Filter</a>,
197 <a href="#Remote_IP_Valve">Remote IP Valve</a>.</p>
198
199 </blockquote></td></tr></table>
200
201 <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>
202
203 <p>The <strong>Remote Address Filter</strong> supports the following
204 configuration attributes:</p>
205
206 <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>className</code></strong></td><td align="left" valign="center">
207 <p>Java class name of the implementation to use. This MUST be set to
208 <strong>org.apache.catalina.valves.RemoteAddrValve</strong>.</p>
209 </td></tr><tr><td align="left" valign="center"><code>allow</code></td><td align="left" valign="center">
210 <p>A comma-separated list of <em>regular expression</em> patterns
211 that the remote client's IP address is compared to. If this attribute
212 is specified, the remote address MUST match for this request to be
213 accepted. If this attribute is not specified, all requests will be
214 accepted UNLESS the remote address matches a <code>deny</code>
215 pattern.</p>
216 </td></tr><tr><td align="left" valign="center"><code>deny</code></td><td align="left" valign="center">
217 <p>A comma-separated list of <em>regular expression</em> patterns
218 that the remote client's IP address is compared to. If this attribute
219 is specified, the remote address MUST NOT match for this request to be
220 accepted. If this attribute is not specified, request acceptance is
221 governed solely by the <code>accept</code> attribute.</p>
222 </td></tr><tr><td align="left" valign="center"><code>denyStatus</code></td><td align="left" valign="center">
223 <p>HTTP response status code that is used when rejecting denied
224 request. The default value is <code>403</code>. For example,
225 it can be set to the value <code>404</code>.</p>
226 </td></tr></table>
227
228 </blockquote></td></tr></table>
229
230</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>
231
232 <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>
233
234 <p>The <strong>Remote Host Filter</strong> allows you to compare the
235 hostname of the client that submitted this request against one or more
236 <em>regular expressions</em>, and either allow the request to continue
237 or refuse to process the request from this client. A Remote Host
238 Filter can be associated with any Catalina container
239 (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
240 <a href="context.html">Context</a>), and must accept any request
241 presented to this container for processing before it will be passed on.</p>
242
243 <p>The syntax for <em>regular expressions</em> is different than that for
244 'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code>
245 package. Please consult the Java documentation for details of the
246 expressions supported.</p>
247
248 <p><strong>Note:</strong> This filter processes the value returned by
249 method <code>ServletRequest.getRemoteHost()</code>. To allow the method
250 to return proper host names, you have to enable "DNS lookups" feature on
251 a <strong>Connector</strong>.</p>
252
253 <p>See also: <a href="#Remote_Address_Filter">Remote Address Filter</a>,
254 <a href="http.html">HTTP Connector</a> configuration.</p>
255
256 </blockquote></td></tr></table>
257
258 <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>
259
260 <p>The <strong>Remote Host Filter</strong> supports the following
261 configuration attributes:</p>
262
263 <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>className</code></strong></td><td align="left" valign="center">
264 <p>Java class name of the implementation to use. This MUST be set to
265 <strong>org.apache.catalina.valves.RemoteHostValve</strong>.</p>
266 </td></tr><tr><td align="left" valign="center"><code>allow</code></td><td align="left" valign="center">
267 <p>A comma-separated list of <em>regular expression</em> patterns
268 that the remote client's hostname is compared to. If this attribute
269 is specified, the remote hostname MUST match for this request to be
270 accepted. If this attribute is not specified, all requests will be
271 accepted UNLESS the remote hostname matches a <code>deny</code>
272 pattern.</p>
273 </td></tr><tr><td align="left" valign="center"><code>deny</code></td><td align="left" valign="center">
274 <p>A comma-separated list of <em>regular expression</em> patterns
275 that the remote client's hostname is compared to. If this attribute
276 is specified, the remote hostname MUST NOT match for this request to be
277 accepted. If this attribute is not specified, request acceptance is
278 governed solely by the <code>accept</code> attribute.</p>
279 </td></tr><tr><td align="left" valign="center"><code>denyStatus</code></td><td align="left" valign="center">
280 <p>HTTP response status code that is used when rejecting denied
281 request. The default value is <code>403</code>. For example,
282 it can be set to the value <code>404</code>.</p>
283 </td></tr></table>
284
285 </blockquote></td></tr></table>
286
287</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Dumper Valve"><!--()--></a><a name="Request_Dumper_Valve"><strong>Request Dumper Valve</strong></a></font></td></tr><tr><td><blockquote>
288
289
290 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Dumper Valve/Introduction"><!--()--></a><a name="Request_Dumper_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
291
292 <p>The <em>Request Dumper Valve</em> is a useful tool in debugging
293 interactions with a client application (or browser) that is sending
294 HTTP requests to your Tomcat-based server. When configured, it causes
295 details about each request processed by its associated <code>Engine</code>,
296 <code>Host</code>, or <code>Context</code> to be logged according to
297 the logging configuration for that container.</p>
298
299 <p><strong>WARNING: Using this valve has side-effects.</strong> The
300 output from this valve includes any parameters included with the request.
301 The parameters will be decoded using the default platform encoding. Any
302 subsequent calls to <code>request.setCharacterEncoding()</code> within
303 the web application will have no effect. NOTE: Since all parameters are
304 included in the output, the InputStream is consumed for requests made with
305 the method POST and content-type application/x-www-form-urlencoded.</p>
306
307 </blockquote></td></tr></table>
308
309
310 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Dumper Valve/Attributes"><!--()--></a><a name="Request_Dumper_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
311
312 <p>The <strong>Request Dumper Valve</strong> supports the following
313 configuration attributes:</p>
314
315 <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>className</code></strong></td><td align="left" valign="center">
316 <p>Java class name of the implementation to use. This MUST be set to
317 <strong>org.apache.catalina.valves.RequestDumperValve</strong>.</p>
318 </td></tr></table>
319
320 </blockquote></td></tr></table>
321
322
323</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>
324
325 <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>
326
327 <p>The <em>Single Sign On Valve</em> is utilized when you wish to give users
328 the ability to sign on to any one of the web applications associated with
329 your virtual host, and then have their identity recognized by all other
330 web applications on the same virtual host.</p>
331
332 <p>See the <a href="host.html#Single Sign On">Single Sign On</a> special
333 feature on the <strong>Host</strong> element for more information.</p>
334
335 </blockquote></td></tr></table>
336
337
338 <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>
339
340 <p>The <strong>Single Sign On</strong> Valve supports the following
341 configuration attributes:</p>
342
343 <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>className</code></strong></td><td align="left" valign="center">
344 <p>Java class name of the implementation to use. This MUST be set to
345 <strong>org.apache.catalina.authenticator.SingleSignOn</strong>.</p>
346 </td></tr><tr><td align="left" valign="center"><code>requireReauthentication</code></td><td align="left" valign="center">
347 <p>Default false. Flag to determine whether each request needs to be
348 reauthenticated to the security <strong>Realm</strong>. If "true", this
349 Valve uses cached security credentials (username and password) to
350 reauthenticate to the <strong>Realm</strong> each request associated
351 with an SSO session. If "false", the Valve can itself authenticate
352 requests based on the presence of a valid SSO cookie, without
353 rechecking with the <strong>Realm</strong>.</p>
354 </td></tr><tr><td align="left" valign="center"><code>cookieDomain</code></td><td align="left" valign="center">
355 <p>Sets the host domain to be used for sso cookies.</p>
356 </td></tr></table>
357
358 </blockquote></td></tr></table>
359
360
361</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>
362
363 <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>
364
365 <p>The <strong>Basic Authenticator Valve</strong> is automatically added to
366 any <a href="context.html">Context</a> that is configured to use BASIC
367 authentication.</p>
368
369 <p>If any non-default settings are required, the valve may be configured
370 within <a href="context.html">Context</a> element with the required
371 values.</p>
372
373 </blockquote></td></tr></table>
374
375 <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>
376
377 <p>The <strong>Basic Authenticator Valve</strong> supports the following
378 configuration attributes:</p>
379
380 <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>className</code></strong></td><td align="left" valign="center">
381 <p>Java class name of the implementation to use. This MUST be set to
382 <strong>org.apache.catalina.authenticator.BasicAuthenticator</strong>.</p>
383 </td></tr><tr><td align="left" valign="center"><code>changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
384 <p>Controls if the session ID is changed if a session exists at the
385 point where users are authenticated. This is to prevent session fixation
386 attacks. If not set, the default value of <code>true</code> will be
387 used.</p>
388 </td></tr><tr><td align="left" valign="center"><code>cnonceCacheSize</code></td><td align="left" valign="center">
389 <p>To protect against replay attacks, the DIGEST authenticator tracks
390 client nonce and nonce count values. This attribute controls the size
391 of that cache. If not specified, the default value of 1000 is used.</p>
392 </td></tr><tr><td align="left" valign="center"><code>disableProxyCaching</code></td><td align="left" valign="center">
393 <p>Controls the caching of pages that are protected by security
394 constraints. Setting this to <code>false</code> may help work around
395 caching issues in some browsers but will also cause secured pages to be
396 cached by proxies which will almost certainly be a security issue.
397 <code>securePagesWithPragma</code> offers an alternative, secure,
398 workaround for browser caching issues. If not set, the default value of
399 <code>true</code> will be used.</p>
400 </td></tr><tr><td align="left" valign="center"><code>key</code></td><td align="left" valign="center">
401 <p>The secret key used by digest authentication. If not set, a secure
402 random value is generated. This should normally only be set when it is
403 necessary to keep key values constant either across server restarts
404 and/or across a cluster.</p>
405 </td></tr><tr><td align="left" valign="center"><code>nonceValidity</code></td><td align="left" valign="center">
406 <p>The time, in milliseconds, that a server generated nonce will be
407 considered valid for use in authentication. If not specified, the
408 default value of 300000 (5 minutes) will be used.</p>
409 </td></tr><tr><td align="left" valign="center"><code>opaque</code></td><td align="left" valign="center">
410 <p>The opaque server string used by digest authentication. If not set, a
411 random value is generated. This should normally only be set when it is
412 necessary to keep opaque values constant either across server restarts
413 and/or across a cluster.</p>
414 </td></tr><tr><td align="left" valign="center"><code>securePagesWithPragma</code></td><td align="left" valign="center">
415 <p>Controls the caching of pages that are protected by security
416 constraints. Setting this to <code>false</code> may help work around
417 caching issues in some browsers by using
418 <code>Cache-Control: private</code> rather than the default of
419 <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
420 If not set, the default value of <code>true</code> will be used.</p>
421 </td></tr><tr><td align="left" valign="center"><code>validateUri</code></td><td align="left" valign="center">
422 <p>Should the URI be validated as required by RFC2617? If not specified,
423 the default value of <code>true</code> will be used. This should
424 normally only be set when Tomcat is located behind a reverse proxy and
425 the proxy is modifying the URI passed to Tomcat such that DIGEST
426 authentication always fails.</p>
427 </td></tr></table>
428
429 </blockquote></td></tr></table>
430
431</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>
432
433 <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>
434
435 <p>The <strong>Digest Authenticator Valve</strong> is automatically added to
436 any <a href="context.html">Context</a> that is configured to use DIGEST
437 authentication.</p>
438
439 <p>If any non-default settings are required, the valve may be configured
440 within <a href="context.html">Context</a> element with the required
441 values.</p>
442
443 </blockquote></td></tr></table>
444
445 <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>
446
447 <p>The <strong>Digest Authenticator Valve</strong> supports the following
448 configuration attributes:</p>
449
450 <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>cache</code></td><td align="left" valign="center">
451 <p>Should we cache authenticated Principals if the request is part of an
452 HTTP session? If not specified, the default value of <code>false</code>
453 will be used.</p>
454 </td></tr><tr><td align="left" valign="center"><strong><code>className</code></strong></td><td align="left" valign="center">
455 <p>Java class name of the implementation to use. This MUST be set to
456 <strong>org.apache.catalina.authenticator.DigestAuthenticator</strong>.</p>
457 </td></tr><tr><td align="left" valign="center"><code>changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
458 <p>Controls if the session ID is changed if a session exists at the
459 point where users are authenticated. This is to prevent session fixation
460 attacks. If not set, the default value of <code>true</code> will be
461 used.</p>
462 </td></tr><tr><td align="left" valign="center"><code>disableProxyCaching</code></td><td align="left" valign="center">
463 <p>Controls the caching of pages that are protected by security
464 constraints. Setting this to <code>false</code> may help work around
465 caching issues in some browsers but will also cause secured pages to be
466 cached by proxies which will almost certainly be a security issue.
467 <code>securePagesWithPragma</code> offers an alternative, secure,
468 workaround for browser caching issues. If not set, the default value of
469 <code>true</code> will be used.</p>
470 </td></tr><tr><td align="left" valign="center"><code>key</code></td><td align="left" valign="center">
471 <p>The secret key used by digest authentication. If not set, a secure
472 random value is generated. This should normally only be set when it is
473 necessary to keep key values constant either across server restarts
474 and/or across a cluster.</p>
475 </td></tr><tr><td align="left" valign="center"><code>nonceCacheSize</code></td><td align="left" valign="center">
476 <p>To protect against replay attacks, the DIGEST authenticator tracks
477 server nonce and nonce count values. This attribute controls the size
478 of that cache. If not specified, the default value of 1000 is used.</p>
479 </td></tr><tr><td align="left" valign="center"><code>nonceValidity</code></td><td align="left" valign="center">
480 <p>The time, in milliseconds, that a server generated nonce will be
481 considered valid for use in authentication. If not specified, the
482 default value of 300000 (5 minutes) will be used.</p>
483 </td></tr><tr><td align="left" valign="center"><code>opaque</code></td><td align="left" valign="center">
484 <p>The opaque server string used by digest authentication. If not set, a
485 random value is generated. This should normally only be set when it is
486 necessary to keep opaque values constant either across server restarts
487 and/or across a cluster.</p>
488 </td></tr><tr><td align="left" valign="center"><code>securePagesWithPragma</code></td><td align="left" valign="center">
489 <p>Controls the caching of pages that are protected by security
490 constraints. Setting this to <code>false</code> may help work around
491 caching issues in some browsers by using
492 <code>Cache-Control: private</code> rather than the default of
493 <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
494 If not set, the default value of <code>true</code> will be used.</p>
495 </td></tr><tr><td align="left" valign="center"><code>validateUri</code></td><td align="left" valign="center">
496 <p>Should the URI be validated as required by RFC2617? If not specified,
497 the default value of <code>true</code> will be used. This should
498 normally only be set when Tomcat is located behind a reverse proxy and
499 the proxy is modifying the URI passed to Tomcat such that DIGEST
500 authentication always fails.</p>
501 </td></tr></table>
502
503 </blockquote></td></tr></table>
504
505</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>
506
507 <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>
508
509 <p>The <strong>Form Authenticator Valve</strong> is automatically added to
510 any <a href="context.html">Context</a> that is configured to use FORM
511 authentication.</p>
512
513 <p>If any non-default settings are required, the valve may be configured
514 within <a href="context.html">Context</a> element with the required
515 values.</p>
516
517 </blockquote></td></tr></table>
518
519 <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>
520
521 <p>The <strong>Form Authenticator Valve</strong> supports the following
522 configuration attributes:</p>
523
524 <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>className</code></strong></td><td align="left" valign="center">
525 <p>Java class name of the implementation to use. This MUST be set to
526 <strong>org.apache.catalina.authenticator.FormAuthenticator</strong>.</p>
527 </td></tr><tr><td align="left" valign="center"><code>changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
528 <p>Controls if the session ID is changed if a session exists at the
529 point where users are authenticated. This is to prevent session fixation
530 attacks. If not set, the default value of <code>true</code> will be
531 used.</p>
532 </td></tr><tr><td align="left" valign="center"><code>characterEncoding</code></td><td align="left" valign="center">
533 <p>Character encoding to use to read the username and password parameters
534 from the request. If not set, the encoding of the request body will be
535 used.</p>
536 </td></tr><tr><td align="left" valign="center"><code>disableProxyCaching</code></td><td align="left" valign="center">
537 <p>Controls the caching of pages that are protected by security
538 constraints. Setting this to <code>false</code> may help work around
539 caching issues in some browsers but will also cause secured pages to be
540 cached by proxies which will almost certainly be a security issue.
541 <code>securePagesWithPragma</code> offers an alternative, secure,
542 workaround for browser caching issues. If not set, the default value of
543 <code>true</code> will be used.</p>
544 </td></tr><tr><td align="left" valign="center"><code>securePagesWithPragma</code></td><td align="left" valign="center">
545 <p>Controls the caching of pages that are protected by security
546 constraints. Setting this to <code>false</code> may help work around
547 caching issues in some browsers by using
548 <code>Cache-Control: private</code> rather than the default of
549 <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
550 If not set, the default value of <code>true</code> will be used.</p>
551 </td></tr></table>
552
553 </blockquote></td></tr></table>
554
555</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>
556
557 <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>
558
559 <p>The <strong>SSL Authenticator Valve</strong> is automatically added to
560 any <a href="context.html">Context</a> that is configured to use SSL
561 authentication.</p>
562
563 <p>If any non-default settings are required, the valve may be configured
564 within <a href="context.html">Context</a> element with the required
565 values.</p>
566
567 </blockquote></td></tr></table>
568
569 <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>
570
571 <p>The <strong>SSL Authenticator Valve</strong> supports the following
572 configuration attributes:</p>
573
574 <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>className</code></strong></td><td align="left" valign="center">
575 <p>Java class name of the implementation to use. This MUST be set to
576 <strong>org.apache.catalina.authenticator.SSLAuthenticator</strong>.</p>
577 </td></tr><tr><td align="left" valign="center"><code>changeSessionIdOnAuthentication</code></td><td align="left" valign="center">
578 <p>Controls if the session ID is changed if a session exists at the
579 point where users are authenticated. This is to prevent session fixation
580 attacks. If not set, the default value of <code>true</code> will be
581 used.</p>
582 </td></tr><tr><td align="left" valign="center"><code>disableProxyCaching</code></td><td align="left" valign="center">
583 <p>Controls the caching of pages that are protected by security
584 constraints. Setting this to <code>false</code> may help work around
585 caching issues in some browsers but will also cause secured pages to be
586 cached by proxies which will almost certainly be a security issue.
587 <code>securePagesWithPragma</code> offers an alternative, secure,
588 workaround for browser caching issues. If not set, the default value of
589 <code>true</code> will be used.</p>
590 </td></tr><tr><td align="left" valign="center"><code>securePagesWithPragma</code></td><td align="left" valign="center">
591 <p>Controls the caching of pages that are protected by security
592 constraints. Setting this to <code>false</code> may help work around
593 caching issues in some browsers by using
594 <code>Cache-Control: private</code> rather than the default of
595 <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>.
596 If not set, the default value of <code>true</code> will be used.</p>
597 </td></tr></table>
598
599 </blockquote></td></tr></table>
600
601</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="WebDAV Fix Valve"><!--()--></a><a name="WebDAV_Fix_Valve"><strong>WebDAV Fix Valve</strong></a></font></td></tr><tr><td><blockquote>
602
603 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="WebDAV Fix Valve/Introduction"><!--()--></a><a name="WebDAV_Fix_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
604
605 <p>Microsoft operating systems have two WebDAV clients. One is used with
606 port 80, the other is used for all other ports. The implementation used with
607 port 80 does not adhere to the WebDAV specification and fails when trying to
608 communicate with the Tomcat WebDAV Servlet. This valve provides a fix for
609 this by forcing the use of the WebDAV implementation that works, even when
610 connecting via port 80.</p>
611
612 <p>This Valve may be used at the <code>Engine</code>, <code>Host</code> or
613 <code>Context</code> level as required. Normally, this Valve would be used
614 at the <code>Context</code> level.</p>
615
616 </blockquote></td></tr></table>
617
618 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="WebDAV Fix Valve/Attributes"><!--()--></a><a name="WebDAV_Fix_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
619
620 <p>The <strong>WebDAV Fix Valve</strong> supports the following
621 configuration attributes:</p>
622
623 <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>className</code></strong></td><td align="left" valign="center">
624 <p>Java class name of the implementation to use. This MUST be set to
625 <strong>org.apache.catalina.valves.WebdavFixValve</strong>.</p>
626 </td></tr></table>
627
628 </blockquote></td></tr></table>
629
630</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>
631
632 <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>
633
634 <p>Tomcat port of
635 <a href="http://httpd.apache.org/docs/trunk/mod/mod_remoteip.html">mod_remoteip</a>,
636 this valve replaces the apparent client remote IP address and hostname for
637 the request with the IP address list presented by a proxy or a load balancer
638 via a request headers (e.g. "X-Forwarded-For").</p>
639
640 <p>Another feature of this valve is to replace the apparent scheme
641 (http/https), server port and <code>request.secure</code> with the scheme presented
642 by a proxy or a load balancer via a request header
643 (e.g. "X-Forwarded-Proto").</p>
644
645 <p>This Valve may be used at the <code>Engine</code>, <code>Host</code> or
646 <code>Context</code> level as required. Normally, this Valve would be used
647 at the <code>Engine</code> level.</p>
648
649 <p>If used in conjunction with Remote Address/Host valves then this valve
650 should be defined first to ensure that the correct client IP address is
651 presented to the Remote Address/Host valves.</p>
652
653 </blockquote></td></tr></table>
654
655 <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>
656
657 <p>The <strong>Remote IP Valve</strong> supports the
658 following configuration attributes:</p>
659
660 <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>className</code></strong></td><td align="left" valign="center">
661 <p>Java class name of the implementation to use. This MUST be set to
662 <strong>org.apache.catalina.valves.RemoteIpValve</strong>.</p>
663 </td></tr><tr><td align="left" valign="center"><code>remoteIpHeader</code></td><td align="left" valign="center">
664 <p>Name of the HTTP Header read by this valve that holds the list of
665 traversed IP addresses starting from the requesting client. If not
666 specified, the default of <code>x-forwarded-for</code> is used.</p>
667 </td></tr><tr><td align="left" valign="center"><code>internalProxies</code></td><td align="left" valign="center">
668 <p>List of internal proxies' IP addresses as comma separated regular
669 expressions. If they appear in the <strong>remoteIpHeader</strong>
670 value, they will be trusted and will not appear in the
671 <strong>proxiesHeader</strong> value. If not specified the default value
672 of <code>10\.\d\d?\d?\.\d\d?\d?\.\d\d?\d?,
673 192\.168\.\d\d?\d?\.\d\d?\d?,
674 169\.254\.\d\d?\d?\.\d\d?\d?,
675 127\.\d\d?\d?\.\d\d?\d?\.\d\d?\d?</code> will
676 be used.</p>
677 <p>
678 Note that the individual regular expressions <i>must not</i>
679 contain commas themselves, as the <code>internalProxies</code>
680 value is first split by commas, then parsed into separate regular
681 expression patterns.
682 </p>
683 </td></tr><tr><td align="left" valign="center"><code>proxiesHeader</code></td><td align="left" valign="center">
684 <p>Name of the HTTP header created by this valve to hold the list of
685 proxies that have been processed in the incoming
686 <strong>remoteIpHeader</strong>. If not specified, the default of
687 <code>x-forwarded-by</code> is used.</p>
688 </td></tr><tr><td align="left" valign="center"><code>trustedProxies</code></td><td align="left" valign="center">
689 <p>List of trusted proxies' IP addresses as comma separated regular
690 expressions. If they appear in the <strong>remoteIpHeader</strong>
691 value, they will be trusted and will appear in the
692 <strong>proxiesHeader</strong> value. If not specified, no proxies will
693 be trusted.</p>
694 </td></tr><tr><td align="left" valign="center"><code>protocolHeader</code></td><td align="left" valign="center">
695 <p>Name of the HTTP Header read by this valve that holds the protocol
696 used by the client to connect to the proxy. If not specified, the
697 default of <code>null</code> is used.</p>
698 </td></tr><tr><td align="left" valign="center"><code>protocolHeaderHttpsValue</code></td><td align="left" valign="center">
699 <p>Value of the <strong>protocolHeader</strong> to indicate that it is
700 an HTTPS request. If not specified, the default of <code>https</code> is
701 used.</p>
702 </td></tr><tr><td align="left" valign="center"><code>httpServerPort</code></td><td align="left" valign="center">
703 <p>Value returned by <code>ServletRequest.getServerPort()</code>
704 when the <strong>protocolHeader</strong> indicates <code>http</code>
705 protocol. If not specified, the default of <code>80</code> is
706 used.</p>
707 </td></tr><tr><td align="left" valign="center"><code>httpsServerPort</code></td><td align="left" valign="center">
708 <p>Value returned by <code>ServletRequest.getServerPort()</code>
709 when the <strong>protocolHeader</strong> indicates <code>https</code>
710 protocol. If not specified, the default of <code>443</code> is
711 used.</p>
712 </td></tr></table>
713
714 </blockquote></td></tr></table>
715
716</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Stuck Thread Detection Valve"><!--()--></a><a name="Stuck_Thread_Detection_Valve"><strong>Stuck Thread Detection Valve</strong></a></font></td></tr><tr><td><blockquote>
717
718 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Stuck Thread Detection Valve/Introduction"><!--()--></a><a name="Stuck_Thread_Detection_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
719
720 <p>This valve allows to detect requests that take a long time to process, which might
721 indicate that the thread that is processing it is stuck.</p>
722 <p>When such a request is detected, the current stack trace of its thread is written
723 to Tomcat log with a WARN level.</p>
724 <p>The IDs and names of the stuck threads are available through JMX in the
725 <code>stuckThreadIds</code> and <code>stuckThreadNames</code> attributes.
726 The IDs can be used with the standard Threading JVM MBean
727 (<code>java.lang:type=Threading</code>) to retrieve other information
728 about each stuck thread.</p>
729
730 </blockquote></td></tr></table>
731
732 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Stuck Thread Detection Valve/Attributes"><!--()--></a><a name="Stuck_Thread_Detection_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
733
734 <p>The <strong>Stuck Thread Detection Valve</strong> supports the
735 following configuration attributes:</p>
736
737 <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>className</code></strong></td><td align="left" valign="center">
738 <p>Java class name of the implementation to use. This MUST be set to
739 <strong>org.apache.catalina.valves.StuckThreadDetectionValve</strong>.
740 </p>
741 </td></tr><tr><td align="left" valign="center"><code>threshold</code></td><td align="left" valign="center">
742 <p>Minimum duration in seconds after which a thread is considered stuck.
743 Default is 600 seconds. If set to 0, the detection is disabled.</p>
744 <p>Note: since the detection is done in the background thread of the Container
745 (Engine, Host or Context) declaring this Valve, the threshold should be higher
746 than the <code>backgroundProcessorDelay</code> of this Container.</p>
747 </td></tr></table>
748
749 </blockquote></td></tr></table>
750
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]751</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 Valve"><!--()--></a><a name="SSL_Valve"><strong>SSL Valve</strong></a></font></td></tr><tr><td><blockquote>
752
753 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="SSL Valve/Introduction"><!--()--></a><a name="SSL_Valve/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
754
755 <p>When using mod_proxy_http, the client SSL information is not included in
756 the protocol (unlike mod_jk and mod_proxy_ajp). To make the client SSL
757 information available to Tomcat, some additional configuration is required.
758 In httpd, mod_headers is used to add the SSL information as HTTP headers. In
759 Tomcat, this valve is used to read the information from the HTTP headers and
760 insert it into the request.</p>
761
762 <p>Note: Ensure that the headers are always set by httpd for all requests to
763 prevent a client spoofing SSL information by sending fake headers.</p>
764
765 <p>To configure httpd to set the necessary headers, add the following:</p>
766<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>&lt;IfModule ssl_module&gt;
767 RequestHeader set SSL_CLIENT_CERT "%{SSL_CLIENT_CERT}s"
768 RequestHeader set SSL_CIPHER "%{SSL_CIPHER}s"
769 RequestHeader set SSL_SESSION_ID "%{SSL_SESSION_ID}s"
770 RequestHeader set SSL_CIPHER_USEKEYSIZE "%{SSL_CIPHER_USEKEYSIZE}s"
771&lt;/IfModule&gt;</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
772
773 </blockquote></td></tr></table>
774
775 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="SSL Valve/Attributes"><!--()--></a><a name="SSL_Valve/Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
776
777 <p>The <strong>SSL Valve</strong> supports the following configuration
778 attribute:</p>
779
780 <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>className</code></strong></td><td align="left" valign="center">
781 <p>Java class name of the implementation to use. This MUST be set to
782 <strong>org.apache.catalina.valves.SSLValve</strong>.
783 </p>
784 </td></tr></table>
785
786 </blockquote></td></tr></table>
787
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]788</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
789 Copyright &copy; 1999-2014, Apache Software Foundation
790 </em></font></div></td></tr></table></body></html>