source: nutchez-0.1/tomcat/webapps/docs/config/printer/valve.html @ 226

Last change on this file since 226 was 66, checked in by waue, 15 years ago

NutchEz - an easy way to nutch
File size: 23.6 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Valve Component</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2    The Apache Tomcat Servlet/JSP Container
3  " align="right" src="../../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat Configuration Reference</h1><h2>The Valve Component</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
4
5  <p>A <strong>Valve</strong> element represents a component that will be
6  inserted into the request processing pipeline for the associated
7  Catalina container (<a href="engine.html">Engine</a>,
8  <a href="host.html">Host</a>, or <a href="context.html">Context</a>).
9  Individual Valves have distinct processing capabilities, and are
10  described individually below.</p>
11
12    <blockquote><em>
13    <p>The description below uses the variable name $CATALINA_BASE to refer the
14    base directory against which most relative paths are resolved. If you have
15    not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
16    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
17    the directory into which you have installed Tomcat 6.</p>
18    </em></blockquote>
19
20</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Access Log Valve"><strong>Access Log Valve</strong></a></font></td></tr><tr><td><blockquote>
21
22  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
23
24    <p>The <strong>Access Log Valve</strong> creates log files in the same
25    format as those created by standard web servers.  These logs can later
26    be analyzed by standard log analysis tools to track page hit counts,
27    user session activity, and so on.  The files produces by this <code>Valve</code>
28    are rolled over nightly at midnight.  This <code>Valve</code>
29    may be associated with any Catalina container (<code>Context</code>,
30    <code>Host</code>, or <code>Engine</code>), and
31    will record ALL requests processed by that container.</p>
32
33  </blockquote></td></tr></table>
34
35  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
36
37    <p>The <strong>Access Log Valve</strong> supports the following
38    configuration attributes:</p>
39
40    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
41        <p>Java class name of the implementation to use.  This MUST be set to
42        <strong>org.apache.catalina.valves.AccessLogValve</strong> to use the
43        default access log valve.</p>
44      </td></tr><tr><td valign="center" align="left"><code>directory</code></td><td valign="center" align="left">
45        <p>Absolute or relative pathname of a directory in which log files
46        created by this valve will be placed.  If a relative path is
47        specified, it is interpreted as relative to $CATALINA_BASE.  If
48        no directory attribute is specified, the default value is "logs"
49        (relative to $CATALINA_BASE).</p>
50      </td></tr><tr><td valign="center" align="left"><code>pattern</code></td><td valign="center" align="left">
51        <p>A formatting layout identifying the various information fields
52        from the request and response to be logged, or the word
53        <code>common</code> or <code>combined</code> to select a
54        standard format.  See below for more information on configuring
55        this attribute. Note that the optimized access does only support
56        <code>common</code> and <code>combined</code> as the value for this
57        attribute.</p>
58      </td></tr><tr><td valign="center" align="left"><code>prefix</code></td><td valign="center" align="left">
59        <p>The prefix added to the start of each log file's name.  If not
60        specified, the default value is "access_log.".  To specify no prefix,
61        use a zero-length string.</p>
62      </td></tr><tr><td valign="center" align="left"><code>resolveHosts</code></td><td valign="center" align="left">
63        <p>Set to <code>true</code> to convert the IP address of the remote
64        host into the corresponding host name via a DNS lookup.  Set to
65        <code>false</code> to skip this lookup, and report the remote IP
66        address instead.</p>
67      </td></tr><tr><td valign="center" align="left"><code>suffix</code></td><td valign="center" align="left">
68        <p>The suffix added to the end of each log file's name.  If not
69        specified, the default value is "".  To specify no suffix,
70        use a zero-length string.</p>
71      </td></tr><tr><td valign="center" align="left"><code>rotatable</code></td><td valign="center" align="left">
72        <p>Deafult true. Flag to determine if log rotation should occur.
73           If set to false, then this file is never rotated and
74           <tt>fileDateFormat</tt> is ignored. Use with caution!
75        </p>
76      </td></tr><tr><td valign="center" align="left"><code>condition</code></td><td valign="center" align="left">
77        <p>Turns on conditional logging. If set, requests will be
78           logged only if <tt>ServletRequest.getAttribute()</tt> is
79           null. For example, if this value is set to
80           <tt>junk</tt>, then a particular request will only be logged
81           if <tt>ServletRequest.getAttribute("junk") == null</tt>.
82           The use of Filters is an easy way to set/unset the attribute
83           in the ServletRequest on many different requests.
84        </p>
85      </td></tr><tr><td valign="center" align="left"><code>fileDateFormat</code></td><td valign="center" align="left">
86        <p>Allows a customized date format in the access log file name.
87           The date format also decides how often the file is rotated.
88           If you wish to rotate every hour, then set this value
89           to: <tt>yyyy-MM-dd.HH</tt>
90        </p>
91      </td></tr><tr><td valign="center" align="left"><code>buffered</code></td><td valign="center" align="left">
92        <p>Deafult true. Flag to determine if logging will be buffered.
93           If set to false, then access logging will be written after each
94           request.
95        </p>
96      </td></tr></table>
97
98    <p>Values for the <code>pattern</code> attribute are made up of literal
99    text strings, combined with pattern identifiers prefixed by the "%"
100    character to cause replacement by the corresponding variable value from
101    the current request and response.  The following pattern codes are
102    supported:</p>
103    <ul>
104    <li><b>%a</b> - Remote IP address</li>
105    <li><b>%A</b> - Local IP address</li>
106    <li><b>%b</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li>
107    <li><b>%B</b> - Bytes sent, excluding HTTP headers</li>
108    <li><b>%h</b> - Remote host name (or IP address if
109        <code>resolveHosts</code> is false)</li>
110    <li><b>%H</b> - Request protocol</li>
111    <li><b>%l</b> - Remote logical username from identd (always returns
112        '-')</li>
113    <li><b>%m</b> - Request method (GET, POST, etc.)</li>
114    <li><b>%p</b> - Local port on which this request was received</li>
115    <li><b>%q</b> - Query string (prepended with a '?' if it exists)</li>
116    <li><b>%r</b> - First line of the request (method and request URI)</li>
117    <li><b>%s</b> - HTTP status code of the response</li>
118    <li><b>%S</b> - User session ID</li>
119    <li><b>%t</b> - Date and time, in Common Log Format</li>
120    <li><b>%u</b> - Remote user that was authenticated (if any), else '-'</li>
121    <li><b>%U</b> - Requested URL path</li>
122    <li><b>%v</b> - Local server name</li>
123    <li><b>%D</b> - Time taken to process the request, in millis</li>
124    <li><b>%T</b> - Time taken to process the request, in seconds</li>
125    <li><b>%I</b> - current request thread name (can compare later with stacktraces)</li>
126    </ul>
127
128    <p>
129    There is also support to write information from the cookie, incoming
130    header, the Session or something else in the ServletRequest.
131    It is modeled after the apache syntax:
132    <ul>
133    <li><b><code>%{xxx}i</code></b> for incoming headers</li>
134    <li><b><code>%{xxx}o</code></b> for outgoing response headers</li>
135    <li><b><code>%{xxx}c</code></b> for a specific cookie</li>
136    <li><b><code>%{xxx}r</code></b> xxx is an attribute in the ServletRequest</li>
137    <li><b><code>%{xxx}s</code></b> xxx is an attribute in the HttpSession</li>
138    </ul>
139    </p>
140
141
142    <p>The shorthand pattern name <code>common</code> (which is also the
143    default) corresponds to <strong>'%h %l %u %t "%r" %s %b'</strong>.</p>
144
145    <p>The shorthand pattern name <code>combined</code> appends the
146    values of the <code>Referer</code> and <code>User-Agent</code> headers,
147    each in double quotes, to the <code>common</code> pattern
148    described in the previous paragraph.</p>
149
150  </blockquote></td></tr></table>
151
152</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Remote Address Filter"><strong>Remote Address Filter</strong></a></font></td></tr><tr><td><blockquote>
153
154  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
155
156    <p>The <strong>Remote Address Filter</strong> allows you to compare the
157    IP address of the client that submitted this request against one or more
158    <em>regular expressions</em>, and either allow the request to continue
159    or refuse to process the request from this client.  A Remote Address
160    Filter can be associated with any Catalina container
161    (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
162    <a href="context.html">Context</a>), and must accept any request
163    presented to this container for processing before it will be passed on.</p>
164
165    <p>The syntax for <em>regular expressions</em> is different than that for
166    'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code>
167    package. Please consult the Java documentation for details of the
168    expressions supported.</p>
169
170  </blockquote></td></tr></table>
171
172  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
173
174    <p>The <strong>Remote Address Filter</strong> supports the following
175    configuration attributes:</p>
176
177    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
178        <p>Java class name of the implementation to use.  This MUST be set to
179        <strong>org.apache.catalina.valves.RemoteAddrValve</strong>.</p>
180      </td></tr><tr><td valign="center" align="left"><code>allow</code></td><td valign="center" align="left">
181        <p>A comma-separated list of <em>regular expression</em> patterns
182        that the remote client's IP address is compared to.  If this attribute
183        is specified, the remote address MUST match for this request to be
184        accepted.  If this attribute is not specified, all requests will be
185        accepted UNLESS the remote address matches a <code>deny</code>
186        pattern.</p>
187      </td></tr><tr><td valign="center" align="left"><code>deny</code></td><td valign="center" align="left">
188        <p>A comma-separated list of <em>regular expression</em> patterns
189        that the remote client's IP address is compared to.  If this attribute
190        is specified, the remote address MUST NOT match for this request to be
191        accepted.  If this attribute is not specified, request acceptance is
192        governed solely by the <code>accept</code> attribute.</p>
193      </td></tr></table>
194
195  </blockquote></td></tr></table>
196
197</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Remote Host Filter"><strong>Remote Host Filter</strong></a></font></td></tr><tr><td><blockquote>
198
199  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
200
201    <p>The <strong>Remote Host Filter</strong> allows you to compare the
202    hostname of the client that submitted this request against one or more
203    <em>regular expressions</em>, and either allow the request to continue
204    or refuse to process the request from this client.  A Remote Host
205    Filter can be associated with any Catalina container
206    (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
207    <a href="context.html">Context</a>), and must accept any request
208    presented to this container for processing before it will be passed on.</p>
209
210    <p>The syntax for <em>regular expressions</em> is different than that for
211    'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code>
212    package. Please consult the Java documentation for details of the
213    expressions supported.</p>
214
215  </blockquote></td></tr></table>
216
217  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
218
219    <p>The <strong>Remote Host Filter</strong> supports the following
220    configuration attributes:</p>
221
222    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
223        <p>Java class name of the implementation to use.  This MUST be set to
224        <strong>org.apache.catalina.valves.RemoteHostValve</strong>.</p>
225      </td></tr><tr><td valign="center" align="left"><code>allow</code></td><td valign="center" align="left">
226        <p>A comma-separated list of <em>regular expression</em> patterns
227        that the remote client's hostname is compared to.  If this attribute
228        is specified, the remote hostname MUST match for this request to be
229        accepted.  If this attribute is not specified, all requests will be
230        accepted UNLESS the remote hostname matches a <code>deny</code>
231        pattern.</p>
232      </td></tr><tr><td valign="center" align="left"><code>deny</code></td><td valign="center" align="left">
233        <p>A comma-separated list of <em>regular expression</em> patterns
234        that the remote client's hostname is compared to.  If this attribute
235        is specified, the remote hostname MUST NOT match for this request to be
236        accepted.  If this attribute is not specified, request acceptance is
237        governed solely by the <code>accept</code> attribute.</p>
238      </td></tr></table>
239
240  </blockquote></td></tr></table>
241
242</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Request Dumper Valve"><strong>Request Dumper Valve</strong></a></font></td></tr><tr><td><blockquote>
243
244
245  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
246
247    <p>The <em>Request Dumper Valve</em> is a useful tool in debugging
248    interactions with a client application (or browser) that is sending
249    HTTP requests to your Tomcat-based server.  When configured, it causes
250    details about each request processed by its associated <code>Engine</code>,
251    <code>Host</code>, or <code>Context</code> to be logged according to
252    the logging configuration for that container.</p>
253
254    <p><strong>WARNING: Using this valve has side-effects.</strong>  The
255    output from this valve includes any parameters included with the request.
256    The parameters will be decoded using the default platform encoding. Any
257    subsequent calls to <code>request.setCharacterEncoding()</code> within
258    the web application will have no effect.</p>
259
260  </blockquote></td></tr></table>
261
262
263  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
264
265    <p>The <strong>Request Dumper Valve</strong> supports the following
266    configuration attributes:</p>
267
268    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
269        <p>Java class name of the implementation to use.  This MUST be set to
270        <strong>org.apache.catalina.valves.RequestDumperValve</strong>.</p>
271      </td></tr></table>
272
273  </blockquote></td></tr></table>
274
275
276</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Single Sign On Valve"><strong>Single Sign On Valve</strong></a></font></td></tr><tr><td><blockquote>
277
278  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
279
280    <p>The <em>Single Sign On Vale</em> is utilized when you wish to give users
281    the ability to sign on to any one of the web applications associated with
282    your virtual host, and then have their identity recognized by all other
283    web applications on the same virtual host.</p>
284
285    <p>See the <a href="host.html#Single Sign On">Single Sign On</a> special
286    feature on the <strong>Host</strong> element for more information.</p>
287
288  </blockquote></td></tr></table>
289
290
291  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
292
293    <p>The <strong>Single Sign On</strong> Valve supports the following
294    configuration attributes:</p>
295
296    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
297        <p>Java class name of the implementation to use.  This MUST be set to
298        <strong>org.apache.catalina.authenticator.SingleSignOn</strong>.</p>
299      </td></tr><tr><td valign="center" align="left"><code>requireReauthentication</code></td><td valign="center" align="left">
300        <p>Default false. Flag to determine whether each request needs to be
301        reauthenticated to the security <strong>Realm</strong>. If "true", this
302        Valve uses cached security credentials (username and password) to
303        reauthenticate to the <strong>Realm</strong> each request associated
304        with an SSO session.  If "false", the Valve can itself authenticate
305        requests based on the presence of a valid SSO cookie, without
306        rechecking with the <strong>Realm</strong>.</p>
307      </td></tr><tr><td valign="center" align="left"><code>cookieDomain</code></td><td valign="center" align="left">
308        <p>Sets the host domain to be used for sso cookies.</p>
309      </td></tr></table>
310
311  </blockquote></td></tr></table>
312
313
314</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Form Authenticator Valve"><strong>Form Authenticator Valve</strong></a></font></td></tr><tr><td><blockquote>
315
316  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
317
318    <p>The <strong>Form Authenticator Valve</strong> is automatically added to
319    any <a href="context.html">Context</a> that is configured to use FORM
320    authentication.</p>
321
322    <p>If any non-default settings are required, the valve may be configured
323    within <a href="context.html">Context</a> element with the required
324    values.</p>
325
326  </blockquote></td></tr></table>
327
328  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
329
330    <p>The <strong>Form Authenticator Valve</strong> supports the following
331    configuration attributes:</p>
332
333    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left">
334        <p>Java class name of the implementation to use.  This MUST be set to
335        <strong>org.apache.catalina.authenticator.FormAuthenticator</strong>.</p>
336      </td></tr><tr><td valign="center" align="left"><code>characterEncoding</code></td><td valign="center" align="left">
337        <p>Character encoding to use to read the username and password parameters
338        from the request. If not set, the encoding of the request body will be
339        used.</p>
340      </td></tr></table>
341
342  </blockquote></td></tr></table>
343
344</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
345        Copyright &copy; 1999-2008, Apache Software Foundation
346        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.