Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 771 | blopes | 1 | <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| 2 | <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The Valve Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo"> |
||
| 3 | Version 9.0.112, |
||
| 4 | <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><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></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</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="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><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></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Valve Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Access_Logging">Access Logging</a><ol><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="#JSON_Access_Log_Valve">JSON Access Log Valve</a><ol><li><a href="#JSON_Access_Log_Valve/Introduction">Introduction</a></li><li><a href="#JSON_Access_Log_Valve/Attributes">Attributes</a></li></ol></li></ol></li><li><a href="#Access_Control">Access Control</a><ol><li><a href="#Remote_Address_Valve">Remote Address Valve</a><ol><li><a href="#Remote_Address_Valve/Introduction">Introduction</a></li><li><a href="#Remote_Address_Valve/Attributes">Attributes</a></li><li><a href="#Remote_Address_Valve/Example_localhost">Example 1</a></li><li><a href="#Remote_Address_Valve/Example_localhost_port">Example 2</a></li><li><a href="#Remote_Address_Valve/Example_port_auth">Example 3</a></li></ol></li><li><a href="#Remote_Host_Valve">Remote Host Valve</a><ol><li><a href="#Remote_Host_Valve/Introduction">Introduction</a></li><li><a href="#Remote_Host_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Remote_CIDR_Valve">Remote CIDR Valve</a><ol><li><a href="#Remote_CIDR_Valve/Introduction">Introduction</a></li><li><a href="#Remote_CIDR_Valve/Attributes">Attributes</a></li><li><a href="#Remote_CIDR_Valve/Example_localhost">Example 1</a></li><li><a href="#Remote_CIDR_Valve/Example_localhost_port">Example 2</a></li><li><a href="#Remote_CIDR_Valve/Example_port_auth">Example 3</a></li></ol></li></ol></li><li><a href="#Proxies_Support">Proxies Support</a><ol><li><a href="#Load_Balancer_Draining_Valve">Load Balancer Draining Valve</a><ol><li><a href="#Load_Balancer_Draining_Valve/Introduction">Introduction</a></li><li><a href="#Load_Balancer_Draining_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="#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></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="#Authentication">Authentication</a><ol><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></ol></li><li><a href="#Error_Report_Valve">Error Report Valve</a><ol><li><a href="#Error_Report_Valve/Introduction">Introduction</a></li><li><a href="#Error_Report_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Json_Error_Report_Valve">Json Error Report Valve</a><ol><li><a href="#Json_Error_Report_Valve/Introduction">Introduction</a></li><li><a href="#Json_Error_Report_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Proxy_Error_Report_Valve">Proxy Error Report Valve</a><ol><li><a href="#Proxy_Error_Report_Valve/Introduction">Introduction</a></li><li><a href="#Proxy_Error_Report_Valve/Attributes">Attributes</a></li><li><a href="#Configuration">Configuration</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><li><a href="#Semaphore_Valve">Semaphore Valve</a><ol><li><a href="#Semaphore_Valve/Introduction">Introduction</a></li><li><a href="#Semaphore_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Health_Check_Valve">Health Check Valve</a><ol><li><a href="#Health_Check_Valve/Introduction">Introduction</a></li><li><a href="#Health_Check_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Persistent_Valve">Persistent Valve</a><ol><li><a href="#Persistent_Valve/Introduction">Introduction</a></li><li><a href="#Persistent_Valve/Attributes">Attributes</a></li></ol></li><li><a href="#Parameter_Limit_Valve">Parameter Limit Valve</a><ol><li><a href="#Parameter_Limit_Valve/Introduction">Introduction</a></li><li><a href="#Parameter_Limit_Valve/Attributes">Attributes</a></li></ol></li></ul> |
||
| 6 | </div><h3 id="Introduction">Introduction</h3><div class="text"> |
||
| 7 | |||
| 8 | <p>A <strong>Valve</strong> element represents a component that will be |
||
| 9 | inserted into the request processing pipeline for the associated |
||
| 10 | Catalina container (<a href="engine.html">Engine</a>, |
||
| 11 | <a href="host.html">Host</a>, or <a href="context.html">Context</a>). |
||
| 12 | Individual Valves have distinct processing capabilities, and are |
||
| 13 | described individually below.</p> |
||
| 14 | |||
| 15 | <p><em>The description below uses the variable name $CATALINA_BASE to refer the |
||
| 16 | base directory against which most relative paths are resolved. If you have |
||
| 17 | not configured Tomcat for multiple instances by setting a CATALINA_BASE |
||
| 18 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, |
||
| 19 | the directory into which you have installed Tomcat.</em></p> |
||
| 20 | |||
| 21 | </div><h3 id="Access_Logging">Access Logging</h3><div class="text"> |
||
| 22 | |||
| 23 | <p>Access logging is performed by valves that implement |
||
| 24 | <strong>org.apache.catalina.AccessLog</strong> interface.</p> |
||
| 25 | |||
| 26 | <div class="subsection"><h4 id="Access_Log_Valve">Access Log Valve</h4><div class="text"> |
||
| 27 | |||
| 28 | <div class="subsection"><h4 id="Access_Log_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 29 | |||
| 30 | <p>The <strong>Access Log Valve</strong> creates log files in the |
||
| 31 | same format as those created by standard web servers. These logs |
||
| 32 | can later be analyzed by standard log analysis tools to track page |
||
| 33 | hit counts, user session activity, and so on. This <code>Valve</code> |
||
| 34 | uses self-contained logic to write its log files, which can be |
||
| 35 | automatically rolled over at midnight each day. (The essential |
||
| 36 | requirement for access logging is to handle a large continuous |
||
| 37 | stream of data with low overhead. This <code>Valve</code> does not |
||
| 38 | use Apache Commons Logging, thus avoiding additional overhead and |
||
| 39 | potentially complex configuration).</p> |
||
| 40 | |||
| 41 | <p>This <code>Valve</code> may be associated with any Catalina container |
||
| 42 | (<code>Context</code>, <code>Host</code>, or <code>Engine</code>), and |
||
| 43 | will record ALL requests processed by that container.</p> |
||
| 44 | |||
| 45 | <p>Some requests may be handled by Tomcat before they are passed to a |
||
| 46 | container. These include redirects from /foo to /foo/ and the rejection of |
||
| 47 | invalid requests. Where Tomcat can identify the <code>Context</code> that |
||
| 48 | would have handled the request, the request/response will be logged in the |
||
| 49 | <code>AccessLog</code>(s) associated <code>Context</code>, <code>Host</code> |
||
| 50 | and <code>Engine</code>. Where Tomcat cannot identify the |
||
| 51 | <code>Context</code> that would have handled the request, e.g. in cases |
||
| 52 | where the URL is invalid, Tomcat will look first in the <code>Engine</code>, |
||
| 53 | then the default <code>Host</code> for the <code>Engine</code> and finally |
||
| 54 | the ROOT (or default) <code>Context</code> for the default <code>Host</code> |
||
| 55 | for an <code>AccessLog</code> implementation. Tomcat will use the first |
||
| 56 | <code>AccessLog</code> implementation found to log those requests that are |
||
| 57 | rejected before they are passed to a container.</p> |
||
| 58 | |||
| 59 | <p>The output file will be placed in the directory given by the |
||
| 60 | <code>directory</code> attribute. The name of the file is composed |
||
| 61 | by concatenation of the configured <code>prefix</code>, timestamp and |
||
| 62 | <code>suffix</code>. The format of the timestamp in the file name can be |
||
| 63 | set using the <code>fileDateFormat</code> attribute. This timestamp will |
||
| 64 | be omitted if the file rotation is switched off by setting |
||
| 65 | <code>rotatable</code> to <code>false</code>.</p> |
||
| 66 | |||
| 67 | <p><strong>Warning:</strong> If multiple AccessLogValve instances |
||
| 68 | are used, they should be configured to use different output files.</p> |
||
| 69 | |||
| 70 | <p>If sendfile is used, the response bytes will be written asynchronously |
||
| 71 | in a separate thread and the access log valve will not know how many bytes |
||
| 72 | were actually written. In this case, the number of bytes that was passed to |
||
| 73 | the sendfile thread for writing will be recorded in the access log valve. |
||
| 74 | </p> |
||
| 75 | </div></div> |
||
| 76 | |||
| 77 | <div class="subsection"><h4 id="Access_Log_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 78 | |||
| 79 | <p>The <strong>Access Log Valve</strong> supports the following |
||
| 80 | configuration attributes:</p> |
||
| 81 | |||
| 82 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 83 | Attribute |
||
| 84 | </th><th style="width: 85%;"> |
||
| 85 | Description |
||
| 86 | </th></tr><tr id="Access Log Valve_Attributes_buffered"><td><code class="attributeName">buffered</code></td><td> |
||
| 87 | <p>Flag to determine if logging will be buffered. |
||
| 88 | If set to <code>false</code>, then access logging will be written after each |
||
| 89 | request. Default value: <code>true</code> |
||
| 90 | </p> |
||
| 91 | </td></tr><tr id="Access Log Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 92 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 93 | <strong>org.apache.catalina.valves.AccessLogValve</strong> to use the |
||
| 94 | default access log valve.</p> |
||
| 95 | </td></tr><tr id="Access Log Valve_Attributes_condition"><td><code class="attributeName">condition</code></td><td> |
||
| 96 | <p>The same as <code>conditionUnless</code>. This attribute is |
||
| 97 | provided for backwards compatibility. |
||
| 98 | </p> |
||
| 99 | </td></tr><tr id="Access Log Valve_Attributes_conditionIf"><td><code class="attributeName">conditionIf</code></td><td> |
||
| 100 | <p>Turns on conditional logging. If set, requests will be |
||
| 101 | logged only if <code>ServletRequest.getAttribute()</code> is |
||
| 102 | not null. For example, if this value is set to |
||
| 103 | <code>important</code>, then a particular request will only be logged |
||
| 104 | if <code>ServletRequest.getAttribute("important") != null</code>. |
||
| 105 | The use of Filters is an easy way to set/unset the attribute |
||
| 106 | in the ServletRequest on many different requests. |
||
| 107 | </p> |
||
| 108 | </td></tr><tr id="Access Log Valve_Attributes_conditionUnless"><td><code class="attributeName">conditionUnless</code></td><td> |
||
| 109 | <p>Turns on conditional logging. If set, requests will be |
||
| 110 | logged only if <code>ServletRequest.getAttribute()</code> is |
||
| 111 | null. For example, if this value is set to |
||
| 112 | <code>junk</code>, then a particular request will only be logged |
||
| 113 | if <code>ServletRequest.getAttribute("junk") == null</code>. |
||
| 114 | The use of Filters is an easy way to set/unset the attribute |
||
| 115 | in the ServletRequest on many different requests. |
||
| 116 | </p> |
||
| 117 | </td></tr><tr id="Access Log Valve_Attributes_directory"><td><code class="attributeName">directory</code></td><td> |
||
| 118 | <p>Absolute or relative pathname of a directory in which log files |
||
| 119 | created by this valve will be placed. If a relative path is |
||
| 120 | specified, it is interpreted as relative to $CATALINA_BASE. If |
||
| 121 | no directory attribute is specified, the default value is "logs" |
||
| 122 | (relative to $CATALINA_BASE).</p> |
||
| 123 | </td></tr><tr id="Access Log Valve_Attributes_encoding"><td><code class="attributeName">encoding</code></td><td> |
||
| 124 | <p>Character set used to write the log file. An empty string means |
||
| 125 | to use the default character set. Default value: UTF-8. |
||
| 126 | </p> |
||
| 127 | </td></tr><tr id="Access Log Valve_Attributes_fileDateFormat"><td><code class="attributeName">fileDateFormat</code></td><td> |
||
| 128 | <p>Allows a customized timestamp in the access log file name. |
||
| 129 | The file is rotated whenever the formatted timestamp changes. |
||
| 130 | The default value is <code>.yyyy-MM-dd</code>. |
||
| 131 | If you wish to rotate every hour, then set this value |
||
| 132 | to <code>.yyyy-MM-dd.HH</code>. |
||
| 133 | The date format will always be localized |
||
| 134 | using the locale <code>en_US</code>. |
||
| 135 | </p> |
||
| 136 | </td></tr><tr id="Access Log Valve_Attributes_ipv6Canonical"><td><code class="attributeName">ipv6Canonical</code></td><td> |
||
| 137 | <p>Flag to determine if IPv6 addresses should be represented in canonical |
||
| 138 | representation format as defined by RFC 5952. If set to <code>true</code>, |
||
| 139 | then IPv6 addresses will be written in canonical format (e.g. |
||
| 140 | <code>2001:db8::1:0:0:1</code>, <code>::1</code>), otherwise it will be |
||
| 141 | represented in full form (e.g. <code>2001:db8:0:0:1:0:0:1</code>, |
||
| 142 | <code>0:0:0:0:0:0:0:1</code>). Default value: <code>false</code> |
||
| 143 | </p> |
||
| 144 | </td></tr><tr id="Access Log Valve_Attributes_locale"><td><code class="attributeName">locale</code></td><td> |
||
| 145 | <p>The locale used to format timestamps in the access log |
||
| 146 | lines. Any timestamps configured using an |
||
| 147 | explicit SimpleDateFormat pattern (<code>%{xxx}t</code>) |
||
| 148 | are formatted in this locale. By default the |
||
| 149 | default locale of the Java process is used. Switching the |
||
| 150 | locale after the AccessLogValve is initialized is not supported. |
||
| 151 | Any timestamps using the common log format |
||
| 152 | (<code>CLF</code>) are always formatted in the locale |
||
| 153 | <code>en_US</code>. |
||
| 154 | </p> |
||
| 155 | </td></tr><tr id="Access Log Valve_Attributes_maxDays"><td><code class="attributeName">maxDays</code></td><td> |
||
| 156 | <p>The maximum number of days rotated access logs will be retained for |
||
| 157 | before being deleted. If not specified, the default value of |
||
| 158 | <code>-1</code> will be used which means never delete old files.</p> |
||
| 159 | </td></tr><tr id="Access Log Valve_Attributes_maxLogMessageBufferSize"><td><code class="attributeName">maxLogMessageBufferSize</code></td><td> |
||
| 160 | <p>Log message buffers are usually recycled and re-used. To prevent |
||
| 161 | excessive memory usage, if a buffer grows beyond this size it will be |
||
| 162 | discarded. The default is <code>256</code> characters. This should be |
||
| 163 | set to larger than the typical access log message size.</p> |
||
| 164 | </td></tr><tr id="Access Log Valve_Attributes_pattern"><td><code class="attributeName">pattern</code></td><td> |
||
| 165 | <p>A formatting layout identifying the various information fields |
||
| 166 | from the request and response to be logged, or the word |
||
| 167 | <code>common</code> or <code>combined</code> to select a |
||
| 168 | standard format. See below for more information on configuring |
||
| 169 | this attribute.</p> |
||
| 170 | </td></tr><tr id="Access Log Valve_Attributes_prefix"><td><code class="attributeName">prefix</code></td><td> |
||
| 171 | <p>The prefix added to the start of each log file's name. If not |
||
| 172 | specified, the default value is "access_log".</p> |
||
| 173 | </td></tr><tr id="Access Log Valve_Attributes_renameOnRotate"><td><code class="attributeName">renameOnRotate</code></td><td> |
||
| 174 | <p>By default for a rotatable log the active access log file name |
||
| 175 | will contain the current timestamp in <code>fileDateFormat</code>. |
||
| 176 | During rotation the file is closed and a new file with the next |
||
| 177 | timestamp in the name is created and used. When setting |
||
| 178 | <code>renameOnRotate</code> to <code>true</code>, the timestamp |
||
| 179 | is no longer part of the active log file name. Only during rotation |
||
| 180 | the file is closed and then renamed to include the timestamp. |
||
| 181 | This is similar to the behavior of most log frameworks when |
||
| 182 | doing time based rotation. |
||
| 183 | Default value: <code>false</code> |
||
| 184 | </p> |
||
| 185 | </td></tr><tr id="Access Log Valve_Attributes_requestAttributesEnabled"><td><code class="attributeName">requestAttributesEnabled</code></td><td> |
||
| 186 | <p>Set to <code>true</code> to check for the existence of request |
||
| 187 | attributes (typically set by the RemoteIpValve and similar) that should |
||
| 188 | be used to override the values returned by the request for remote |
||
| 189 | address, remote host, server port and protocol. If the attributes are |
||
| 190 | not set, or this attribute is set to <code>false</code> then the values |
||
| 191 | from the request will be used. If not set, the default value of |
||
| 192 | <code>false</code> will be used.</p> |
||
| 193 | </td></tr><tr id="Access Log Valve_Attributes_resolveHosts"><td><code class="attributeName">resolveHosts</code></td><td> |
||
| 194 | <p>This attribute is no longer supported. Use the connector |
||
| 195 | attribute <code>enableLookups</code> instead.</p> |
||
| 196 | <p>If you have <code>enableLookups</code> on the connector set to |
||
| 197 | <code>true</code> and want to ignore it, use <b>%a</b> instead of |
||
| 198 | <b>%h</b> in the value of <code>pattern</code>.</p> |
||
| 199 | </td></tr><tr id="Access Log Valve_Attributes_rotatable"><td><code class="attributeName">rotatable</code></td><td> |
||
| 200 | <p>Flag to determine if log rotation should occur. |
||
| 201 | If set to <code>false</code>, then this file is never rotated and |
||
| 202 | <code>fileDateFormat</code> is ignored. |
||
| 203 | Default value: <code>true</code> |
||
| 204 | </p> |
||
| 205 | </td></tr><tr id="Access Log Valve_Attributes_suffix"><td><code class="attributeName">suffix</code></td><td> |
||
| 206 | <p>The suffix added to the end of each log file's name. If not |
||
| 207 | specified, the default value is "" (a zero-length string), |
||
| 208 | meaning that no suffix will be added.</p> |
||
| 209 | </td></tr></table> |
||
| 210 | |||
| 211 | <p>Values for the <code>pattern</code> attribute are made up of literal |
||
| 212 | text strings, combined with pattern identifiers prefixed by the "%" |
||
| 213 | character to cause replacement by the corresponding variable value from |
||
| 214 | the current request and response. The following pattern codes are |
||
| 215 | supported:</p> |
||
| 216 | <ul> |
||
| 217 | <li><b><code>%a</code></b> - Remote IP address. |
||
| 218 | See also <code>%{xxx}a</code> below.</li> |
||
| 219 | <li><b><code>%A</code></b> - Local IP address</li> |
||
| 220 | <li><b><code>%b</code></b> - Bytes sent, excluding HTTP headers, or '-' if zero</li> |
||
| 221 | <li><b><code>%B</code></b> - Bytes sent, excluding HTTP headers</li> |
||
| 222 | <li><b><code>%D</code></b> - Time taken to process the request in millis. Note: In |
||
| 223 | httpd %D is microseconds. Behaviour will be aligned to httpd |
||
| 224 | in Tomcat 10 onwards.</li> |
||
| 225 | <li><b><code>%F</code></b> - Time taken to commit the response, in milliseconds</li> |
||
| 226 | <li><b><code>%h</code></b> - Remote host name (or IP address if |
||
| 227 | <code>enableLookups</code> for the connector is false)</li> |
||
| 228 | <li><b><code>%H</code></b> - Request protocol</li> |
||
| 229 | <li><b><code>%I</code></b> - Current request thread name (can compare later with stacktraces)</li> |
||
| 230 | <li><b><code>%l</code></b> - Remote logical username from identd (always returns |
||
| 231 | '-')</li> |
||
| 232 | <li><b><code>%m</code></b> - Request method (GET, POST, etc.)</li> |
||
| 233 | <li><b><code>%p</code></b> - Local port on which this request was received. |
||
| 234 | See also <code>%{xxx}p</code> below.</li> |
||
| 235 | <li><b><code>%q</code></b> - Query string (prepended with a '?' if it exists)</li> |
||
| 236 | <li><b><code>%r</code></b> - First line of the request (method and request URI)</li> |
||
| 237 | <li><b><code>%s</code></b> - HTTP status code of the response</li> |
||
| 238 | <li><b><code>%S</code></b> - User session ID</li> |
||
| 239 | <li><b><code>%t</code></b> - Date and time, in Common Log Format</li> |
||
| 240 | <li><b><code>%T</code></b> - Time taken to process the request, in seconds. Note: This |
||
| 241 | value has millisecond resolution whereas in httpd it has |
||
| 242 | second resolution. Behaviour will be align to httpd |
||
| 243 | in Tomcat 10 onwards.</li> |
||
| 244 | <li><b><code>%u</code></b> - Remote user that was authenticated (if any), else '-' (escaped if required)</li> |
||
| 245 | <li><b><code>%U</code></b> - Requested URL path</li> |
||
| 246 | <li><b><code>%v</code></b> - Local server name</li> |
||
| 247 | <li><b><code>%X</code></b> - Connection status when response is completed: |
||
| 248 | <ul> |
||
| 249 | <li><code>X</code> = Connection aborted before the response completed.</li> |
||
| 250 | <li><code>+</code> = Connection may be kept alive after the response is sent.</li> |
||
| 251 | <li><code>-</code> = Connection will be closed after the response is sent.</li> |
||
| 252 | </ul> |
||
| 253 | </li> |
||
| 254 | </ul> |
||
| 255 | |||
| 256 | <p> |
||
| 257 | There is also support to write information incoming or outgoing |
||
| 258 | headers, cookies, session or request attributes and special |
||
| 259 | timestamp formats. |
||
| 260 | It is modeled after the |
||
| 261 | <a href="https://httpd.apache.org/">Apache HTTP Server</a> log configuration |
||
| 262 | syntax. Each of them can be used multiple times with different <code>xxx</code> keys: |
||
| 263 | </p> |
||
| 264 | <ul> |
||
| 265 | <li><b><code>%{xxx}a</code></b> write remote address (client) (<code>xxx==remote</code>) or |
||
| 266 | connection peer address (<code>xxx=peer</code>)</li> |
||
| 267 | <li><b><code>%{xxx}i</code></b> write value of incoming header with name <code>xxx</code> (escaped if required)</li> |
||
| 268 | <li><b><code>%{xxx}o</code></b> write value of outgoing header with name <code>xxx</code> (escaped if required)</li> |
||
| 269 | <li><b><code>%{xxx}c</code></b> write value of cookie(s) with name <code>xxx</code> (comma separated and escaped if required)</li> |
||
| 270 | <li><b><code>%{xxx}r</code></b> write value of ServletRequest attribute with name <code>xxx</code> (escaped if required, value <code>??</code> if request is null)</li> |
||
| 271 | <li><b><code>%{xxx}s</code></b> write value of HttpSession attribute with name <code>xxx</code> (escaped if required, value <code>??</code> if request is null)</li> |
||
| 272 | <li><b><code>%{xxx}p</code></b> write local (server) port (<code>xxx==local</code>) or |
||
| 273 | remote (client) port (<code>xxx=remote</code>)</li> |
||
| 274 | <li><b><code>%{xxx}t</code></b> write timestamp at the end of the request formatted using the |
||
| 275 | enhanced SimpleDateFormat pattern <code>xxx</code></li> |
||
| 276 | </ul> |
||
| 277 | |||
| 278 | <p>All formats supported by SimpleDateFormat are allowed in <code>%{xxx}t</code>. |
||
| 279 | In addition the following extensions have been added:</p> |
||
| 280 | <ul> |
||
| 281 | <li><b><code>sec</code></b> - number of seconds since the epoch</li> |
||
| 282 | <li><b><code>msec</code></b> - number of milliseconds since the epoch</li> |
||
| 283 | <li><b><code>msec_frac</code></b> - millisecond fraction</li> |
||
| 284 | </ul> |
||
| 285 | <p>These formats cannot be mixed with SimpleDateFormat formats in the same format |
||
| 286 | token.</p> |
||
| 287 | |||
| 288 | <p>Furthermore one can define whether to log the timestamp for the request start |
||
| 289 | time or the response finish time:</p> |
||
| 290 | <ul> |
||
| 291 | <li><b><code>begin</code></b> or prefix <b><code>begin:</code></b> chooses |
||
| 292 | the request start time</li> |
||
| 293 | <li><b><code>end</code></b> or prefix <b><code>end:</code></b> chooses |
||
| 294 | the response finish time</li> |
||
| 295 | </ul> |
||
| 296 | <p>By adding multiple <code>%{xxx}t</code> tokens to the pattern, one can |
||
| 297 | also log both timestamps.</p> |
||
| 298 | |||
| 299 | <p>Escaping is applied as follows:</p> |
||
| 300 | <ul> |
||
| 301 | <li><code>"</code> is escaped as <code>\"</code></li> |
||
| 302 | <li><code>\</code> is escaped as <code>\\</code></li> |
||
| 303 | <li>Standard C escaping are used for <code>\f</code>, <code>\n</code>, |
||
| 304 | <code>\r</code> and <code>\t</code></li> |
||
| 305 | <li>Any other control characters or characters with code points above 127 |
||
| 306 | are encoded using the standard Java unicode escaping |
||
| 307 | (<code>\uXXXX</code>)</li> |
||
| 308 | </ul> |
||
| 309 | |||
| 310 | <p>The shorthand pattern <code>pattern="common"</code> |
||
| 311 | corresponds to the Common Log Format defined by |
||
| 312 | <strong>'%h %l %u %t "%r" %s %b'</strong>.</p> |
||
| 313 | |||
| 314 | <p>The shorthand pattern <code>pattern="combined"</code> |
||
| 315 | appends the values of the <code>Referer</code> and <code>User-Agent</code> |
||
| 316 | headers, each in double quotes, to the <code>common</code> pattern.</p> |
||
| 317 | |||
| 318 | <p>Fields using unknown pattern identifiers will be logged as <code>???X???</code> |
||
| 319 | where <code>X</code> is the unknown identifier. Fields with unknown pattern identifier |
||
| 320 | plus <code>{xxx}</code> key will be logged as <code>???</code>.</p> |
||
| 321 | |||
| 322 | <p>When Tomcat is operating behind a reverse proxy, the client information |
||
| 323 | logged by the Access Log Valve may represent the reverse proxy, the browser |
||
| 324 | or some combination of the two depending on the configuration of Tomcat and |
||
| 325 | the reverse proxy. For Tomcat configuration options see |
||
| 326 | <a href="#Proxies_Support">Proxies Support</a> and the |
||
| 327 | <a href="../proxy-howto.html">Proxy How-To</a>. For reverse proxies that |
||
| 328 | use mod_jk, see the <a href="https://tomcat.apache.org/connectors-doc/generic_howto/proxy.html">generic |
||
| 329 | proxy</a> documentation. For other reverse proxies, consult their |
||
| 330 | documentation.</p> |
||
| 331 | </div></div> |
||
| 332 | |||
| 333 | </div></div> |
||
| 334 | |||
| 335 | |||
| 336 | <div class="subsection"><h4 id="Extended_Access_Log_Valve">Extended Access Log Valve</h4><div class="text"> |
||
| 337 | |||
| 338 | <div class="subsection"><h4 id="Extended_Access_Log_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 339 | |||
| 340 | <p>The <strong>Extended Access Log Valve</strong> extends the |
||
| 341 | <a href="#Access_Log_Valve">Access Log Valve</a> class, and so |
||
| 342 | uses the same self-contained logging logic. This means it |
||
| 343 | implements many of the same file handling attributes. The main |
||
| 344 | difference to the standard <code>AccessLogValve</code> is that |
||
| 345 | <code>ExtendedAccessLogValve</code> creates log files which |
||
| 346 | conform to the Working Draft for the |
||
| 347 | <a href="https://www.w3.org/TR/WD-logfile.html">Extended Log File Format</a> |
||
| 348 | defined by the W3C.</p> |
||
| 349 | |||
| 350 | </div></div> |
||
| 351 | |||
| 352 | <div class="subsection"><h4 id="Extended_Access_Log_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 353 | |||
| 354 | <p>The <strong>Extended Access Log Valve</strong> supports all |
||
| 355 | configuration attributes of the standard |
||
| 356 | <a href="#Access_Log_Valve">Access Log Valve.</a> Only the |
||
| 357 | values used for <code>className</code> and <code>pattern</code> differ.</p> |
||
| 358 | |||
| 359 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 360 | Attribute |
||
| 361 | </th><th style="width: 85%;"> |
||
| 362 | Description |
||
| 363 | </th></tr><tr id="Extended Access Log Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 364 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 365 | <strong>org.apache.catalina.valves.ExtendedAccessLogValve</strong> to |
||
| 366 | use the extended access log valve.</p> |
||
| 367 | </td></tr><tr id="Extended Access Log Valve_Attributes_pattern"><td><code class="attributeName">pattern</code></td><td> |
||
| 368 | <p>A formatting layout identifying the various information fields |
||
| 369 | from the request and response to be logged. |
||
| 370 | See below for more information on configuring this attribute.</p> |
||
| 371 | </td></tr></table> |
||
| 372 | |||
| 373 | <p>Values for the <code>pattern</code> attribute are made up of |
||
| 374 | format tokens. Some of the tokens need an additional prefix. Possible |
||
| 375 | prefixes are <code>c</code> for "client", <code>s</code> for "server", |
||
| 376 | <code>cs</code> for "client to server", <code>sc</code> for |
||
| 377 | "server to client" or <code>x</code> for "application specific". |
||
| 378 | Furthermore some tokens are completed by an additional selector. |
||
| 379 | See the <a href="https://www.w3.org/TR/WD-logfile.html">W3C specification</a> |
||
| 380 | for more information about the format.</p> |
||
| 381 | |||
| 382 | <p>The following format tokens are supported:</p> |
||
| 383 | <ul> |
||
| 384 | <li><b>bytes</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li> |
||
| 385 | <li><b>c-dns</b> - Remote host name (or IP address if |
||
| 386 | <code>enableLookups</code> for the connector is false)</li> |
||
| 387 | <li><b>c-ip</b> - Remote IP address</li> |
||
| 388 | <li><b>cs-method</b> - Request method (GET, POST, etc.)</li> |
||
| 389 | <li><b>cs-uri</b> - Request URI</li> |
||
| 390 | <li><b>cs-uri-query</b> - Query string (prepended with a '?' if it exists)</li> |
||
| 391 | <li><b>cs-uri-stem</b> - Requested URL path</li> |
||
| 392 | <li><b>date</b> - The date in yyyy-mm-dd format for GMT</li> |
||
| 393 | <li><b>s-dns</b> - Local host name</li> |
||
| 394 | <li><b>s-ip</b> - Local IP address</li> |
||
| 395 | <li><b>sc-status</b> - HTTP status code of the response</li> |
||
| 396 | <li><b>time</b> - Time the request was served in HH:mm:ss format for GMT</li> |
||
| 397 | <li><b>time-taken</b> - Time (in seconds as floating point) taken to serve the request</li> |
||
| 398 | <li><b>x-threadname</b> - Current request thread name (can compare later with stacktraces)</li> |
||
| 399 | </ul> |
||
| 400 | |||
| 401 | <p>For any of the <code>x-H(XXX)</code> the following method will be called from the |
||
| 402 | HttpServletRequest object:</p> |
||
| 403 | <ul> |
||
| 404 | <li><b><code>x-H(authType)</code></b>: getAuthType </li> |
||
| 405 | <li><b><code>x-H(characterEncoding)</code></b>: getCharacterEncoding </li> |
||
| 406 | <li><b><code>x-H(contentLength)</code></b>: getContentLength </li> |
||
| 407 | <li><b><code>x-H(locale)</code></b>: getLocale</li> |
||
| 408 | <li><b><code>x-H(protocol)</code></b>: getProtocol </li> |
||
| 409 | <li><b><code>x-H(remoteUser)</code></b>: getRemoteUser</li> |
||
| 410 | <li><b><code>x-H(requestedSessionId)</code></b>: getRequestedSessionId</li> |
||
| 411 | <li><b><code>x-H(requestedSessionIdFromCookie)</code></b>: |
||
| 412 | isRequestedSessionIdFromCookie </li> |
||
| 413 | <li><b><code>x-H(requestedSessionIdValid)</code></b>: |
||
| 414 | isRequestedSessionIdValid</li> |
||
| 415 | <li><b><code>x-H(scheme)</code></b>: getScheme</li> |
||
| 416 | <li><b><code>x-H(secure)</code></b>: isSecure</li> |
||
| 417 | </ul> |
||
| 418 | |||
| 419 | <p> |
||
| 420 | There is also support to write information about headers |
||
| 421 | cookies, context, request or session attributes and request |
||
| 422 | parameters. |
||
| 423 | </p> |
||
| 424 | <ul> |
||
| 425 | <li><b><code>cs(XXX)</code></b> for incoming request headers with name XXX</li> |
||
| 426 | <li><b><code>sc(XXX)</code></b> for outgoing response headers with name XXX</li> |
||
| 427 | <li><b><code>x-A(XXX)</code></b> for the servlet context attribute with name XXX</li> |
||
| 428 | <li><b><code>x-C(XXX)</code></b> for the cookie(s) with name XXX (comma separated if required)</li> |
||
| 429 | <li><b><code>x-O(XXX)</code></b> for a concatenation of all outgoing response headers with name XXX</li> |
||
| 430 | <li><b><code>x-P(XXX)</code></b> for the URL encoded (using UTF-8) request parameter with name XXX</li> |
||
| 431 | <li><b><code>x-R(XXX)</code></b> for the request attribute with name XXX</li> |
||
| 432 | <li><b><code>x-S(XXX)</code></b> for the session attribute with name XXX</li> |
||
| 433 | </ul> |
||
| 434 | |||
| 435 | </div></div> |
||
| 436 | |||
| 437 | </div></div> |
||
| 438 | |||
| 439 | <div class="subsection"><h4 id="JSON_Access_Log_Valve">JSON Access Log Valve</h4><div class="text"> |
||
| 440 | |||
| 441 | <div class="subsection"><h4 id="JSON_Access_Log_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 442 | |||
| 443 | <p>The <strong>JSON Access Log Valve</strong> extends the |
||
| 444 | <a href="#Access_Log_Valve">Access Log Valve</a>, and so |
||
| 445 | uses the same self-contained logging logic. This means it |
||
| 446 | implements the same file handling attributes. The main |
||
| 447 | difference to the standard <code>AccessLogValve</code> is that |
||
| 448 | <code>JsonAccessLogValve</code> creates log files which |
||
| 449 | follow the JSON syntax as defined by |
||
| 450 | <a href="https://www.rfc-editor.org/rfc/rfc8259.html">RFC 8259</a>.</p> |
||
| 451 | |||
| 452 | </div></div> |
||
| 453 | |||
| 454 | <div class="subsection"><h4 id="JSON_Access_Log_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 455 | |||
| 456 | <p>The <strong>JSON Access Log Valve</strong> supports all |
||
| 457 | configuration attributes of the standard |
||
| 458 | <a href="#Access_Log_Valve">Access Log Valve.</a> Only the |
||
| 459 | values used for <code>className</code> differ.</p> |
||
| 460 | |||
| 461 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 462 | Attribute |
||
| 463 | </th><th style="width: 85%;"> |
||
| 464 | Description |
||
| 465 | </th></tr><tr id="JSON Access Log Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 466 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 467 | <strong>org.apache.catalina.valves.JsonAccessLogValve</strong> to |
||
| 468 | use the extended access log valve.</p> |
||
| 469 | </td></tr></table> |
||
| 470 | |||
| 471 | <p>While the patterns supported are the same as for the regular |
||
| 472 | <a href="#Access_Log_Valve">Access Log Valve</a>, |
||
| 473 | there are a few differences: |
||
| 474 | <ul> |
||
| 475 | <li>requests are logged as JSON objects.</li> |
||
| 476 | <li>each supported "%X" single character pattern |
||
| 477 | identifier results in a key value pair in this object. |
||
| 478 | See below for the list of keys used for the respective pattern |
||
| 479 | identifiers.</li> |
||
| 480 | <li>each pattern identifiers using a subkey of the form <code>%{xxx}X</code> |
||
| 481 | where "X" is one of "a", "p" or "t" |
||
| 482 | results in a key value pair of the form "key-xxx". |
||
| 483 | See below for the list of keys used for the respective pattern |
||
| 484 | identifiers.</li> |
||
| 485 | <li>each pattern identifiers using a subkey of the form <code>%{xxx}X</code> |
||
| 486 | where "X" is one of "c", "i", "o", "r" or "s" |
||
| 487 | results in a sub object. See below for the key pointing at this |
||
| 488 | sub object. The keys in the sub object are the "xxx" subkeys in the pattern.</li> |
||
| 489 | <li>each unsupported "%X" character pattern |
||
| 490 | identifier results in a key value pair using the key "other-X".</li> |
||
| 491 | <li>the values logged are the same as the ones logged by |
||
| 492 | the standard <a href="#Access_Log_Valve">Access Log Valve</a> |
||
| 493 | for the same pattern identifiers.</li> |
||
| 494 | <li>any "xxx" subkeys get Json escaped.</li> |
||
| 495 | <li>any verbatim text between pattern identifiers gets silently ignored.</li> |
||
| 496 | </ul> |
||
| 497 | The JSON object keys used for the pattern identifiers which |
||
| 498 | do not generate a sub object are the following: |
||
| 499 | <ul> |
||
| 500 | <li><b><code>%a</code></b>: remoteAddr</li> |
||
| 501 | <li><b><code>%A</code></b>: localAddr</li> |
||
| 502 | <li><b><code>%b</code></b>: size</li> |
||
| 503 | <li><b><code>%B</code></b>: byteSentNC</li> |
||
| 504 | <li><b><code>%D</code></b>: elapsedTime</li> |
||
| 505 | <li><b><code>%F</code></b>: firstByteTime</li> |
||
| 506 | <li><b><code>%h</code></b>: host</li> |
||
| 507 | <li><b><code>%H</code></b>: protocol</li> |
||
| 508 | <li><b><code>%I</code></b>: threadName</li> |
||
| 509 | <li><b><code>%l</code></b>: logicalUserName</li> |
||
| 510 | <li><b><code>%m</code></b>: method</li> |
||
| 511 | <li><b><code>%p</code></b>: port</li> |
||
| 512 | <li><b><code>%q</code></b>: query</li> |
||
| 513 | <li><b><code>%r</code></b>: request</li> |
||
| 514 | <li><b><code>%s</code></b>: statusCode</li> |
||
| 515 | <li><b><code>%S</code></b>: sessionId</li> |
||
| 516 | <li><b><code>%t</code></b>: time</li> |
||
| 517 | <li><b><code>%T</code></b>: elapsedTimeS</li> |
||
| 518 | <li><b><code>%u</code></b>: user</li> |
||
| 519 | <li><b><code>%U</code></b>: path</li> |
||
| 520 | <li><b><code>%v</code></b>: localServerName</li> |
||
| 521 | <li><b><code>%X</code></b>: connectionStatus</li> |
||
| 522 | </ul> |
||
| 523 | The JSON object keys used for the pattern identifiers which |
||
| 524 | generate a sub object are the following: |
||
| 525 | <ul> |
||
| 526 | <li><b><code>%c</code></b>: cookies</li> |
||
| 527 | <li><b><code>%i</code></b>: requestHeaders</li> |
||
| 528 | <li><b><code>%o</code></b>: responseHeaders</li> |
||
| 529 | <li><b><code>%r</code></b>: requestAttributes</li> |
||
| 530 | <li><b><code>%s</code></b>: sessionAttributes</li> |
||
| 531 | </ul> |
||
| 532 | </p> |
||
| 533 | |||
| 534 | </div></div> |
||
| 535 | |||
| 536 | </div></div> |
||
| 537 | |||
| 538 | </div><h3 id="Access_Control">Access Control</h3><div class="text"> |
||
| 539 | |||
| 540 | |||
| 541 | <div class="subsection"><h4 id="Remote_Address_Valve">Remote Address Valve</h4><div class="text"> |
||
| 542 | |||
| 543 | <div class="subsection"><h4 id="Remote_Address_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 544 | |||
| 545 | <p>The <strong>Remote Address Valve</strong> allows you to compare the |
||
| 546 | IP address of the client that submitted this request against one or more |
||
| 547 | <em>regular expressions</em>, and either allow the request to continue |
||
| 548 | or refuse to process the request from this client. A Remote Address |
||
| 549 | Valve can be associated with any Catalina container |
||
| 550 | (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or |
||
| 551 | <a href="context.html">Context</a>), and must accept any request |
||
| 552 | presented to this container for processing before it will be passed on.</p> |
||
| 553 | |||
| 554 | <p>The syntax for <em>regular expressions</em> is different than that for |
||
| 555 | 'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code> |
||
| 556 | package. Please consult the Java documentation for details of the |
||
| 557 | expressions supported.</p> |
||
| 558 | |||
| 559 | <p>After setting the attribute <code>addConnectorPort</code> to |
||
| 560 | <code>true</code>, one can append the server connector port separated with a |
||
| 561 | semicolon (";") to allow different expressions for each connector.</p> |
||
| 562 | |||
| 563 | <p>By setting the attribute <code>usePeerAddress</code> to |
||
| 564 | <code>true</code>, the valve will use the connection peer address in its |
||
| 565 | checks. This will differ from the client IP, if a reverse proxy is used |
||
| 566 | in front of Tomcat in combination with either the AJP protocol, or the |
||
| 567 | HTTP protocol plus the <code>RemoteIp(Valve|Filter)</code>.</p> |
||
| 568 | |||
| 569 | <p>A refused request will be answered a response with status code |
||
| 570 | <code>403</code>. This status code can be overwritten using the attribute |
||
| 571 | <code>denyStatus</code>.</p> |
||
| 572 | |||
| 573 | <p>By setting the attribute <code>invalidAuthenticationWhenDeny</code> to |
||
| 574 | <code>true</code>, the behavior when a request is refused can be changed |
||
| 575 | to not deny but instead set an invalid <code>authentication</code> |
||
| 576 | header. This is useful in combination with the context attribute |
||
| 577 | <code>preemptiveAuthentication="true"</code>.</p> |
||
| 578 | |||
| 579 | <p><strong>Note:</strong> There is a caveat when using this valve with |
||
| 580 | IPv6 addresses. Format of the IP address that this valve is processing |
||
| 581 | depends on the API that was used to obtain it. If the address was obtained |
||
| 582 | from Java socket using Inet6Address class, its format will be |
||
| 583 | <code>x:x:x:x:x:x:x:x</code>. That is, the IP address for localhost |
||
| 584 | will be <code>0:0:0:0:0:0:0:1</code> instead of the more widely used |
||
| 585 | <code>::1</code>. Consult your access logs for the actual value.</p> |
||
| 586 | |||
| 587 | <p>See also: <a href="#Remote_Host_Valve">Remote Host Valve</a>, |
||
| 588 | <a href="#Remote_CIDR_Valve">Remote CIDR Valve</a>, |
||
| 589 | <a href="#Remote_IP_Valve">Remote IP Valve</a>, |
||
| 590 | <a href="http.html">HTTP Connector</a> configuration.</p> |
||
| 591 | |||
| 592 | <p><strong>Note:</strong> This Valve is deprecated and will be removed in |
||
| 593 | Tomcat 12. Use <a href="#Remote_CIDR_Valve">Remote CIDR Valve</a> |
||
| 594 | instead.</p> |
||
| 595 | |||
| 596 | </div></div> |
||
| 597 | |||
| 598 | <div class="subsection"><h4 id="Remote_Address_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 599 | |||
| 600 | <p>The <strong>Remote Address Valve</strong> supports the following |
||
| 601 | configuration attributes:</p> |
||
| 602 | |||
| 603 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 604 | Attribute |
||
| 605 | </th><th style="width: 85%;"> |
||
| 606 | Description |
||
| 607 | </th></tr><tr id="Remote Address Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 608 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 609 | <strong>org.apache.catalina.valves.RemoteAddrValve</strong>.</p> |
||
| 610 | </td></tr><tr id="Remote Address Valve_Attributes_allow"><td><code class="attributeName">allow</code></td><td> |
||
| 611 | <p>A regular expression (using <code>java.util.regex</code>) that the |
||
| 612 | remote client's IP address is compared to. If this attribute |
||
| 613 | is specified, the remote address MUST match for this request to be |
||
| 614 | accepted. If this attribute is not specified, all requests will be |
||
| 615 | accepted UNLESS the remote address matches a <code>deny</code> |
||
| 616 | pattern.</p> |
||
| 617 | </td></tr><tr id="Remote Address Valve_Attributes_deny"><td><code class="attributeName">deny</code></td><td> |
||
| 618 | <p>A regular expression (using <code>java.util.regex</code>) that the |
||
| 619 | remote client's IP address is compared to. If this attribute |
||
| 620 | is specified, the remote address MUST NOT match for this request to be |
||
| 621 | accepted. If this attribute is not specified, request acceptance is |
||
| 622 | governed solely by the <code>allow</code> attribute.</p> |
||
| 623 | </td></tr><tr id="Remote Address Valve_Attributes_denyStatus"><td><code class="attributeName">denyStatus</code></td><td> |
||
| 624 | <p>HTTP response status code that is used when rejecting denied |
||
| 625 | request. The default value is <code>403</code>. For example, |
||
| 626 | it can be set to the value <code>404</code>.</p> |
||
| 627 | </td></tr><tr id="Remote Address Valve_Attributes_addConnectorPort"><td><code class="attributeName">addConnectorPort</code></td><td> |
||
| 628 | <p>Append the server connector port to the client IP address separated |
||
| 629 | with a semicolon (";"). If this is set to <code>true</code>, the |
||
| 630 | expressions configured with <code>allow</code> and |
||
| 631 | <code>deny</code> is compared against <code>ADDRESS;PORT</code> |
||
| 632 | where <code>ADDRESS</code> is the client IP address and |
||
| 633 | <code>PORT</code> is the Tomcat connector port which received the |
||
| 634 | request. The default value is <code>false</code>.</p> |
||
| 635 | </td></tr><tr id="Remote Address Valve_Attributes_invalidAuthenticationWhenDeny"><td><code class="attributeName">invalidAuthenticationWhenDeny</code></td><td> |
||
| 636 | <p>When a request should be denied, do not deny but instead |
||
| 637 | set an invalid <code>authentication</code> header. This only works |
||
| 638 | if the context has the attribute <code>preemptiveAuthentication="true"</code> |
||
| 639 | set. An already existing <code>authentication</code> header will not be |
||
| 640 | overwritten. In effect this will trigger authentication instead of deny |
||
| 641 | even if the application does not have a security constraint configured.</p> |
||
| 642 | <p>This can be combined with <code>addConnectorPort</code> to trigger authentication |
||
| 643 | depending on the client and the connector that is used to access an application.</p> |
||
| 644 | </td></tr><tr id="Remote Address Valve_Attributes_usePeerAddress"><td><code class="attributeName">usePeerAddress</code></td><td> |
||
| 645 | <p>Use the connection peer address instead of the client IP address. |
||
| 646 | They will differ, if a reverse proxy is used in front of Tomcat in |
||
| 647 | combination with either the AJP protocol, or the HTTP protocol plus |
||
| 648 | the <code>RemoteIp(Valve|Filter)</code>.</p> |
||
| 649 | </td></tr></table> |
||
| 650 | |||
| 651 | </div></div> |
||
| 652 | |||
| 653 | <div class="subsection"><h4 id="Remote_Address_Valve/Example_localhost">Example 1</h4><div class="text"> |
||
| 654 | <p>To allow access only for the clients connecting from localhost:</p> |
||
| 655 | <div class="codeBox"><pre><code><Valve className="org.apache.catalina.valves.RemoteAddrValve" |
||
| 656 | allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1"/></code></pre></div> |
||
| 657 | </div></div> |
||
| 658 | |||
| 659 | <div class="subsection"><h4 id="Remote_Address_Valve/Example_localhost_port">Example 2</h4><div class="text"> |
||
| 660 | <p>To allow unrestricted access for the clients connecting from localhost |
||
| 661 | but for all other clients only to port 8443:</p> |
||
| 662 | <div class="codeBox"><pre><code><Valve className="org.apache.catalina.valves.RemoteAddrValve" |
||
| 663 | addConnectorPort="true" |
||
| 664 | allow="127\.\d+\.\d+\.\d+;\d*|::1;\d*|0:0:0:0:0:0:0:1;\d*|.*;8443"/></code></pre></div> |
||
| 665 | </div></div> |
||
| 666 | |||
| 667 | <div class="subsection"><h4 id="Remote_Address_Valve/Example_port_auth">Example 3</h4><div class="text"> |
||
| 668 | <p>To allow unrestricted access to port 8009, but trigger basic |
||
| 669 | authentication if the application is accessed on another port:</p> |
||
| 670 | <div class="codeBox"><pre><code><Context> |
||
| 671 | ... |
||
| 672 | <Valve className="org.apache.catalina.valves.RemoteAddrValve" |
||
| 673 | addConnectorPort="true" |
||
| 674 | invalidAuthenticationWhenDeny="true" |
||
| 675 | allow=".*;8009"/> |
||
| 676 | <Valve className="org.apache.catalina.authenticator.BasicAuthenticator" /> |
||
| 677 | ... |
||
| 678 | </Context></code></pre></div> |
||
| 679 | </div></div> |
||
| 680 | |||
| 681 | </div></div> |
||
| 682 | |||
| 683 | |||
| 684 | <div class="subsection"><h4 id="Remote_Host_Valve">Remote Host Valve</h4><div class="text"> |
||
| 685 | |||
| 686 | <div class="subsection"><h4 id="Remote_Host_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 687 | |||
| 688 | <p>The <strong>Remote Host Valve</strong> allows you to compare the |
||
| 689 | hostname of the client that submitted this request against one or more |
||
| 690 | <em>regular expressions</em>, and either allow the request to continue |
||
| 691 | or refuse to process the request from this client. A Remote Host |
||
| 692 | Valve can be associated with any Catalina container |
||
| 693 | (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or |
||
| 694 | <a href="context.html">Context</a>), and must accept any request |
||
| 695 | presented to this container for processing before it will be passed on.</p> |
||
| 696 | |||
| 697 | <p>The syntax for <em>regular expressions</em> is different than that for |
||
| 698 | 'standard' wildcard matching. Tomcat uses the <code>java.util.regex</code> |
||
| 699 | package. Please consult the Java documentation for details of the |
||
| 700 | expressions supported.</p> |
||
| 701 | |||
| 702 | <p>After setting the attribute <code>addConnectorPort</code> to |
||
| 703 | <code>true</code>, one can append the server connector port separated with a |
||
| 704 | semicolon (";") to allow different expressions for each connector.</p> |
||
| 705 | |||
| 706 | <p>A refused request will be answered a response with status code |
||
| 707 | <code>403</code>. This status code can be overwritten using the attribute |
||
| 708 | <code>denyStatus</code>.</p> |
||
| 709 | |||
| 710 | <p>By setting the attribute <code>invalidAuthenticationWhenDeny</code> to |
||
| 711 | <code>true</code>, the behavior when a request is refused can be changed |
||
| 712 | to not deny but instead set an invalid <code>authentication</code> |
||
| 713 | header. This is useful in combination with the context attribute |
||
| 714 | <code>preemptiveAuthentication="true"</code>.</p> |
||
| 715 | |||
| 716 | <p><strong>Note:</strong> This valve processes the value returned by |
||
| 717 | method <code>ServletRequest.getRemoteHost()</code>. To allow the method |
||
| 718 | to return proper host names, you have to enable "DNS lookups" feature on |
||
| 719 | a <strong>Connector</strong>.</p> |
||
| 720 | |||
| 721 | <p>See also: <a href="#Remote_Address_Valve">Remote Address Valve</a>, |
||
| 722 | <a href="#Remote_CIDR_Valve">Remote CIDR Valve</a>, |
||
| 723 | <a href="#Remote_IP_Valve">Remote IP Valve</a>, |
||
| 724 | <a href="http.html">HTTP Connector</a> configuration.</p> |
||
| 725 | </div></div> |
||
| 726 | |||
| 727 | <div class="subsection"><h4 id="Remote_Host_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 728 | |||
| 729 | <p>The <strong>Remote Host Valve</strong> supports the following |
||
| 730 | configuration attributes:</p> |
||
| 731 | |||
| 732 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 733 | Attribute |
||
| 734 | </th><th style="width: 85%;"> |
||
| 735 | Description |
||
| 736 | </th></tr><tr id="Remote Host Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 737 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 738 | <strong>org.apache.catalina.valves.RemoteHostValve</strong>.</p> |
||
| 739 | </td></tr><tr id="Remote Host Valve_Attributes_allow"><td><code class="attributeName">allow</code></td><td> |
||
| 740 | <p>A regular expression (using <code>java.util.regex</code>) that the |
||
| 741 | remote client's hostname is compared to. If this attribute |
||
| 742 | is specified, the remote hostname MUST match for this request to be |
||
| 743 | accepted. If this attribute is not specified, all requests will be |
||
| 744 | accepted UNLESS the remote hostname matches a <code>deny</code> |
||
| 745 | pattern.</p> |
||
| 746 | </td></tr><tr id="Remote Host Valve_Attributes_deny"><td><code class="attributeName">deny</code></td><td> |
||
| 747 | <p>A regular expression (using <code>java.util.regex</code>) that the |
||
| 748 | remote client's hostname is compared to. If this attribute |
||
| 749 | is specified, the remote hostname MUST NOT match for this request to be |
||
| 750 | accepted. If this attribute is not specified, request acceptance is |
||
| 751 | governed solely by the <code>allow</code> attribute.</p> |
||
| 752 | </td></tr><tr id="Remote Host Valve_Attributes_denyStatus"><td><code class="attributeName">denyStatus</code></td><td> |
||
| 753 | <p>HTTP response status code that is used when rejecting denied |
||
| 754 | request. The default value is <code>403</code>. For example, |
||
| 755 | it can be set to the value <code>404</code>.</p> |
||
| 756 | </td></tr><tr id="Remote Host Valve_Attributes_addConnectorPort"><td><code class="attributeName">addConnectorPort</code></td><td> |
||
| 757 | <p>Append the server connector port to the client hostname separated |
||
| 758 | with a semicolon (";"). If this is set to <code>true</code>, the |
||
| 759 | expressions configured with <code>allow</code> and |
||
| 760 | <code>deny</code> is compared against <code>HOSTNAME;PORT</code> |
||
| 761 | where <code>HOSTNAME</code> is the client hostname and |
||
| 762 | <code>PORT</code> is the Tomcat connector port which received the |
||
| 763 | request. The default value is <code>false</code>.</p> |
||
| 764 | </td></tr><tr id="Remote Host Valve_Attributes_invalidAuthenticationWhenDeny"><td><code class="attributeName">invalidAuthenticationWhenDeny</code></td><td> |
||
| 765 | <p>When a request should be denied, do not deny but instead |
||
| 766 | set an invalid <code>authentication</code> header. This only works |
||
| 767 | if the context has the attribute <code>preemptiveAuthentication="true"</code> |
||
| 768 | set. An already existing <code>authentication</code> header will not be |
||
| 769 | overwritten. In effect this will trigger authentication instead of deny |
||
| 770 | even if the application does not have a security constraint configured.</p> |
||
| 771 | <p>This can be combined with <code>addConnectorPort</code> to trigger authentication |
||
| 772 | depending on the client and the connector that is used to access an application.</p> |
||
| 773 | </td></tr></table> |
||
| 774 | |||
| 775 | </div></div> |
||
| 776 | |||
| 777 | </div></div> |
||
| 778 | |||
| 779 | <div class="subsection"><h4 id="Remote_CIDR_Valve">Remote CIDR Valve</h4><div class="text"> |
||
| 780 | |||
| 781 | <div class="subsection"><h4 id="Remote_CIDR_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 782 | |||
| 783 | <p>The <strong>Remote CIDR Valve</strong> allows you to compare the |
||
| 784 | IP address of the client that submitted this request against one or more |
||
| 785 | netmasks following the CIDR notation, and either allow the request to |
||
| 786 | continue or refuse to process the request from this client. IPv4 and |
||
| 787 | IPv6 are both fully supported. A Remote CIDR Valve can be associated |
||
| 788 | with any Catalina container (<a href="engine.html">Engine</a>, |
||
| 789 | <a href="host.html">Host</a>, or <a href="context.html">Context</a>), and |
||
| 790 | must accept any request presented to this container for processing before |
||
| 791 | it will be passed on. |
||
| 792 | </p> |
||
| 793 | |||
| 794 | <p>This valve mimics Apache's <code>Order</code>, |
||
| 795 | <code>Allow from</code> and <code>Deny from</code> directives, |
||
| 796 | with the following limitations: |
||
| 797 | </p> |
||
| 798 | |||
| 799 | <ul> |
||
| 800 | <li><code>Order</code> will always be <code>allow, deny</code>;</li> |
||
| 801 | <li>dotted quad notations for netmasks are not supported (that is, you |
||
| 802 | cannot write <code>192.168.1.0/255.255.255.0</code>, you must write |
||
| 803 | <code>192.168.1.0/24</code>; |
||
| 804 | </li> |
||
| 805 | <li>shortcuts, like <code>10.10.</code>, which is equivalent to |
||
| 806 | <code>10.10.0.0/16</code>, are not supported; |
||
| 807 | </li> |
||
| 808 | <li>as the valve name says, this is a CIDR only valve, |
||
| 809 | therefore subdomain notations like <code>.mydomain.com</code> are not |
||
| 810 | supported either. |
||
| 811 | </li> |
||
| 812 | </ul> |
||
| 813 | |||
| 814 | <p>After setting the attribute <code>addConnectorPort</code> to |
||
| 815 | <code>true</code>, one can append the server connector port separated with a |
||
| 816 | semicolon (";") to allow different expressions for each connector.</p> |
||
| 817 | |||
| 818 | <p>By setting the attribute <code>usePeerAddress</code> to |
||
| 819 | <code>true</code>, the valve will use the connection peer address in its |
||
| 820 | checks. This will differ from the client IP, if a reverse proxy is used |
||
| 821 | in front of Tomcat in combination with either the AJP protocol, or the |
||
| 822 | HTTP protocol plus the <code>RemoteIp(Valve|Filter)</code>.</p> |
||
| 823 | |||
| 824 | <p>A refused request will be answered a response with status code |
||
| 825 | <code>403</code>. This status code can be overwritten using the attribute |
||
| 826 | <code>denyStatus</code>.</p> |
||
| 827 | |||
| 828 | <p>By setting the attribute <code>invalidAuthenticationWhenDeny</code> to |
||
| 829 | <code>true</code>, the behavior when a request is refused can be changed |
||
| 830 | to not deny but instead set an invalid <code>authentication</code> |
||
| 831 | header. This is useful in combination with the context attribute |
||
| 832 | <code>preemptiveAuthentication="true"</code>.</p> |
||
| 833 | |||
| 834 | <p>Some more features of this valve are: |
||
| 835 | </p> |
||
| 836 | |||
| 837 | <ul> |
||
| 838 | <li>if you omit the CIDR prefix, this valve becomes a single IP |
||
| 839 | valve;</li> |
||
| 840 | <li>unlike the <a href="#Remote_Host_Valve">Remote Host Valve</a>, |
||
| 841 | it can handle IPv6 addresses in condensed form (<code>::1</code>, |
||
| 842 | <code>fe80::/71</code>, etc).</li> |
||
| 843 | </ul> |
||
| 844 | |||
| 845 | <p>See also: <a href="#Remote_Address_Valve">Remote Address Valve</a>, |
||
| 846 | <a href="#Remote_Host_Valve">Remote Host Valve</a>, |
||
| 847 | <a href="#Remote_IP_Valve">Remote IP Valve</a>, |
||
| 848 | <a href="http.html">HTTP Connector</a> configuration.</p> |
||
| 849 | </div></div> |
||
| 850 | |||
| 851 | <div class="subsection"><h4 id="Remote_CIDR_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 852 | |||
| 853 | <p>The <strong>Remote CIDR Valve</strong> supports the following |
||
| 854 | configuration attributes:</p> |
||
| 855 | |||
| 856 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 857 | Attribute |
||
| 858 | </th><th style="width: 85%;"> |
||
| 859 | Description |
||
| 860 | </th></tr><tr id="Remote CIDR Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 861 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 862 | <strong>org.apache.catalina.valves.RemoteCIDRValve</strong>.</p> |
||
| 863 | </td></tr><tr id="Remote CIDR Valve_Attributes_allow"><td><code class="attributeName">allow</code></td><td> |
||
| 864 | <p>A comma-separated list of IPv4 or IPv6 netmasks or addresses |
||
| 865 | that the remote client's IP address is matched against. |
||
| 866 | If this attribute is specified, the remote address MUST match |
||
| 867 | for this request to be accepted. If this attribute is not specified, |
||
| 868 | all requests will be accepted UNLESS the remote IP is matched by a |
||
| 869 | netmask in the <code>deny</code> attribute. |
||
| 870 | </p> |
||
| 871 | </td></tr><tr id="Remote CIDR Valve_Attributes_deny"><td><code class="attributeName">deny</code></td><td> |
||
| 872 | <p>A comma-separated list of IPv4 or IPv6 netmasks or addresses |
||
| 873 | that the remote client's IP address is matched against. |
||
| 874 | If this attribute is specified, the remote address MUST NOT match |
||
| 875 | for this request to be accepted. If this attribute is not specified, |
||
| 876 | request acceptance is governed solely by the <code>accept</code> |
||
| 877 | attribute. |
||
| 878 | </p> |
||
| 879 | </td></tr><tr id="Remote CIDR Valve_Attributes_denyStatus"><td><code class="attributeName">denyStatus</code></td><td> |
||
| 880 | <p>HTTP response status code that is used when rejecting denied |
||
| 881 | request. The default value is <code>403</code>. For example, |
||
| 882 | it can be set to the value <code>404</code>.</p> |
||
| 883 | </td></tr><tr id="Remote CIDR Valve_Attributes_addConnectorPort"><td><code class="attributeName">addConnectorPort</code></td><td> |
||
| 884 | <p>Append the server connector port to the client IP address separated |
||
| 885 | with a semicolon (";"). If this is set to <code>true</code>, the |
||
| 886 | expressions configured with <code>allow</code> and |
||
| 887 | <code>deny</code> is compared against <code>ADDRESS;PORT</code> |
||
| 888 | where <code>ADDRESS</code> is the client IP address and |
||
| 889 | <code>PORT</code> is the Tomcat connector port which received the |
||
| 890 | request. The default value is <code>false</code>.</p> |
||
| 891 | </td></tr><tr id="Remote CIDR Valve_Attributes_invalidAuthenticationWhenDeny"><td><code class="attributeName">invalidAuthenticationWhenDeny</code></td><td> |
||
| 892 | <p>When a request should be denied, do not deny but instead |
||
| 893 | set an invalid <code>authentication</code> header. This only works |
||
| 894 | if the context has the attribute <code>preemptiveAuthentication="true"</code> |
||
| 895 | set. An already existing <code>authentication</code> header will not be |
||
| 896 | overwritten. In effect this will trigger authentication instead of deny |
||
| 897 | even if the application does not have a security constraint configured.</p> |
||
| 898 | <p>This can be combined with <code>addConnectorPort</code> to trigger authentication |
||
| 899 | depending on the client and the connector that is used to access an application.</p> |
||
| 900 | </td></tr><tr id="Remote CIDR Valve_Attributes_usePeerAddress"><td><code class="attributeName">usePeerAddress</code></td><td> |
||
| 901 | <p>Use the connection peer address instead of the client IP address. |
||
| 902 | They will differ, if a reverse proxy is used in front of Tomcat in |
||
| 903 | combination with either the AJP protocol, or the HTTP protocol plus |
||
| 904 | the <code>RemoteIp(Valve|Filter)</code>.</p> |
||
| 905 | </td></tr></table> |
||
| 906 | |||
| 907 | </div></div> |
||
| 908 | |||
| 909 | <div class="subsection"><h4 id="Remote_CIDR_Valve/Example_localhost">Example 1</h4><div class="text"> |
||
| 910 | <p>To allow access only for the clients connecting from localhost:</p> |
||
| 911 | <div class="codeBox"><pre><code><Valve className="org.apache.catalina.valves.RemoteCIDRValve" |
||
| 912 | allow="127.0.0.1, ::1"/></code></pre></div> |
||
| 913 | </div></div> |
||
| 914 | |||
| 915 | <div class="subsection"><h4 id="Remote_CIDR_Valve/Example_localhost_port">Example 2</h4><div class="text"> |
||
| 916 | <p>To allow unrestricted access for the clients connecting from the local network |
||
| 917 | but for all clients in network 10. only to port 8443:</p> |
||
| 918 | <div class="codeBox"><pre><code><Valve className="org.apache.catalina.valves.RemoteCIDRValve" |
||
| 919 | addConnectorPort="true" |
||
| 920 | allow="127.0.0.1;\d*|::1;\d*|10.0.0.0/8;8443"/></code></pre></div> |
||
| 921 | </div></div> |
||
| 922 | |||
| 923 | <div class="subsection"><h4 id="Remote_CIDR_Valve/Example_port_auth">Example 3</h4><div class="text"> |
||
| 924 | <p>To allow access to port 8009 from network 10., but trigger basic |
||
| 925 | authentication if the application is accessed on another port:</p> |
||
| 926 | <div class="codeBox"><pre><code><Context> |
||
| 927 | ... |
||
| 928 | <Valve className="org.apache.catalina.valves.RemoteCIDRValve" |
||
| 929 | addConnectorPort="true" |
||
| 930 | invalidAuthenticationWhenDeny="true" |
||
| 931 | allow="10.0.0.0/8;8009"/> |
||
| 932 | <Valve className="org.apache.catalina.authenticator.BasicAuthenticator" /> |
||
| 933 | ... |
||
| 934 | </Context></code></pre></div> |
||
| 935 | </div></div> |
||
| 936 | |||
| 937 | </div></div> |
||
| 938 | |||
| 939 | </div><h3 id="Proxies_Support">Proxies Support</h3><div class="text"> |
||
| 940 | <div class="subsection"><h4 id="Load_Balancer_Draining_Valve">Load Balancer Draining Valve</h4><div class="text"> |
||
| 941 | <div class="subsection"><h4 id="Load_Balancer_Draining_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 942 | <p> |
||
| 943 | When using mod_jk or mod_proxy_ajp, the client's session id is used to |
||
| 944 | determine which back-end server will be used to serve the request. If the |
||
| 945 | target node is being "drained" (in mod_jk, this is the <i>DISABLED</i> |
||
| 946 | state; in mod_proxy_ajp, this is the <i>Drain (N)</i> state), requests |
||
| 947 | for expired sessions can actually cause the draining node to fail to |
||
| 948 | drain. |
||
| 949 | </p> |
||
| 950 | <p> |
||
| 951 | Unfortunately, AJP-based load-balancers cannot prove whether the |
||
| 952 | client-provided session id is valid or not and therefore will send any |
||
| 953 | requests for a session that appears to be targeted to that node to the |
||
| 954 | disabled (or "draining") node, causing the "draining" process to take |
||
| 955 | longer than necessary. |
||
| 956 | </p> |
||
| 957 | <p> |
||
| 958 | This Valve detects requests for invalid sessions, strips the session |
||
| 959 | information from the request, and redirects back to the same URL, where |
||
| 960 | the load-balancer should choose a different (active) node to handle the |
||
| 961 | request. This will accelerate the "draining" process for the disabled |
||
| 962 | node(s). |
||
| 963 | </p> |
||
| 964 | |||
| 965 | <p> |
||
| 966 | The activation state of the node is sent by the load-balancer in the |
||
| 967 | request, so no state change on the node being disabled is necessary. Simply |
||
| 968 | configure this Valve in your valve pipeline and it will take action when |
||
| 969 | the activation state is set to "disabled". |
||
| 970 | </p> |
||
| 971 | |||
| 972 | <p> |
||
| 973 | You should take care to register this Valve earlier in the Valve pipeline |
||
| 974 | than any authentication Valves, because this Valve should be able to |
||
| 975 | redirect a request before any authentication Valve saves a request to a |
||
| 976 | protected resource. If this happens, a new session will be created and |
||
| 977 | the draining process will stall because a new, valid session will be |
||
| 978 | established. |
||
| 979 | </p> |
||
| 980 | </div></div> |
||
| 981 | |||
| 982 | <div class="subsection"><h4 id="Load_Balancer_Draining_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 983 | <p>The <strong>Load Balancer Draining Valve</strong> supports the |
||
| 984 | following configuration attributes:</p> |
||
| 985 | |||
| 986 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 987 | Attribute |
||
| 988 | </th><th style="width: 85%;"> |
||
| 989 | Description |
||
| 990 | </th></tr><tr id="Load Balancer Draining Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 991 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 992 | <strong>org.apache.catalina.valves.LoadBalancerDrainingValve</strong>. |
||
| 993 | </p> |
||
| 994 | </td></tr><tr id="Load Balancer Draining Valve_Attributes_redirectStatusCode"><td><code class="attributeName">redirectStatusCode</code></td><td> |
||
| 995 | <p>Allows setting a custom redirect code to be used when the client |
||
| 996 | is redirected to be re-balanced by the load-balancer. The default is |
||
| 997 | 307 TEMPORARY_REDIRECT.</p> |
||
| 998 | </td></tr><tr id="Load Balancer Draining Valve_Attributes_ignoreCookieName"><td><code class="attributeName">ignoreCookieName</code></td><td> |
||
| 999 | <p>When used with <code>ignoreCookieValue</code>, a client can present |
||
| 1000 | this cookie (and accompanying value) that will cause this Valve to |
||
| 1001 | do nothing. This will allow you to probe your <i>disabled</i> node |
||
| 1002 | before re-enabling it to make sure that it is working as expected.</p> |
||
| 1003 | </td></tr><tr id="Load Balancer Draining Valve_Attributes_ignoreCookieValue"><td><code class="attributeName">ignoreCookieValue</code></td><td> |
||
| 1004 | <p>When used with <code>ignoreCookieName</code>, a client can present |
||
| 1005 | a cookie (and accompanying value) that will cause this Valve to |
||
| 1006 | do nothing. This will allow you to probe your <i>disabled</i> node |
||
| 1007 | before re-enabling it to make sure that it is working as expected.</p> |
||
| 1008 | </td></tr></table> |
||
| 1009 | </div></div> |
||
| 1010 | </div></div> |
||
| 1011 | |||
| 1012 | <div class="subsection"><h4 id="Remote_IP_Valve">Remote IP Valve</h4><div class="text"> |
||
| 1013 | |||
| 1014 | <div class="subsection"><h4 id="Remote_IP_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1015 | |||
| 1016 | <p>Tomcat port of |
||
| 1017 | <a href="https://httpd.apache.org/docs/trunk/mod/mod_remoteip.html">mod_remoteip</a>, |
||
| 1018 | this valve replaces the apparent client remote IP address and hostname for |
||
| 1019 | the request with the IP address list presented by a proxy or a load balancer |
||
| 1020 | via a request headers (e.g. "X-Forwarded-For").</p> |
||
| 1021 | |||
| 1022 | <p>Another feature of this valve is to replace the apparent scheme |
||
| 1023 | (http/https), server port and <code>request.secure</code> with the scheme presented |
||
| 1024 | by a proxy or a load balancer via a request header |
||
| 1025 | (e.g. "X-Forwarded-Proto").</p> |
||
| 1026 | |||
| 1027 | <p>This Valve may be used at the <code>Engine</code>, <code>Host</code> or |
||
| 1028 | <code>Context</code> level as required. Normally, this Valve would be used |
||
| 1029 | at the <code>Engine</code> level.</p> |
||
| 1030 | |||
| 1031 | <p>If used in conjunction with Remote Address/Host valves then this valve |
||
| 1032 | should be defined first to ensure that the correct client IP address is |
||
| 1033 | presented to the Remote Address/Host valves.</p> |
||
| 1034 | |||
| 1035 | <p><strong>Note:</strong> By default this valve has no effect on the |
||
| 1036 | values that are written into access log. The original values are restored |
||
| 1037 | when request processing leaves the valve and that always happens earlier |
||
| 1038 | than access logging. To pass the remote address, remote host, server port |
||
| 1039 | and protocol values set by this valve to the access log, |
||
| 1040 | they are put into request attributes. Publishing these values here |
||
| 1041 | is enabled by default, but <code>AccessLogValve</code> should be explicitly |
||
| 1042 | configured to use them. See documentation for |
||
| 1043 | <code>requestAttributesEnabled</code> attribute of |
||
| 1044 | <code>AccessLogValve</code>.</p> |
||
| 1045 | |||
| 1046 | <p>The names of request attributes that are set by this valve |
||
| 1047 | and can be used by access logging are the following:</p> |
||
| 1048 | |||
| 1049 | <ul> |
||
| 1050 | <li><code>org.apache.catalina.AccessLog.RemoteAddr</code></li> |
||
| 1051 | <li><code>org.apache.catalina.AccessLog.RemoteHost</code></li> |
||
| 1052 | <li><code>org.apache.catalina.AccessLog.Protocol</code></li> |
||
| 1053 | <li><code>org.apache.catalina.AccessLog.ServerPort</code></li> |
||
| 1054 | <li><code>org.apache.tomcat.remoteAddr</code></li> |
||
| 1055 | </ul> |
||
| 1056 | |||
| 1057 | </div></div> |
||
| 1058 | |||
| 1059 | <div class="subsection"><h4 id="Remote_IP_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1060 | |||
| 1061 | <p>The <strong>Remote IP Valve</strong> supports the |
||
| 1062 | following configuration attributes:</p> |
||
| 1063 | |||
| 1064 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1065 | Attribute |
||
| 1066 | </th><th style="width: 85%;"> |
||
| 1067 | Description |
||
| 1068 | </th></tr><tr id="Remote IP Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1069 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1070 | <strong>org.apache.catalina.valves.RemoteIpValve</strong>.</p> |
||
| 1071 | </td></tr><tr id="Remote IP Valve_Attributes_remoteIpHeader"><td><code class="attributeName">remoteIpHeader</code></td><td> |
||
| 1072 | <p>Name of the HTTP Header read by this valve that holds the list of |
||
| 1073 | traversed IP addresses starting from the requesting client. If not |
||
| 1074 | specified, the default of <code>x-forwarded-for</code> is used.</p> |
||
| 1075 | </td></tr><tr id="Remote IP Valve_Attributes_internalProxies"><td><code class="attributeName">internalProxies</code></td><td> |
||
| 1076 | <p>Regular expression (using <code>java.util.regex</code>) that a |
||
| 1077 | proxy's IP address must match to be considered an internal proxy. |
||
| 1078 | Internal proxies that appear in the <strong>remoteIpHeader</strong> will |
||
| 1079 | be trusted and will not appear in the <strong>proxiesHeader</strong> |
||
| 1080 | value. If not specified the default value of <code> |
||
| 1081 | 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}|100\.6[4-9]{1}\.\d{1,3}\.\d{1,3}|100\.[7-9]{1}\d{1}\.\d{1,3}\.\d{1,3}|100\.1[0-1]{1}\d{1}\.\d{1,3}\.\d{1,3}|100\.12[0-7]{1}\.\d{1,3}\.\d{1,3}|172\.1[6-9]{1}\.\d{1,3}\.\d{1,3}|172\.2[0-9]{1}\.\d{1,3}\.\d{1,3}|172\.3[0-1]{1}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1|::1|fe[89ab]\p{XDigit}:.*|"f[cd]\p{XDigit}{2}+:.* |
||
| 1082 | </code> will be used.</p> |
||
| 1083 | </td></tr><tr id="Remote IP Valve_Attributes_proxiesHeader"><td><code class="attributeName">proxiesHeader</code></td><td> |
||
| 1084 | <p>Name of the HTTP header created by this valve to hold the list of |
||
| 1085 | proxies that have been processed in the incoming |
||
| 1086 | <strong>remoteIpHeader</strong>. If not specified, the default of |
||
| 1087 | <code>x-forwarded-by</code> is used.</p> |
||
| 1088 | </td></tr><tr id="Remote IP Valve_Attributes_requestAttributesEnabled"><td><code class="attributeName">requestAttributesEnabled</code></td><td> |
||
| 1089 | <p>Set to <code>true</code> to set the request attributes used by |
||
| 1090 | AccessLog implementations to override the values returned by the |
||
| 1091 | request for remote address, remote host, server port and protocol. |
||
| 1092 | Request attributes are also used to enable the forwarded remote address |
||
| 1093 | to be displayed on the status page of the Manager web application. |
||
| 1094 | If not set, the default value of <code>true</code> will be used.</p> |
||
| 1095 | </td></tr><tr id="Remote IP Valve_Attributes_trustedProxies"><td><code class="attributeName">trustedProxies</code></td><td> |
||
| 1096 | <p>Regular expression (using <code>java.util.regex</code>) that a |
||
| 1097 | proxy's IP address must match to be considered an trusted proxy. |
||
| 1098 | Trusted proxies that appear in the <strong>remoteIpHeader</strong> will |
||
| 1099 | be trusted and will appear in the <strong>proxiesHeader</strong> value. |
||
| 1100 | If not specified, no proxies will be trusted.</p> |
||
| 1101 | </td></tr><tr id="Remote IP Valve_Attributes_protocolHeader"><td><code class="attributeName">protocolHeader</code></td><td> |
||
| 1102 | <p>Name of the HTTP Header read by this valve that holds the protocol |
||
| 1103 | used by the client to connect to the proxy. If not specified, the |
||
| 1104 | default of <code>X-Forwarded-Proto</code> is used.</p> |
||
| 1105 | </td></tr><tr id="Remote IP Valve_Attributes_hostHeader"><td><code class="attributeName">hostHeader</code></td><td> |
||
| 1106 | <p>Name of the HTTP Header read by this valve that holds the host |
||
| 1107 | used by the client to connect to the proxy. If not specified, the |
||
| 1108 | default of <code>null</code> is used.</p> |
||
| 1109 | </td></tr><tr id="Remote IP Valve_Attributes_portHeader"><td><code class="attributeName">portHeader</code></td><td> |
||
| 1110 | <p>Name of the HTTP Header read by this valve that holds the port |
||
| 1111 | used by the client to connect to the proxy. If not specified, the |
||
| 1112 | default of <code>null</code> is used.</p> |
||
| 1113 | </td></tr><tr id="Remote IP Valve_Attributes_protocolHeaderHttpsValue"><td><code class="attributeName">protocolHeaderHttpsValue</code></td><td> |
||
| 1114 | <p>Value of the <strong>protocolHeader</strong> to indicate that it is |
||
| 1115 | an HTTPS request. If not specified, the default of <code>https</code> is |
||
| 1116 | used.</p> |
||
| 1117 | </td></tr><tr id="Remote IP Valve_Attributes_httpServerPort"><td><code class="attributeName">httpServerPort</code></td><td> |
||
| 1118 | <p>Value returned by <code>ServletRequest.getServerPort()</code> |
||
| 1119 | when the <strong>protocolHeader</strong> indicates <code>http</code> |
||
| 1120 | protocol and no <strong>portHeader</strong> is present. If not |
||
| 1121 | specified, the default of <code>80</code> is used.</p> |
||
| 1122 | </td></tr><tr id="Remote IP Valve_Attributes_httpsServerPort"><td><code class="attributeName">httpsServerPort</code></td><td> |
||
| 1123 | <p>Value returned by <code>ServletRequest.getServerPort()</code> |
||
| 1124 | when the <strong>protocolHeader</strong> indicates <code>https</code> |
||
| 1125 | protocol and no <strong>portHeader</strong> is present. If not |
||
| 1126 | specified, the default of <code>443</code> is used.</p> |
||
| 1127 | </td></tr><tr id="Remote IP Valve_Attributes_changeLocalName"><td><code class="attributeName">changeLocalName</code></td><td> |
||
| 1128 | <p>If <code>true</code>, the value returned by |
||
| 1129 | <code>ServletRequest.getLocalHost()</code> and |
||
| 1130 | <code>ServletRequest.getServerHost()</code> is modified by the this |
||
| 1131 | valve. If not specified, the default of <code>false</code> is used.</p> |
||
| 1132 | </td></tr><tr id="Remote IP Valve_Attributes_changeLocalPort"><td><code class="attributeName">changeLocalPort</code></td><td> |
||
| 1133 | <p>If <code>true</code>, the value returned by |
||
| 1134 | <code>ServletRequest.getLocalPort()</code> and |
||
| 1135 | <code>ServletRequest.getServerPort()</code> is modified by the this |
||
| 1136 | valve. If not specified, the default of <code>false</code> is used.</p> |
||
| 1137 | </td></tr></table> |
||
| 1138 | |||
| 1139 | </div></div> |
||
| 1140 | |||
| 1141 | </div></div> |
||
| 1142 | |||
| 1143 | |||
| 1144 | <div class="subsection"><h4 id="SSL_Valve">SSL Valve</h4><div class="text"> |
||
| 1145 | |||
| 1146 | <div class="subsection"><h4 id="SSL_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1147 | |||
| 1148 | <p>When using mod_proxy_http, the client SSL information is not included in |
||
| 1149 | the protocol (unlike mod_jk and mod_proxy_ajp). To make the client SSL |
||
| 1150 | information available to Tomcat, some additional configuration is required. |
||
| 1151 | In httpd, mod_headers is used to add the SSL information as HTTP headers. In |
||
| 1152 | Tomcat, this valve is used to read the information from the HTTP headers and |
||
| 1153 | insert it into the request.</p> |
||
| 1154 | |||
| 1155 | <p>Note: Ensure that the headers are always set by httpd for all requests to |
||
| 1156 | prevent a client spoofing SSL information by sending fake headers.</p> |
||
| 1157 | |||
| 1158 | <p>To configure httpd to set the necessary headers, add the following:</p> |
||
| 1159 | <div class="codeBox"><pre><code><IfModule ssl_module> |
||
| 1160 | RequestHeader set SSL_CLIENT_CERT "%{SSL_CLIENT_CERT}s" |
||
| 1161 | RequestHeader set SSL_CIPHER "%{SSL_CIPHER}s" |
||
| 1162 | RequestHeader set SSL_SESSION_ID "%{SSL_SESSION_ID}s" |
||
| 1163 | RequestHeader set SSL_CIPHER_USEKEYSIZE "%{SSL_CIPHER_USEKEYSIZE}s" |
||
| 1164 | </IfModule></code></pre></div> |
||
| 1165 | |||
| 1166 | </div></div> |
||
| 1167 | |||
| 1168 | <div class="subsection"><h4 id="SSL_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1169 | |||
| 1170 | <p>The <strong>SSL Valve</strong> supports the following configuration |
||
| 1171 | attribute:</p> |
||
| 1172 | |||
| 1173 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1174 | Attribute |
||
| 1175 | </th><th style="width: 85%;"> |
||
| 1176 | Description |
||
| 1177 | </th></tr><tr id="SSL Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1178 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1179 | <strong>org.apache.catalina.valves.SSLValve</strong>. |
||
| 1180 | </p> |
||
| 1181 | </td></tr><tr id="SSL Valve_Attributes_sslClientCertHeader"><td><code class="attributeName">sslClientCertHeader</code></td><td> |
||
| 1182 | <p>Allows setting a custom name for the ssl_client_cert header. |
||
| 1183 | If not specified, the default of <code>ssl_client_cert</code> is |
||
| 1184 | used.</p> |
||
| 1185 | </td></tr><tr id="SSL Valve_Attributes_sslClientEscapedCertHeader"><td><code class="attributeName">sslClientEscapedCertHeader</code></td><td> |
||
| 1186 | <p>Allows setting a custom name for the ssl_client_escaped_cert header. |
||
| 1187 | If not specified, the default of <code>ssl_client_escaped_cert</code> is |
||
| 1188 | used.</p> |
||
| 1189 | <p>This header is useful for Nginx proxying, and takes precedence over |
||
| 1190 | the ssl_client_cert header.</p> |
||
| 1191 | </td></tr><tr id="SSL Valve_Attributes_sslCipherHeader"><td><code class="attributeName">sslCipherHeader</code></td><td> |
||
| 1192 | <p>Allows setting a custom name for the ssl_cipher header. |
||
| 1193 | If not specified, the default of <code>ssl_cipher</code> is |
||
| 1194 | used.</p> |
||
| 1195 | </td></tr><tr id="SSL Valve_Attributes_sslSessionIdHeader"><td><code class="attributeName">sslSessionIdHeader</code></td><td> |
||
| 1196 | <p>Allows setting a custom name for the ssl_session_id header. |
||
| 1197 | If not specified, the default of <code>ssl_session_id</code> is |
||
| 1198 | used.</p> |
||
| 1199 | </td></tr><tr id="SSL Valve_Attributes_sslCipherUserKeySizeHeader"><td><code class="attributeName">sslCipherUserKeySizeHeader</code></td><td> |
||
| 1200 | <p>Allows setting a custom name for the ssl_cipher_usekeysize header. |
||
| 1201 | If not specified, the default of <code>ssl_cipher_usekeysize</code> is |
||
| 1202 | used.</p> |
||
| 1203 | </td></tr></table> |
||
| 1204 | |||
| 1205 | </div></div> |
||
| 1206 | |||
| 1207 | </div></div> |
||
| 1208 | |||
| 1209 | |||
| 1210 | </div><h3 id="Single_Sign_On_Valve">Single Sign On Valve</h3><div class="text"> |
||
| 1211 | |||
| 1212 | <div class="subsection"><h4 id="Single_Sign_On_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1213 | |||
| 1214 | <p>The <em>Single Sign On Valve</em> is utilized when you wish to give users |
||
| 1215 | the ability to sign on to any one of the web applications associated with |
||
| 1216 | your virtual host, and then have their identity recognized by all other |
||
| 1217 | web applications on the same virtual host.</p> |
||
| 1218 | |||
| 1219 | <p>See the <a href="host.html#Single_Sign_On">Single Sign On</a> special |
||
| 1220 | feature on the <strong>Host</strong> element for more information.</p> |
||
| 1221 | |||
| 1222 | </div></div> |
||
| 1223 | |||
| 1224 | |||
| 1225 | <div class="subsection"><h4 id="Single_Sign_On_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1226 | |||
| 1227 | <p>The <strong>Single Sign On</strong> Valve supports the following |
||
| 1228 | configuration attributes:</p> |
||
| 1229 | |||
| 1230 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1231 | Attribute |
||
| 1232 | </th><th style="width: 85%;"> |
||
| 1233 | Description |
||
| 1234 | </th></tr><tr id="Single Sign On Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1235 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1236 | <strong>org.apache.catalina.authenticator.SingleSignOn</strong>.</p> |
||
| 1237 | </td></tr><tr id="Single Sign On Valve_Attributes_requireReauthentication"><td><code class="attributeName">requireReauthentication</code></td><td> |
||
| 1238 | <p>Default false. Flag to determine whether each request needs to be |
||
| 1239 | reauthenticated to the security <strong>Realm</strong>. If "true", this |
||
| 1240 | Valve uses cached security credentials (username and password) to |
||
| 1241 | reauthenticate to the <strong>Realm</strong> each request associated |
||
| 1242 | with an SSO session. If "false", the Valve can itself authenticate |
||
| 1243 | requests based on the presence of a valid SSO cookie, without |
||
| 1244 | rechecking with the <strong>Realm</strong>.</p> |
||
| 1245 | </td></tr><tr id="Single Sign On Valve_Attributes_cookieDomain"><td><code class="attributeName">cookieDomain</code></td><td> |
||
| 1246 | <p>Sets the host domain to be used for sso cookies.</p> |
||
| 1247 | </td></tr><tr id="Single Sign On Valve_Attributes_cookieName"><td><code class="attributeName">cookieName</code></td><td> |
||
| 1248 | <p>Sets the cookie name to be used for sso cookies. The default value |
||
| 1249 | is <code>JSESSIONIDSSO</code></p> |
||
| 1250 | </td></tr></table> |
||
| 1251 | |||
| 1252 | </div></div> |
||
| 1253 | |||
| 1254 | |||
| 1255 | </div><h3 id="Authentication">Authentication</h3><div class="text"> |
||
| 1256 | |||
| 1257 | <p>The valves in this section implement |
||
| 1258 | <strong>org.apache.catalina.Authenticator</strong> interface.</p> |
||
| 1259 | |||
| 1260 | <div class="subsection"><h4 id="Basic_Authenticator_Valve">Basic Authenticator Valve</h4><div class="text"> |
||
| 1261 | |||
| 1262 | <div class="subsection"><h4 id="Basic_Authenticator_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1263 | |||
| 1264 | <p>The <strong>Basic Authenticator Valve</strong> is automatically added to |
||
| 1265 | any <a href="context.html">Context</a> that is configured to use BASIC |
||
| 1266 | authentication.</p> |
||
| 1267 | |||
| 1268 | <p>If any non-default settings are required, the valve may be configured |
||
| 1269 | within <a href="context.html">Context</a> element with the required |
||
| 1270 | values.</p> |
||
| 1271 | |||
| 1272 | </div></div> |
||
| 1273 | |||
| 1274 | <div class="subsection"><h4 id="Basic_Authenticator_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1275 | |||
| 1276 | <p>The <strong>Basic Authenticator Valve</strong> supports the following |
||
| 1277 | configuration attributes:</p> |
||
| 1278 | |||
| 1279 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1280 | Attribute |
||
| 1281 | </th><th style="width: 85%;"> |
||
| 1282 | Description |
||
| 1283 | </th></tr><tr id="Basic Authenticator Valve_Attributes_allowCorsPreflight"><td><code class="attributeName">allowCorsPreflight</code></td><td> |
||
| 1284 | <p>Are requests that appear to be CORS preflight requests allowed to |
||
| 1285 | bypass the authenticator as required by the CORS specification. The |
||
| 1286 | allowed values are <code>never</code>, <code>filter</code> and |
||
| 1287 | <code>always</code>. <code>never</code> means that a request will never |
||
| 1288 | bypass authentication even if it appears to be a CORS preflight request. |
||
| 1289 | <code>filter</code> means that a request will bypass authentication if |
||
| 1290 | it appears to be a CORS preflight request; it is mapped to a web |
||
| 1291 | application that has the <a href="filter.html#CORS_Filter">CORS |
||
| 1292 | Filter</a> enabled; and the request matches the URLPatterns for the CORS |
||
| 1293 | filter mapper. |
||
| 1294 | <code>always</code> means that all requests that appear to be CORS |
||
| 1295 | preflight requests will bypass authentication. If not set, the default |
||
| 1296 | value is <code>never</code>.</p> |
||
| 1297 | </td></tr><tr id="Basic Authenticator Valve_Attributes_alwaysUseSession"><td><code class="attributeName">alwaysUseSession</code></td><td> |
||
| 1298 | <p>Should a session always be used once a user is authenticated? This |
||
| 1299 | may offer some performance benefits since the session can then be used |
||
| 1300 | to cache the authenticated Principal, hence removing the need to |
||
| 1301 | authenticate the user via the Realm on every request. This may be of |
||
| 1302 | help for combinations such as BASIC authentication used with the |
||
| 1303 | JNDIRealm or DataSourceRealms. However there will also be the |
||
| 1304 | performance cost of creating and GC'ing the session. If not set, the |
||
| 1305 | default value of <code>false</code> will be used.</p> |
||
| 1306 | </td></tr><tr id="Basic Authenticator Valve_Attributes_cache"><td><code class="attributeName">cache</code></td><td> |
||
| 1307 | <p>Should we cache authenticated Principals if the request is part of an |
||
| 1308 | HTTP session? If not specified, the default value of <code>true</code> |
||
| 1309 | will be used.</p> |
||
| 1310 | </td></tr><tr id="Basic Authenticator Valve_Attributes_changeSessionIdOnAuthentication"><td><code class="attributeName">changeSessionIdOnAuthentication</code></td><td> |
||
| 1311 | <p>Controls if the session ID is changed if a session exists at the |
||
| 1312 | point where users are authenticated. This is to prevent session fixation |
||
| 1313 | attacks. If not set, the default value of <code>true</code> will be |
||
| 1314 | used.</p> |
||
| 1315 | </td></tr><tr id="Basic Authenticator Valve_Attributes_charset"><td><code class="attributeName">charset</code></td><td> |
||
| 1316 | <p>Controls if the <code>WWW-Authenticate</code> HTTP header includes a |
||
| 1317 | <code>charset</code> authentication parameter as per RFC 7617. The only |
||
| 1318 | permitted options are <code>null</code>, the empty string and |
||
| 1319 | <code>UTF-8</code>. If <code>UTF-8</code> is specified then the |
||
| 1320 | <code>charset</code> authentication parameter will be sent with that |
||
| 1321 | value and the provided user name and optional password will be converted |
||
| 1322 | from bytes to characters using UTF-8. Otherwise, no <code>charset</code> |
||
| 1323 | authentication parameter will be sent and the provided user name and |
||
| 1324 | optional password will be converted from bytes to characters using |
||
| 1325 | ISO-8859-1. The default value is <code>null</code></p> |
||
| 1326 | </td></tr><tr id="Basic Authenticator Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1327 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1328 | <strong>org.apache.catalina.authenticator.BasicAuthenticator</strong>.</p> |
||
| 1329 | </td></tr><tr id="Basic Authenticator Valve_Attributes_disableProxyCaching"><td><code class="attributeName">disableProxyCaching</code></td><td> |
||
| 1330 | <p>Controls the caching of pages that are protected by security |
||
| 1331 | constraints. Setting this to <code>false</code> may help work around |
||
| 1332 | caching issues in some browsers but will also cause secured pages to be |
||
| 1333 | cached by proxies which will almost certainly be a security issue. |
||
| 1334 | <code>securePagesWithPragma</code> offers an alternative, secure, |
||
| 1335 | workaround for browser caching issues. If not set, the default value of |
||
| 1336 | <code>true</code> will be used.</p> |
||
| 1337 | </td></tr><tr id="Basic Authenticator Valve_Attributes_jaspicCallbackHandlerClass"><td><code class="attributeName">jaspicCallbackHandlerClass</code></td><td> |
||
| 1338 | <p>Name of the Java class of the |
||
| 1339 | <code>javax.security.auth.callback.CallbackHandler</code> implementation |
||
| 1340 | which should be used by JASPIC. If none is specified the default |
||
| 1341 | <code>org.apache.catalina.authenticator.jaspic.CallbackHandlerImpl</code> |
||
| 1342 | will be used.</p> |
||
| 1343 | </td></tr><tr id="Basic Authenticator Valve_Attributes_securePagesWithPragma"><td><code class="attributeName">securePagesWithPragma</code></td><td> |
||
| 1344 | <p>Controls the caching of pages that are protected by security |
||
| 1345 | constraints. Setting this to <code>false</code> may help work around |
||
| 1346 | caching issues in some browsers by using |
||
| 1347 | <code>Cache-Control: private</code> rather than the default of |
||
| 1348 | <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>. |
||
| 1349 | If not set, the default value of <code>false</code> will be used.</p> |
||
| 1350 | </td></tr><tr id="Basic Authenticator Valve_Attributes_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 1351 | <p>Name of the algorithm to use to create the |
||
| 1352 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 1353 | IDs. If an invalid algorithm and/or provider is specified, the platform |
||
| 1354 | default provider and the default algorithm will be used. If not |
||
| 1355 | specified, the default algorithm of SHA1PRNG will be used. If the |
||
| 1356 | default algorithm is not supported, the platform default will be used. |
||
| 1357 | To specify that the platform default should be used, do not set the |
||
| 1358 | secureRandomProvider attribute and set this attribute to the empty |
||
| 1359 | string.</p> |
||
| 1360 | </td></tr><tr id="Basic Authenticator Valve_Attributes_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 1361 | <p>Name of the Java class that extends |
||
| 1362 | <code>java.security.SecureRandom</code> to use to generate SSO session |
||
| 1363 | IDs. If not specified, the default value is |
||
| 1364 | <code>java.security.SecureRandom</code>.</p> |
||
| 1365 | </td></tr><tr id="Basic Authenticator Valve_Attributes_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 1366 | <p>Name of the provider to use to create the |
||
| 1367 | <code>java.security.SecureRandom</code> instances that generate SSO |
||
| 1368 | session IDs. If an invalid algorithm and/or provider is specified, the |
||
| 1369 | platform default provider and the default algorithm will be used. If not |
||
| 1370 | specified, the platform default provider will be used.</p> |
||
| 1371 | </td></tr><tr id="Basic Authenticator Valve_Attributes_sendAuthInfoResponseHeaders"><td><code class="attributeName">sendAuthInfoResponseHeaders</code></td><td> |
||
| 1372 | <p>Controls whether the auth information (remote user and auth type) |
||
| 1373 | shall be returned as response headers for a forwarded/proxied request. |
||
| 1374 | When the <code>RemoteIpValve</code> or <code>RemoteIpFilter</code> mark |
||
| 1375 | a forwarded request with the <code>Globals.REQUEST_FORWARDED_ATTRIBUTE</code> |
||
| 1376 | this authenticator can return the values of |
||
| 1377 | <code>HttpServletRequest.getRemoteUser()</code> and |
||
| 1378 | <code>HttpServletRequest.getAuthType()</code> as response headers |
||
| 1379 | <code>remote-user</code> and <code>auth-type</code> to a reverse proxy. |
||
| 1380 | This is useful, e.g., for access log consistency or other decisions to make. |
||
| 1381 | If not specified, the default value is <code>false</code>.</p> |
||
| 1382 | </td></tr><tr id="Basic Authenticator Valve_Attributes_trimCredentials"><td><code class="attributeName">trimCredentials</code></td><td> |
||
| 1383 | <p>Controls whether leading and/or trailing whitespace is removed from |
||
| 1384 | the parsed credentials. If not specified, the default value is |
||
| 1385 | <code>false</code>. |
||
| 1386 | </p> |
||
| 1387 | <p>Note: This attribute will be removed from Tomcat 11 onwards.</p> |
||
| 1388 | </td></tr></table> |
||
| 1389 | |||
| 1390 | </div></div> |
||
| 1391 | |||
| 1392 | </div></div> |
||
| 1393 | |||
| 1394 | |||
| 1395 | <div class="subsection"><h4 id="Digest_Authenticator_Valve">Digest Authenticator Valve</h4><div class="text"> |
||
| 1396 | |||
| 1397 | <div class="subsection"><h4 id="Digest_Authenticator_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1398 | |||
| 1399 | <p>The <strong>Digest Authenticator Valve</strong> is automatically added to |
||
| 1400 | any <a href="context.html">Context</a> that is configured to use DIGEST |
||
| 1401 | authentication.</p> |
||
| 1402 | |||
| 1403 | <p>If any non-default settings are required, the valve may be configured |
||
| 1404 | within <a href="context.html">Context</a> element with the required |
||
| 1405 | values.</p> |
||
| 1406 | |||
| 1407 | </div></div> |
||
| 1408 | |||
| 1409 | <div class="subsection"><h4 id="Digest_Authenticator_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1410 | |||
| 1411 | <p>The <strong>Digest Authenticator Valve</strong> supports the following |
||
| 1412 | configuration attributes:</p> |
||
| 1413 | |||
| 1414 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1415 | Attribute |
||
| 1416 | </th><th style="width: 85%;"> |
||
| 1417 | Description |
||
| 1418 | </th></tr><tr id="Digest Authenticator Valve_Attributes_algorithms"><td><code class="attributeName">algorithms</code></td><td> |
||
| 1419 | <p>A comma-separated list of digest algorithms to be used for the |
||
| 1420 | authentication process. Algorithms may be specified using the Java |
||
| 1421 | Standard names or the names used by RFC 7616. If not specified, the |
||
| 1422 | default value of <code>SHA-256,MD5</code> will be used.</p> |
||
| 1423 | </td></tr><tr id="Digest Authenticator Valve_Attributes_allowCorsPreflight"><td><code class="attributeName">allowCorsPreflight</code></td><td> |
||
| 1424 | <p>Are requests that appear to be CORS preflight requests allowed to |
||
| 1425 | bypass the authenticator as required by the CORS specification. The |
||
| 1426 | allowed values are <code>never</code>, <code>filter</code> and |
||
| 1427 | <code>always</code>. <code>never</code> means that a request will never |
||
| 1428 | bypass authentication even if it appears to be a CORS preflight request. |
||
| 1429 | <code>filter</code> means that a request will bypass authentication if |
||
| 1430 | it appears to be a CORS preflight request; it is mapped to a web |
||
| 1431 | application that has the <a href="filter.html#CORS_Filter">CORS |
||
| 1432 | Filter</a> enabled; and the request matches the URLPatterns for the CORS |
||
| 1433 | filter mapper. |
||
| 1434 | <code>always</code> means that all requests that appear to be CORS |
||
| 1435 | preflight requests will bypass authentication. If not set, the default |
||
| 1436 | value is <code>never</code>.</p> |
||
| 1437 | </td></tr><tr id="Digest Authenticator Valve_Attributes_alwaysUseSession"><td><code class="attributeName">alwaysUseSession</code></td><td> |
||
| 1438 | <p>Should a session always be used once a user is authenticated? This |
||
| 1439 | may offer some performance benefits since the session can then be used |
||
| 1440 | to cache the authenticated Principal, hence removing the need to |
||
| 1441 | authenticate the user via the Realm on every request. This may be of |
||
| 1442 | help for combinations such as BASIC authentication used with the |
||
| 1443 | JNDIRealm or DataSourceRealms. However there will also be the |
||
| 1444 | performance cost of creating and GC'ing the session. If not set, the |
||
| 1445 | default value of <code>false</code> will be used.</p> |
||
| 1446 | </td></tr><tr id="Digest Authenticator Valve_Attributes_cache"><td><code class="attributeName">cache</code></td><td> |
||
| 1447 | <p>Should we cache authenticated Principals if the request is part of an |
||
| 1448 | HTTP session? If not specified, the default value of <code>false</code> |
||
| 1449 | will be used.</p> |
||
| 1450 | </td></tr><tr id="Digest Authenticator Valve_Attributes_changeSessionIdOnAuthentication"><td><code class="attributeName">changeSessionIdOnAuthentication</code></td><td> |
||
| 1451 | <p>Controls if the session ID is changed if a session exists at the |
||
| 1452 | point where users are authenticated. This is to prevent session fixation |
||
| 1453 | attacks. If not set, the default value of <code>true</code> will be |
||
| 1454 | used.</p> |
||
| 1455 | </td></tr><tr id="Digest Authenticator Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1456 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1457 | <strong>org.apache.catalina.authenticator.DigestAuthenticator</strong>.</p> |
||
| 1458 | </td></tr><tr id="Digest Authenticator Valve_Attributes_disableProxyCaching"><td><code class="attributeName">disableProxyCaching</code></td><td> |
||
| 1459 | <p>Controls the caching of pages that are protected by security |
||
| 1460 | constraints. Setting this to <code>false</code> may help work around |
||
| 1461 | caching issues in some browsers but will also cause secured pages to be |
||
| 1462 | cached by proxies which will almost certainly be a security issue. |
||
| 1463 | <code>securePagesWithPragma</code> offers an alternative, secure, |
||
| 1464 | workaround for browser caching issues. If not set, the default value of |
||
| 1465 | <code>true</code> will be used.</p> |
||
| 1466 | </td></tr><tr id="Digest Authenticator Valve_Attributes_jaspicCallbackHandlerClass"><td><code class="attributeName">jaspicCallbackHandlerClass</code></td><td> |
||
| 1467 | <p>Name of the Java class of the |
||
| 1468 | <code>javax.security.auth.callback.CallbackHandler</code> implementation |
||
| 1469 | which should be used by JASPIC. If none is specified the default |
||
| 1470 | <code>org.apache.catalina.authenticator.jaspic.CallbackHandlerImpl</code> |
||
| 1471 | will be used.</p> |
||
| 1472 | </td></tr><tr id="Digest Authenticator Valve_Attributes_key"><td><code class="attributeName">key</code></td><td> |
||
| 1473 | <p>The secret key used by digest authentication. If not set, a secure |
||
| 1474 | random value is generated. This should normally only be set when it is |
||
| 1475 | necessary to keep key values constant either across server restarts |
||
| 1476 | and/or across a cluster.</p> |
||
| 1477 | </td></tr><tr id="Digest Authenticator Valve_Attributes_nonceCacheSize"><td><code class="attributeName">nonceCacheSize</code></td><td> |
||
| 1478 | <p>To protect against replay attacks, the DIGEST authenticator tracks |
||
| 1479 | server nonce and nonce count values. This attribute controls the size |
||
| 1480 | of that cache. If not specified, the default value of 1000 is used.</p> |
||
| 1481 | </td></tr><tr id="Digest Authenticator Valve_Attributes_nonceCountWindowSize"><td><code class="attributeName">nonceCountWindowSize</code></td><td> |
||
| 1482 | <p>Client requests may be processed out of order which in turn means |
||
| 1483 | that the nonce count values may be processed out of order. To prevent |
||
| 1484 | authentication failures when nonce counts are presented out of order |
||
| 1485 | the authenticator tracks a window of nonce count values. This attribute |
||
| 1486 | controls how big that window is. If not specified, the default value of |
||
| 1487 | 100 is used.</p> |
||
| 1488 | </td></tr><tr id="Digest Authenticator Valve_Attributes_nonceValidity"><td><code class="attributeName">nonceValidity</code></td><td> |
||
| 1489 | <p>The time, in milliseconds, that a server generated nonce will be |
||
| 1490 | considered valid for use in authentication. If not specified, the |
||
| 1491 | default value of 300000 (5 minutes) will be used.</p> |
||
| 1492 | </td></tr><tr id="Digest Authenticator Valve_Attributes_opaque"><td><code class="attributeName">opaque</code></td><td> |
||
| 1493 | <p>The opaque server string used by digest authentication. If not set, a |
||
| 1494 | random value is generated. This should normally only be set when it is |
||
| 1495 | necessary to keep opaque values constant either across server restarts |
||
| 1496 | and/or across a cluster.</p> |
||
| 1497 | </td></tr><tr id="Digest Authenticator Valve_Attributes_securePagesWithPragma"><td><code class="attributeName">securePagesWithPragma</code></td><td> |
||
| 1498 | <p>Controls the caching of pages that are protected by security |
||
| 1499 | constraints. Setting this to <code>false</code> may help work around |
||
| 1500 | caching issues in some browsers by using |
||
| 1501 | <code>Cache-Control: private</code> rather than the default of |
||
| 1502 | <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>. |
||
| 1503 | If not set, the default value of <code>false</code> will be used.</p> |
||
| 1504 | </td></tr><tr id="Digest Authenticator Valve_Attributes_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 1505 | <p>Name of the algorithm to use to create the |
||
| 1506 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 1507 | IDs. If an invalid algorithm and/or provider is specified, the platform |
||
| 1508 | default provider and the default algorithm will be used. If not |
||
| 1509 | specified, the default algorithm of SHA1PRNG will be used. If the |
||
| 1510 | default algorithm is not supported, the platform default will be used. |
||
| 1511 | To specify that the platform default should be used, do not set the |
||
| 1512 | secureRandomProvider attribute and set this attribute to the empty |
||
| 1513 | string.</p> |
||
| 1514 | </td></tr><tr id="Digest Authenticator Valve_Attributes_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 1515 | <p>Name of the Java class that extends |
||
| 1516 | <code>java.security.SecureRandom</code> to use to generate SSO session |
||
| 1517 | IDs. If not specified, the default value is |
||
| 1518 | <code>java.security.SecureRandom</code>.</p> |
||
| 1519 | </td></tr><tr id="Digest Authenticator Valve_Attributes_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 1520 | <p>Name of the provider to use to create the |
||
| 1521 | <code>java.security.SecureRandom</code> instances that generate SSO |
||
| 1522 | session IDs. If an invalid algorithm and/or provider is specified, the |
||
| 1523 | platform default provider and the default algorithm will be used. If not |
||
| 1524 | specified, the platform default provider will be used.</p> |
||
| 1525 | </td></tr><tr id="Digest Authenticator Valve_Attributes_sendAuthInfoResponseHeaders"><td><code class="attributeName">sendAuthInfoResponseHeaders</code></td><td> |
||
| 1526 | <p>Controls whether the auth information (remote user and auth type) |
||
| 1527 | shall be returned as response headers for a forwarded/proxied request. |
||
| 1528 | When the <code>RemoteIpValve</code> or <code>RemoteIpFilter</code> mark |
||
| 1529 | a forwarded request with the <code>Globals.REQUEST_FORWARDED_ATTRIBUTE</code> |
||
| 1530 | this authenticator can return the values of |
||
| 1531 | <code>HttpServletRequest.getRemoteUser()</code> and |
||
| 1532 | <code>HttpServletRequest.getAuthType()</code> as response headers |
||
| 1533 | <code>remote-user</code> and <code>auth-type</code> to a reverse proxy. |
||
| 1534 | This is useful, e.g., for access log consistency or other decisions to make. |
||
| 1535 | If not specified, the default value is <code>false</code>.</p> |
||
| 1536 | </td></tr><tr id="Digest Authenticator Valve_Attributes_validateUri"><td><code class="attributeName">validateUri</code></td><td> |
||
| 1537 | <p>Should the URI be validated as required by RFC2617? If not specified, |
||
| 1538 | the default value of <code>true</code> will be used. This should |
||
| 1539 | normally only be set when Tomcat is located behind a reverse proxy and |
||
| 1540 | the proxy is modifying the URI passed to Tomcat such that DIGEST |
||
| 1541 | authentication always fails.</p> |
||
| 1542 | </td></tr></table> |
||
| 1543 | |||
| 1544 | </div></div> |
||
| 1545 | |||
| 1546 | </div></div> |
||
| 1547 | |||
| 1548 | |||
| 1549 | <div class="subsection"><h4 id="Form_Authenticator_Valve">Form Authenticator Valve</h4><div class="text"> |
||
| 1550 | |||
| 1551 | <div class="subsection"><h4 id="Form_Authenticator_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1552 | |||
| 1553 | <p>The <strong>Form Authenticator Valve</strong> is automatically added to |
||
| 1554 | any <a href="context.html">Context</a> that is configured to use FORM |
||
| 1555 | authentication.</p> |
||
| 1556 | |||
| 1557 | <p>If any non-default settings are required, the valve may be configured |
||
| 1558 | within <a href="context.html">Context</a> element with the required |
||
| 1559 | values.</p> |
||
| 1560 | |||
| 1561 | </div></div> |
||
| 1562 | |||
| 1563 | <div class="subsection"><h4 id="Form_Authenticator_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1564 | |||
| 1565 | <p>The <strong>Form Authenticator Valve</strong> supports the following |
||
| 1566 | configuration attributes:</p> |
||
| 1567 | |||
| 1568 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1569 | Attribute |
||
| 1570 | </th><th style="width: 85%;"> |
||
| 1571 | Description |
||
| 1572 | </th></tr><tr id="Form Authenticator Valve_Attributes_allowCorsPreflight"><td><code class="attributeName">allowCorsPreflight</code></td><td> |
||
| 1573 | <p>Are requests that appear to be CORS preflight requests allowed to |
||
| 1574 | bypass the authenticator as required by the CORS specification. The |
||
| 1575 | allowed values are <code>never</code>, <code>filter</code> and |
||
| 1576 | <code>always</code>. <code>never</code> means that a request will never |
||
| 1577 | bypass authentication even if it appears to be a CORS preflight request. |
||
| 1578 | <code>filter</code> means that a request will bypass authentication if |
||
| 1579 | it appears to be a CORS preflight request; it is mapped to a web |
||
| 1580 | application that has the <a href="filter.html#CORS_Filter">CORS |
||
| 1581 | Filter</a> enabled; and the request matches the URLPatterns for the CORS |
||
| 1582 | filter mapper. |
||
| 1583 | <code>always</code> means that all requests that appear to be CORS |
||
| 1584 | preflight requests will bypass authentication. If not set, the default |
||
| 1585 | value is <code>never</code>.</p> |
||
| 1586 | </td></tr><tr id="Form Authenticator Valve_Attributes_authenticationSessionTimeout"><td><code class="attributeName">authenticationSessionTimeout</code></td><td> |
||
| 1587 | <p>If the authentication process creates a session, this is the maximum session timeout (in seconds) during the |
||
| 1588 | authentication process. Once authentication is complete, the default session timeout will apply. Sessions that |
||
| 1589 | exist before the authentication process starts will retain their original session timeout throughout. If not |
||
| 1590 | set, the default value of <code>120</code> seconds will be used.</p> |
||
| 1591 | </td></tr><tr id="Form Authenticator Valve_Attributes_changeSessionIdOnAuthentication"><td><code class="attributeName">changeSessionIdOnAuthentication</code></td><td> |
||
| 1592 | <p>Controls if the session ID is changed if a session exists at the |
||
| 1593 | point where users are authenticated. This is to prevent session fixation |
||
| 1594 | attacks. If not set, the default value of <code>true</code> will be |
||
| 1595 | used.</p> |
||
| 1596 | </td></tr><tr id="Form Authenticator Valve_Attributes_characterEncoding"><td><code class="attributeName">characterEncoding</code></td><td> |
||
| 1597 | <p>Character encoding to use to read the username and password parameters |
||
| 1598 | from the request. If not set, the encoding of the request body will be |
||
| 1599 | used.</p> |
||
| 1600 | </td></tr><tr id="Form Authenticator Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1601 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1602 | <strong>org.apache.catalina.authenticator.FormAuthenticator</strong>.</p> |
||
| 1603 | </td></tr><tr id="Form Authenticator Valve_Attributes_disableProxyCaching"><td><code class="attributeName">disableProxyCaching</code></td><td> |
||
| 1604 | <p>Controls the caching of pages that are protected by security |
||
| 1605 | constraints. Setting this to <code>false</code> may help work around |
||
| 1606 | caching issues in some browsers but will also cause secured pages to be |
||
| 1607 | cached by proxies which will almost certainly be a security issue. |
||
| 1608 | <code>securePagesWithPragma</code> offers an alternative, secure, |
||
| 1609 | workaround for browser caching issues. If not set, the default value of |
||
| 1610 | <code>true</code> will be used.</p> |
||
| 1611 | </td></tr><tr id="Form Authenticator Valve_Attributes_jaspicCallbackHandlerClass"><td><code class="attributeName">jaspicCallbackHandlerClass</code></td><td> |
||
| 1612 | <p>Name of the Java class of the |
||
| 1613 | <code>javax.security.auth.callback.CallbackHandler</code> implementation |
||
| 1614 | which should be used by JASPIC. If none is specified the default |
||
| 1615 | <code>org.apache.catalina.authenticator.jaspic.CallbackHandlerImpl</code> |
||
| 1616 | will be used.</p> |
||
| 1617 | </td></tr><tr id="Form Authenticator Valve_Attributes_landingPage"><td><code class="attributeName">landingPage</code></td><td> |
||
| 1618 | <p>Controls the behavior of the FORM authentication process if the |
||
| 1619 | process is misused, for example by directly requesting the login page |
||
| 1620 | or delaying logging in for so long that the session expires. If this |
||
| 1621 | attribute is set, rather than returning an error response code, Tomcat |
||
| 1622 | will redirect the user to the specified landing page if the login form |
||
| 1623 | is submitted with valid credentials. For the login to be processed, the |
||
| 1624 | landing page must be a protected resource (i.e. one that requires |
||
| 1625 | authentication). If the landing page does not require authentication |
||
| 1626 | then the user will not be logged in and will be prompted for their |
||
| 1627 | credentials again when they access a protected page.</p> |
||
| 1628 | </td></tr><tr id="Form Authenticator Valve_Attributes_securePagesWithPragma"><td><code class="attributeName">securePagesWithPragma</code></td><td> |
||
| 1629 | <p>Controls the caching of pages that are protected by security |
||
| 1630 | constraints. Setting this to <code>false</code> may help work around |
||
| 1631 | caching issues in some browsers by using |
||
| 1632 | <code>Cache-Control: private</code> rather than the default of |
||
| 1633 | <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>. |
||
| 1634 | If not set, the default value of <code>false</code> will be used.</p> |
||
| 1635 | </td></tr><tr id="Form Authenticator Valve_Attributes_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 1636 | <p>Name of the algorithm to use to create the |
||
| 1637 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 1638 | IDs. If an invalid algorithm and/or provider is specified, the platform |
||
| 1639 | default provider and the default algorithm will be used. If not |
||
| 1640 | specified, the default algorithm of SHA1PRNG will be used. If the |
||
| 1641 | default algorithm is not supported, the platform default will be used. |
||
| 1642 | To specify that the platform default should be used, do not set the |
||
| 1643 | secureRandomProvider attribute and set this attribute to the empty |
||
| 1644 | string.</p> |
||
| 1645 | </td></tr><tr id="Form Authenticator Valve_Attributes_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 1646 | <p>Name of the Java class that extends |
||
| 1647 | <code>java.security.SecureRandom</code> to use to generate SSO session |
||
| 1648 | IDs. If not specified, the default value is |
||
| 1649 | <code>java.security.SecureRandom</code>.</p> |
||
| 1650 | </td></tr><tr id="Form Authenticator Valve_Attributes_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 1651 | <p>Name of the provider to use to create the |
||
| 1652 | <code>java.security.SecureRandom</code> instances that generate SSO |
||
| 1653 | session IDs. If an invalid algorithm and/or provider is specified, the |
||
| 1654 | platform default provider and the default algorithm will be used. If not |
||
| 1655 | specified, the platform default provider will be used.</p> |
||
| 1656 | </td></tr><tr id="Form Authenticator Valve_Attributes_sendAuthInfoResponseHeaders"><td><code class="attributeName">sendAuthInfoResponseHeaders</code></td><td> |
||
| 1657 | <p>Controls whether the auth information (remote user and auth type) |
||
| 1658 | shall be returned as response headers for a forwarded/proxied request. |
||
| 1659 | When the <code>RemoteIpValve</code> or <code>RemoteIpFilter</code> mark |
||
| 1660 | a forwarded request with the <code>Globals.REQUEST_FORWARDED_ATTRIBUTE</code> |
||
| 1661 | this authenticator can return the values of |
||
| 1662 | <code>HttpServletRequest.getRemoteUser()</code> and |
||
| 1663 | <code>HttpServletRequest.getAuthType()</code> as response headers |
||
| 1664 | <code>remote-user</code> and <code>auth-type</code> to a reverse proxy. |
||
| 1665 | This is useful, e.g., for access log consistency or other decisions to make. |
||
| 1666 | If not specified, the default value is <code>false</code>.</p> |
||
| 1667 | </td></tr></table> |
||
| 1668 | |||
| 1669 | </div></div> |
||
| 1670 | |||
| 1671 | </div></div> |
||
| 1672 | |||
| 1673 | |||
| 1674 | <div class="subsection"><h4 id="SSL_Authenticator_Valve">SSL Authenticator Valve</h4><div class="text"> |
||
| 1675 | |||
| 1676 | <div class="subsection"><h4 id="SSL_Authenticator_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1677 | |||
| 1678 | <p>The <strong>SSL Authenticator Valve</strong> is automatically added to |
||
| 1679 | any <a href="context.html">Context</a> that is configured to use SSL |
||
| 1680 | authentication.</p> |
||
| 1681 | |||
| 1682 | <p>If any non-default settings are required, the valve may be configured |
||
| 1683 | within <a href="context.html">Context</a> element with the required |
||
| 1684 | values.</p> |
||
| 1685 | |||
| 1686 | </div></div> |
||
| 1687 | |||
| 1688 | <div class="subsection"><h4 id="SSL_Authenticator_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1689 | |||
| 1690 | <p>The <strong>SSL Authenticator Valve</strong> supports the following |
||
| 1691 | configuration attributes:</p> |
||
| 1692 | |||
| 1693 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1694 | Attribute |
||
| 1695 | </th><th style="width: 85%;"> |
||
| 1696 | Description |
||
| 1697 | </th></tr><tr id="SSL Authenticator Valve_Attributes_allowCorsPreflight"><td><code class="attributeName">allowCorsPreflight</code></td><td> |
||
| 1698 | <p>Are requests that appear to be CORS preflight requests allowed to |
||
| 1699 | bypass the authenticator as required by the CORS specification. The |
||
| 1700 | allowed values are <code>never</code>, <code>filter</code> and |
||
| 1701 | <code>always</code>. <code>never</code> means that a request will never |
||
| 1702 | bypass authentication even if it appears to be a CORS preflight request. |
||
| 1703 | <code>filter</code> means that a request will bypass authentication if |
||
| 1704 | it appears to be a CORS preflight request; it is mapped to a web |
||
| 1705 | application that has the <a href="filter.html#CORS_Filter">CORS |
||
| 1706 | Filter</a> enabled; and the request matches the URLPatterns for the CORS |
||
| 1707 | filter mapper. |
||
| 1708 | <code>always</code> means that all requests that appear to be CORS |
||
| 1709 | preflight requests will bypass authentication. If not set, the default |
||
| 1710 | value is <code>never</code>.</p> |
||
| 1711 | </td></tr><tr id="SSL Authenticator Valve_Attributes_cache"><td><code class="attributeName">cache</code></td><td> |
||
| 1712 | <p>Should we cache authenticated Principals if the request is part of an |
||
| 1713 | HTTP session? If not specified, the default value of <code>true</code> |
||
| 1714 | will be used.</p> |
||
| 1715 | </td></tr><tr id="SSL Authenticator Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1716 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1717 | <strong>org.apache.catalina.authenticator.SSLAuthenticator</strong>.</p> |
||
| 1718 | </td></tr><tr id="SSL Authenticator Valve_Attributes_changeSessionIdOnAuthentication"><td><code class="attributeName">changeSessionIdOnAuthentication</code></td><td> |
||
| 1719 | <p>Controls if the session ID is changed if a session exists at the |
||
| 1720 | point where users are authenticated. This is to prevent session fixation |
||
| 1721 | attacks. If not set, the default value of <code>true</code> will be |
||
| 1722 | used.</p> |
||
| 1723 | </td></tr><tr id="SSL Authenticator Valve_Attributes_disableProxyCaching"><td><code class="attributeName">disableProxyCaching</code></td><td> |
||
| 1724 | <p>Controls the caching of pages that are protected by security |
||
| 1725 | constraints. Setting this to <code>false</code> may help work around |
||
| 1726 | caching issues in some browsers but will also cause secured pages to be |
||
| 1727 | cached by proxies which will almost certainly be a security issue. |
||
| 1728 | <code>securePagesWithPragma</code> offers an alternative, secure, |
||
| 1729 | workaround for browser caching issues. If not set, the default value of |
||
| 1730 | <code>true</code> will be used.</p> |
||
| 1731 | </td></tr><tr id="SSL Authenticator Valve_Attributes_jaspicCallbackHandlerClass"><td><code class="attributeName">jaspicCallbackHandlerClass</code></td><td> |
||
| 1732 | <p>Name of the Java class of the |
||
| 1733 | <code>javax.security.auth.callback.CallbackHandler</code> implementation |
||
| 1734 | which should be used by JASPIC. If none is specified the default |
||
| 1735 | <code>org.apache.catalina.authenticator.jaspic.CallbackHandlerImpl</code> |
||
| 1736 | will be used.</p> |
||
| 1737 | </td></tr><tr id="SSL Authenticator Valve_Attributes_securePagesWithPragma"><td><code class="attributeName">securePagesWithPragma</code></td><td> |
||
| 1738 | <p>Controls the caching of pages that are protected by security |
||
| 1739 | constraints. Setting this to <code>false</code> may help work around |
||
| 1740 | caching issues in some browsers by using |
||
| 1741 | <code>Cache-Control: private</code> rather than the default of |
||
| 1742 | <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>. |
||
| 1743 | If not set, the default value of <code>false</code> will be used.</p> |
||
| 1744 | </td></tr><tr id="SSL Authenticator Valve_Attributes_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 1745 | <p>Name of the algorithm to use to create the |
||
| 1746 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 1747 | IDs. If an invalid algorithm and/or provider is specified, the platform |
||
| 1748 | default provider and the default algorithm will be used. If not |
||
| 1749 | specified, the default algorithm of SHA1PRNG will be used. If the |
||
| 1750 | default algorithm is not supported, the platform default will be used. |
||
| 1751 | To specify that the platform default should be used, do not set the |
||
| 1752 | secureRandomProvider attribute and set this attribute to the empty |
||
| 1753 | string.</p> |
||
| 1754 | </td></tr><tr id="SSL Authenticator Valve_Attributes_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 1755 | <p>Name of the Java class that extends |
||
| 1756 | <code>java.security.SecureRandom</code> to use to generate SSO session |
||
| 1757 | IDs. If not specified, the default value is |
||
| 1758 | <code>java.security.SecureRandom</code>.</p> |
||
| 1759 | </td></tr><tr id="SSL Authenticator Valve_Attributes_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 1760 | <p>Name of the provider to use to create the |
||
| 1761 | <code>java.security.SecureRandom</code> instances that generate SSO |
||
| 1762 | session IDs. If an invalid algorithm and/or provider is specified, the |
||
| 1763 | platform default provider and the default algorithm will be used. If not |
||
| 1764 | specified, the platform default provider will be used.</p> |
||
| 1765 | </td></tr></table> |
||
| 1766 | |||
| 1767 | </div></div> |
||
| 1768 | |||
| 1769 | </div></div> |
||
| 1770 | |||
| 1771 | |||
| 1772 | <div class="subsection"><h4 id="SPNEGO_Valve">SPNEGO Valve</h4><div class="text"> |
||
| 1773 | |||
| 1774 | <div class="subsection"><h4 id="SPNEGO_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1775 | |||
| 1776 | <p>The <strong>SPNEGO Authenticator Valve</strong> is automatically added to |
||
| 1777 | any <a href="context.html">Context</a> that is configured to use SPNEGO |
||
| 1778 | authentication.</p> |
||
| 1779 | |||
| 1780 | <p>If any non-default settings are required, the valve may be configured |
||
| 1781 | within <a href="context.html">Context</a> element with the required |
||
| 1782 | values.</p> |
||
| 1783 | |||
| 1784 | </div></div> |
||
| 1785 | |||
| 1786 | <div class="subsection"><h4 id="SPNEGO_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1787 | |||
| 1788 | <p>The <strong>SPNEGO Authenticator Valve</strong> supports the following |
||
| 1789 | configuration attributes:</p> |
||
| 1790 | |||
| 1791 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1792 | Attribute |
||
| 1793 | </th><th style="width: 85%;"> |
||
| 1794 | Description |
||
| 1795 | </th></tr><tr id="SPNEGO Valve_Attributes_allowCorsPreflight"><td><code class="attributeName">allowCorsPreflight</code></td><td> |
||
| 1796 | <p>Are requests that appear to be CORS preflight requests allowed to |
||
| 1797 | bypass the authenticator as required by the CORS specification. The |
||
| 1798 | allowed values are <code>never</code>, <code>filter</code> and |
||
| 1799 | <code>always</code>. <code>never</code> means that a request will never |
||
| 1800 | bypass authentication even if it appears to be a CORS preflight request. |
||
| 1801 | <code>filter</code> means that a request will bypass authentication if |
||
| 1802 | it appears to be a CORS preflight request and the web application the |
||
| 1803 | request maps to has the <a href="filter.html#CORS_Filter">CORS |
||
| 1804 | Filter</a> enabled; and the request matches the URLPatterns for the CORS |
||
| 1805 | filter mapper. |
||
| 1806 | means that all requests that appear to be CORS preflight requests will |
||
| 1807 | bypass authentication. If not set, the default value is |
||
| 1808 | <code>never</code>.</p> |
||
| 1809 | </td></tr><tr id="SPNEGO Valve_Attributes_alwaysUseSession"><td><code class="attributeName">alwaysUseSession</code></td><td> |
||
| 1810 | <p>Should a session always be used once a user is authenticated? This |
||
| 1811 | may offer some performance benefits since the session can then be used |
||
| 1812 | to cache the authenticated Principal, hence removing the need to |
||
| 1813 | authenticate the user on every request. This will also help with clients |
||
| 1814 | that assume that the server will cache the authenticated user. However |
||
| 1815 | there will also be the performance cost of creating and GC'ing the |
||
| 1816 | session. For an alternative solution see |
||
| 1817 | <code>noKeepAliveUserAgents</code>. If not set, the default value of |
||
| 1818 | <code>false</code> will be used.</p> |
||
| 1819 | </td></tr><tr id="SPNEGO Valve_Attributes_applyJava8u40Fix"><td><code class="attributeName">applyJava8u40Fix</code></td><td> |
||
| 1820 | <p>A fix introduced in Java 8 update 40 ( |
||
| 1821 | <a href="https://bugs.openjdk.java.net/browse/JDK-8048194">JDK-8048194</a>) |
||
| 1822 | onwards broke SPNEGO authentication for IE with Tomcat running on |
||
| 1823 | Windows 2008 R2 servers. This option enables a work-around that allows |
||
| 1824 | SPNEGO authentication to continue working. The work-around should not |
||
| 1825 | impact other configurations so it is enabled by default. If necessary, |
||
| 1826 | the workaround can be disabled by setting this attribute to |
||
| 1827 | <code>false</code>.</p> |
||
| 1828 | </td></tr><tr id="SPNEGO Valve_Attributes_cache"><td><code class="attributeName">cache</code></td><td> |
||
| 1829 | <p>Should we cache authenticated Principals if the request is part of an |
||
| 1830 | HTTP session? If not specified, the default value of <code>true</code> |
||
| 1831 | will be used.</p> |
||
| 1832 | </td></tr><tr id="SPNEGO Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1833 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1834 | <strong>org.apache.catalina.authenticator.SpnegoAuthenticator</strong>. |
||
| 1835 | </p> |
||
| 1836 | </td></tr><tr id="SPNEGO Valve_Attributes_changeSessionIdOnAuthentication"><td><code class="attributeName">changeSessionIdOnAuthentication</code></td><td> |
||
| 1837 | <p>Controls if the session ID is changed if a session exists at the |
||
| 1838 | point where users are authenticated. This is to prevent session fixation |
||
| 1839 | attacks. If not set, the default value of <code>true</code> will be |
||
| 1840 | used.</p> |
||
| 1841 | </td></tr><tr id="SPNEGO Valve_Attributes_disableProxyCaching"><td><code class="attributeName">disableProxyCaching</code></td><td> |
||
| 1842 | <p>Controls the caching of pages that are protected by security |
||
| 1843 | constraints. Setting this to <code>false</code> may help work around |
||
| 1844 | caching issues in some browsers but will also cause secured pages to be |
||
| 1845 | cached by proxies which will almost certainly be a security issue. |
||
| 1846 | <code>securePagesWithPragma</code> offers an alternative, secure, |
||
| 1847 | workaround for browser caching issues. If not set, the default value of |
||
| 1848 | <code>true</code> will be used.</p> |
||
| 1849 | </td></tr><tr id="SPNEGO Valve_Attributes_jaspicCallbackHandlerClass"><td><code class="attributeName">jaspicCallbackHandlerClass</code></td><td> |
||
| 1850 | <p>Name of the Java class of the |
||
| 1851 | <code>javax.security.auth.callback.CallbackHandler</code> implementation |
||
| 1852 | which should be used by JASPIC. If none is specified the default |
||
| 1853 | <code>org.apache.catalina.authenticator.jaspic.CallbackHandlerImpl</code> |
||
| 1854 | will be used.</p> |
||
| 1855 | </td></tr><tr id="SPNEGO Valve_Attributes_loginConfigName"><td><code class="attributeName">loginConfigName</code></td><td> |
||
| 1856 | <p>The name of the JAAS login configuration to be used to login as the |
||
| 1857 | service. If not specified, the default of |
||
| 1858 | <code>com.sun.security.jgss.krb5.accept</code> is used.</p> |
||
| 1859 | </td></tr><tr id="SPNEGO Valve_Attributes_noKeepAliveUserAgents"><td><code class="attributeName">noKeepAliveUserAgents</code></td><td> |
||
| 1860 | <p>Some clients (not most browsers) expect the server to cache the |
||
| 1861 | authenticated user information for a connection and do not resend the |
||
| 1862 | credentials with every request. Tomcat will not do this unless an HTTP |
||
| 1863 | session is available. A session will be available if either the |
||
| 1864 | application creates one or if <code>alwaysUseSession</code> is enabled |
||
| 1865 | for this Authenticator.</p> |
||
| 1866 | <p>As an alternative to creating a session, this attribute may be used |
||
| 1867 | to define the user agents for which HTTP keep-alive is disabled. This |
||
| 1868 | means that a connection will only used for a single request and hence |
||
| 1869 | there is no ability to cache authenticated user information per |
||
| 1870 | connection. There will be a performance cost in disabling HTTP |
||
| 1871 | keep-alive.</p> |
||
| 1872 | <p>The attribute should be a regular expression that matches the entire |
||
| 1873 | user-agent string, e.g. <code>.*Chrome.*</code>. If not specified, no |
||
| 1874 | regular expression will be defined and no user agents will have HTTP |
||
| 1875 | keep-alive disabled.</p> |
||
| 1876 | </td></tr><tr id="SPNEGO Valve_Attributes_securePagesWithPragma"><td><code class="attributeName">securePagesWithPragma</code></td><td> |
||
| 1877 | <p>Controls the caching of pages that are protected by security |
||
| 1878 | constraints. Setting this to <code>false</code> may help work around |
||
| 1879 | caching issues in some browsers by using |
||
| 1880 | <code>Cache-Control: private</code> rather than the default of |
||
| 1881 | <code>Pragma: No-cache</code> and <code>Cache-control: No-cache</code>. |
||
| 1882 | If not set, the default value of <code>false</code> will be used.</p> |
||
| 1883 | </td></tr><tr id="SPNEGO Valve_Attributes_secureRandomAlgorithm"><td><code class="attributeName">secureRandomAlgorithm</code></td><td> |
||
| 1884 | <p>Name of the algorithm to use to create the |
||
| 1885 | <code>java.security.SecureRandom</code> instances that generate session |
||
| 1886 | IDs. If an invalid algorithm and/or provider is specified, the platform |
||
| 1887 | default provider and the default algorithm will be used. If not |
||
| 1888 | specified, the default algorithm of SHA1PRNG will be used. If the |
||
| 1889 | default algorithm is not supported, the platform default will be used. |
||
| 1890 | To specify that the platform default should be used, do not set the |
||
| 1891 | secureRandomProvider attribute and set this attribute to the empty |
||
| 1892 | string.</p> |
||
| 1893 | </td></tr><tr id="SPNEGO Valve_Attributes_secureRandomClass"><td><code class="attributeName">secureRandomClass</code></td><td> |
||
| 1894 | <p>Name of the Java class that extends |
||
| 1895 | <code>java.security.SecureRandom</code> to use to generate SSO session |
||
| 1896 | IDs. If not specified, the default value is |
||
| 1897 | <code>java.security.SecureRandom</code>.</p> |
||
| 1898 | </td></tr><tr id="SPNEGO Valve_Attributes_secureRandomProvider"><td><code class="attributeName">secureRandomProvider</code></td><td> |
||
| 1899 | <p>Name of the provider to use to create the |
||
| 1900 | <code>java.security.SecureRandom</code> instances that generate SSO |
||
| 1901 | session IDs. If an invalid algorithm and/or provider is specified, the |
||
| 1902 | platform default provider and the default algorithm will be used. If not |
||
| 1903 | specified, the platform default provider will be used.</p> |
||
| 1904 | </td></tr><tr id="SPNEGO Valve_Attributes_sendAuthInfoResponseHeaders"><td><code class="attributeName">sendAuthInfoResponseHeaders</code></td><td> |
||
| 1905 | <p>Controls whether the auth information (remote user and auth type) |
||
| 1906 | shall be returned as response headers for a forwarded/proxied request. |
||
| 1907 | When the <code>RemoteIpValve</code> or <code>RemoteIpFilter</code> mark |
||
| 1908 | a forwarded request with the <code>Globals.REQUEST_FORWARDED_ATTRIBUTE</code> |
||
| 1909 | this authenticator can return the values of |
||
| 1910 | <code>HttpServletRequest.getRemoteUser()</code> and |
||
| 1911 | <code>HttpServletRequest.getAuthType()</code> as response headers |
||
| 1912 | <code>remote-user</code> and <code>auth-type</code> to a reverse proxy. |
||
| 1913 | This is useful, e.g., for access log consistency or other decisions to make. |
||
| 1914 | If not specified, the default value is <code>false</code>.</p> |
||
| 1915 | </td></tr><tr id="SPNEGO Valve_Attributes_storeDelegatedCredential"><td><code class="attributeName">storeDelegatedCredential</code></td><td> |
||
| 1916 | <p>Controls if the user' delegated credential will be stored in |
||
| 1917 | the user Principal. If available, the delegated credential will be |
||
| 1918 | available to applications (e.g. for onward authentication to external |
||
| 1919 | services) via the <code>org.apache.catalina.realm.GSS_CREDENTIAL</code> |
||
| 1920 | request attribute. If not set, the default value of <code>true</code> |
||
| 1921 | will be used.</p> |
||
| 1922 | </td></tr></table> |
||
| 1923 | |||
| 1924 | </div></div> |
||
| 1925 | |||
| 1926 | </div></div> |
||
| 1927 | |||
| 1928 | |||
| 1929 | </div><h3 id="Error_Report_Valve">Error Report Valve</h3><div class="text"> |
||
| 1930 | |||
| 1931 | <div class="subsection"><h4 id="Error_Report_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1932 | |||
| 1933 | <p>The <strong>Error Report Valve</strong> is a simple error handler |
||
| 1934 | for HTTP status codes that will generate and return HTML error pages. It can |
||
| 1935 | also be configured to return pre-defined static HTML pages for specific |
||
| 1936 | status codes and/or exception types.</p> |
||
| 1937 | |||
| 1938 | <p><strong>NOTE:</strong> Disabling both showServerInfo and showReport will |
||
| 1939 | only return the HTTP status code.</p> |
||
| 1940 | |||
| 1941 | </div></div> |
||
| 1942 | |||
| 1943 | <div class="subsection"><h4 id="Error_Report_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 1944 | |||
| 1945 | <p>The <strong>Error Report Valve</strong> supports the following |
||
| 1946 | configuration attributes:</p> |
||
| 1947 | |||
| 1948 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 1949 | Attribute |
||
| 1950 | </th><th style="width: 85%;"> |
||
| 1951 | Description |
||
| 1952 | </th></tr><tr id="Error Report Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 1953 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 1954 | <strong>org.apache.catalina.valves.ErrorReportValve</strong> to use the |
||
| 1955 | default error report valve.</p> |
||
| 1956 | </td></tr><tr id="Error Report Valve_Attributes_errorCode.nnn"><td><code class="attributeName">errorCode.nnn</code></td><td> |
||
| 1957 | <p>The location of the UTF-8 encoded HTML file to return for the HTTP |
||
| 1958 | error code represented by <code>nnn</code>. For example, |
||
| 1959 | <code>errorCode.404</code> specifies the file to return for an HTTP 404 |
||
| 1960 | error. The location may be relative or absolute. If relative, it must be |
||
| 1961 | relative to <code>$CATALINA_BASE</code>. The special value of |
||
| 1962 | <code>errorCode.0</code> may be used to define a default error page to |
||
| 1963 | be used if no error page is defined for a status code. If no matching |
||
| 1964 | error page is found, the default <strong>Error Report Valve</strong> |
||
| 1965 | response will be returned.</p> |
||
| 1966 | </td></tr><tr id="Error Report Valve_Attributes_exceptionType.fullyQualifiedClassName"><td><code class="attributeName">exceptionType.fullyQualifiedClassName</code></td><td> |
||
| 1967 | <p>The location of the UTF-8 encoded HTML file to return if an error has |
||
| 1968 | occurred and the <code>javax.servlet.error.exception</code> request |
||
| 1969 | attribute has been set to an instance of |
||
| 1970 | <code>fullyQualifiedClassName</code> or a sub-class of it. For example, |
||
| 1971 | <code>errorCode.java.io.IOException</code> specifies the file to return |
||
| 1972 | for an <code>IOException</code>. The location may be relative or |
||
| 1973 | absolute. If relative, it must be relative to |
||
| 1974 | <code>$CATALINA_BASE</code>. If no matching error page is found, the |
||
| 1975 | default <strong>Error Report Valve</strong> response will be |
||
| 1976 | returned.</p> |
||
| 1977 | </td></tr><tr id="Error Report Valve_Attributes_showReport"><td><code class="attributeName">showReport</code></td><td> |
||
| 1978 | <p>Flag to determine if the error report (custom error message and/or |
||
| 1979 | stack trace) is presented when an error occurs. If set to |
||
| 1980 | <code>false</code>, then the error report is not returned in the HTML |
||
| 1981 | response. |
||
| 1982 | Default value: <code>true</code> |
||
| 1983 | </p> |
||
| 1984 | </td></tr><tr id="Error Report Valve_Attributes_showServerInfo"><td><code class="attributeName">showServerInfo</code></td><td> |
||
| 1985 | <p>Flag to determine if server information is presented when an error |
||
| 1986 | occurs. If set to <code>false</code>, then the server version is not |
||
| 1987 | returned in the HTML response. |
||
| 1988 | Default value: <code>true</code> |
||
| 1989 | </p> |
||
| 1990 | </td></tr></table> |
||
| 1991 | |||
| 1992 | </div></div> |
||
| 1993 | |||
| 1994 | </div><h3 id="Json_Error_Report_Valve">Json Error Report Valve</h3><div class="text"> |
||
| 1995 | |||
| 1996 | <div class="subsection"><h4 id="Json_Error_Report_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 1997 | |||
| 1998 | <p>The <strong>Json Error Report Valve</strong> is a simple error handler |
||
| 1999 | for HTTP status codes that will return Json error messages.</p> |
||
| 2000 | |||
| 2001 | <p>By specifying this class in <code>errorReportValveClass</code> attribute |
||
| 2002 | in <code>Host</code>, it will be used instead of |
||
| 2003 | <code>ErrorReportValve</code> and will return JSON response instead of HTML. |
||
| 2004 | </p> |
||
| 2005 | |||
| 2006 | </div></div> |
||
| 2007 | |||
| 2008 | <div class="subsection"><h4 id="Json_Error_Report_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2009 | |||
| 2010 | <p>The <strong>Json Error Report Valve</strong> supports the following |
||
| 2011 | configuration attributes:</p> |
||
| 2012 | |||
| 2013 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2014 | Attribute |
||
| 2015 | </th><th style="width: 85%;"> |
||
| 2016 | Description |
||
| 2017 | </th></tr><tr id="Json Error Report Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2018 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2019 | <strong>org.apache.catalina.valves.JsonErrorReportValve</strong>.</p> |
||
| 2020 | </td></tr></table> |
||
| 2021 | |||
| 2022 | </div></div> |
||
| 2023 | |||
| 2024 | </div><h3 id="Proxy_Error_Report_Valve">Proxy Error Report Valve</h3><div class="text"> |
||
| 2025 | |||
| 2026 | <div class="subsection"><h4 id="Proxy_Error_Report_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2027 | |||
| 2028 | <p>The <strong>Proxy Error Report Valve</strong> is a simple error handler |
||
| 2029 | for HTTP status codes that will redirect or proxy to another location |
||
| 2030 | responsible for the generation of the error report.</p> |
||
| 2031 | |||
| 2032 | <p>By specifying this class in <code>errorReportValveClass</code> attribute |
||
| 2033 | in <code>Host</code>, it will be used instead of |
||
| 2034 | <code>ErrorReportValve</code> with the default attribute values. To |
||
| 2035 | configure the attributes, the valve can be defined nested in the |
||
| 2036 | <code>Host</code> element.</p> |
||
| 2037 | |||
| 2038 | </div></div> |
||
| 2039 | |||
| 2040 | <div class="subsection"><h4 id="Proxy_Error_Report_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2041 | |||
| 2042 | <p>The <strong>Proxy Error Report Valve</strong> supports the following |
||
| 2043 | configuration attributes:</p> |
||
| 2044 | |||
| 2045 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2046 | Attribute |
||
| 2047 | </th><th style="width: 85%;"> |
||
| 2048 | Description |
||
| 2049 | </th></tr><tr id="Proxy Error Report Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2050 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2051 | <strong>org.apache.catalina.valves.ProxyErrorReportValve</strong>.</p> |
||
| 2052 | </td></tr><tr id="Proxy Error Report Valve_Attributes_usePropertiesFile"><td><code class="attributeName">usePropertiesFile</code></td><td> |
||
| 2053 | <p>If <code>true</code>, the valve will use the properties file |
||
| 2054 | described below to associate the URLs with the status code. |
||
| 2055 | If <code>false</code>, the configuration mechanism of the default |
||
| 2056 | <code>ErrorReportValve</code> will be used instead. The default |
||
| 2057 | value is <code>false</code>.</p> |
||
| 2058 | </td></tr><tr id="Proxy Error Report Valve_Attributes_useRedirect"><td><code class="attributeName">useRedirect</code></td><td> |
||
| 2059 | <p>If <code>true</code>, the valve will send a redirect to the URL. |
||
| 2060 | If <code>false</code>, the valve will instead proxy the content from |
||
| 2061 | the specified URL. The default value is <code>true</code>.</p> |
||
| 2062 | </td></tr></table> |
||
| 2063 | |||
| 2064 | </div></div> |
||
| 2065 | |||
| 2066 | <div class="subsection"><h4 id="Configuration">Configuration</h4><div class="text"> |
||
| 2067 | |||
| 2068 | <p>The <strong>Proxy Error Report Valve</strong> can use a resource file |
||
| 2069 | <strong>ProxyErrorReportValve.properties</strong> |
||
| 2070 | from the class path, where each entry is a statusCode=baseUrl. baseUrl |
||
| 2071 | should not include any url parameters, statusCode, statusDescription, |
||
| 2072 | requestUri, and throwable which will be automatically appended. A special |
||
| 2073 | key named <code>0</code> should be used to match any other unmapped |
||
| 2074 | code to a redirect or proxy URL.</p> |
||
| 2075 | |||
| 2076 | </div></div> |
||
| 2077 | |||
| 2078 | </div><h3 id="Crawler_Session_Manager_Valve">Crawler Session Manager Valve</h3><div class="text"> |
||
| 2079 | |||
| 2080 | <div class="subsection"><h4 id="Crawler_Session_Manager_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2081 | |||
| 2082 | <p>Web crawlers can trigger the creation of many thousands of sessions as |
||
| 2083 | they crawl a site which may result in significant memory consumption. This |
||
| 2084 | Valve ensures that crawlers are associated with a single session - just like |
||
| 2085 | normal users - regardless of whether or not they provide a session token |
||
| 2086 | with their requests.</p> |
||
| 2087 | |||
| 2088 | <p>This Valve may be used at the <code>Engine</code>, <code>Host</code> or |
||
| 2089 | <code>Context</code> level as required. Normally, this Valve would be used |
||
| 2090 | at the <code>Engine</code> level.</p> |
||
| 2091 | |||
| 2092 | <p>If used in conjunction with Remote IP valve then the Remote IP valve |
||
| 2093 | should be defined before this valve to ensure that the correct client IP |
||
| 2094 | address is presented to this valve.</p> |
||
| 2095 | |||
| 2096 | </div></div> |
||
| 2097 | |||
| 2098 | <div class="subsection"><h4 id="Crawler_Session_Manager_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2099 | |||
| 2100 | <p>The <strong>Crawler Session Manager Valve</strong> supports the |
||
| 2101 | following configuration attributes:</p> |
||
| 2102 | |||
| 2103 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2104 | Attribute |
||
| 2105 | </th><th style="width: 85%;"> |
||
| 2106 | Description |
||
| 2107 | </th></tr><tr id="Crawler Session Manager Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2108 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2109 | <strong>org.apache.catalina.valves.CrawlerSessionManagerValve</strong>. |
||
| 2110 | </p> |
||
| 2111 | </td></tr><tr id="Crawler Session Manager Valve_Attributes_contextAware"><td><code class="attributeName">contextAware</code></td><td> |
||
| 2112 | <p>Flag to use the context name together with the client IP to |
||
| 2113 | identify the session to re-use. Can be combined with <code>hostAware</code>. |
||
| 2114 | Default value: <code>true</code> |
||
| 2115 | </p> |
||
| 2116 | </td></tr><tr id="Crawler Session Manager Valve_Attributes_crawlerIps"><td><code class="attributeName">crawlerIps</code></td><td> |
||
| 2117 | <p>Regular expression (using <code>java.util.regex</code>) that client |
||
| 2118 | IP is matched against to determine if a request is from a web crawler. |
||
| 2119 | By default such regular expression is not set.</p> |
||
| 2120 | </td></tr><tr id="Crawler Session Manager Valve_Attributes_crawlerUserAgents"><td><code class="attributeName">crawlerUserAgents</code></td><td> |
||
| 2121 | <p>Regular expression (using <code>java.util.regex</code>) that the user |
||
| 2122 | agent HTTP request header is matched against to determine if a request |
||
| 2123 | is from a web crawler. If not set, the default of |
||
| 2124 | <code>.*[bB]ot.*|.*Yahoo! Slurp.*|.*Feedfetcher-Google.*</code> is used.</p> |
||
| 2125 | </td></tr><tr id="Crawler Session Manager Valve_Attributes_hostAware"><td><code class="attributeName">hostAware</code></td><td> |
||
| 2126 | <p>Flag to use the configured host together with the client IP to |
||
| 2127 | identify the session to re-use. Can be combined with <code>contextAware</code>. |
||
| 2128 | Default value: <code>true</code> |
||
| 2129 | </p> |
||
| 2130 | </td></tr><tr id="Crawler Session Manager Valve_Attributes_sessionInactiveInterval"><td><code class="attributeName">sessionInactiveInterval</code></td><td> |
||
| 2131 | <p>The minimum time in seconds that the Crawler Session Manager Valve |
||
| 2132 | should keep the mapping of client IP to session ID in memory without any |
||
| 2133 | activity from the client. The client IP / session cache will be |
||
| 2134 | periodically purged of mappings that have been inactive for longer than |
||
| 2135 | this interval. If not specified the default value of <code>60</code> |
||
| 2136 | will be used.</p> |
||
| 2137 | </td></tr></table> |
||
| 2138 | |||
| 2139 | </div></div> |
||
| 2140 | |||
| 2141 | </div><h3 id="Stuck_Thread_Detection_Valve">Stuck Thread Detection Valve</h3><div class="text"> |
||
| 2142 | |||
| 2143 | <div class="subsection"><h4 id="Stuck_Thread_Detection_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2144 | |||
| 2145 | <p>This valve allows to detect requests that take a long time to process, |
||
| 2146 | which might indicate that the thread that is processing it is stuck. |
||
| 2147 | Additionally it can optionally interrupt such threads to try and unblock |
||
| 2148 | them.</p> |
||
| 2149 | <p>When such a request is detected, the current stack trace of its thread is |
||
| 2150 | written to Tomcat log with a WARN level.</p> |
||
| 2151 | <p>The IDs and names of the stuck threads are available through JMX in the |
||
| 2152 | <code>stuckThreadIds</code> and <code>stuckThreadNames</code> attributes. |
||
| 2153 | The IDs can be used with the standard Threading JVM MBean |
||
| 2154 | (<code>java.lang:type=Threading</code>) to retrieve other information |
||
| 2155 | about each stuck thread.</p> |
||
| 2156 | |||
| 2157 | </div></div> |
||
| 2158 | |||
| 2159 | <div class="subsection"><h4 id="Stuck_Thread_Detection_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2160 | |||
| 2161 | <p>The <strong>Stuck Thread Detection Valve</strong> supports the |
||
| 2162 | following configuration attributes:</p> |
||
| 2163 | |||
| 2164 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2165 | Attribute |
||
| 2166 | </th><th style="width: 85%;"> |
||
| 2167 | Description |
||
| 2168 | </th></tr><tr id="Stuck Thread Detection Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2169 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2170 | <strong>org.apache.catalina.valves.StuckThreadDetectionValve</strong>. |
||
| 2171 | </p> |
||
| 2172 | </td></tr><tr id="Stuck Thread Detection Valve_Attributes_threshold"><td><code class="attributeName">threshold</code></td><td> |
||
| 2173 | <p>Minimum duration in seconds after which a thread is considered stuck. |
||
| 2174 | Default is 600 seconds. If set to 0, the detection is disabled.</p> |
||
| 2175 | <p>Note: since the detection (and optional interruption) is done in the |
||
| 2176 | background thread of the Container (Engine, Host or Context) declaring |
||
| 2177 | this Valve, the threshold should be higher than the |
||
| 2178 | <code>backgroundProcessorDelay</code> of this Container.</p> |
||
| 2179 | </td></tr><tr id="Stuck Thread Detection Valve_Attributes_interruptThreadThreshold"><td><code class="attributeName">interruptThreadThreshold</code></td><td> |
||
| 2180 | <p>Minimum duration in seconds after which a stuck thread should be |
||
| 2181 | interrupted to attempt to "free" it.</p> |
||
| 2182 | <p>Note that there's no guarantee that the thread will get unstuck. |
||
| 2183 | This usually works well for threads stuck on I/O or locks, but is |
||
| 2184 | probably useless in case of infinite loops.</p> |
||
| 2185 | <p>Default is -1 which disables the feature. To enable it, the value |
||
| 2186 | must be greater or equal to <code>threshold</code>.</p> |
||
| 2187 | </td></tr></table> |
||
| 2188 | |||
| 2189 | </div></div> |
||
| 2190 | |||
| 2191 | </div><h3 id="Semaphore_Valve">Semaphore Valve</h3><div class="text"> |
||
| 2192 | |||
| 2193 | <div class="subsection"><h4 id="Semaphore_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2194 | |||
| 2195 | <p>The <strong>Semaphore Valve</strong> is able to limit the number of |
||
| 2196 | concurrent request processing threads.</p> |
||
| 2197 | <p><strong>org.apache.catalina.valves.SemaphoreValve</strong> provides |
||
| 2198 | methods which may be overridden by a subclass to customize behavior:</p> |
||
| 2199 | <ul> |
||
| 2200 | <li><b><code>controlConcurrency</code></b> may be overridden to add |
||
| 2201 | conditions;</li> |
||
| 2202 | <li><b><code>permitDenied</code></b> may be overridden to add error handling |
||
| 2203 | when a permit isn't granted.</li> |
||
| 2204 | </ul> |
||
| 2205 | |||
| 2206 | </div></div> |
||
| 2207 | |||
| 2208 | <div class="subsection"><h4 id="Semaphore_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2209 | |||
| 2210 | <p>The <strong>Semaphore Valve</strong> supports the following |
||
| 2211 | configuration attributes:</p> |
||
| 2212 | |||
| 2213 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2214 | Attribute |
||
| 2215 | </th><th style="width: 85%;"> |
||
| 2216 | Description |
||
| 2217 | </th></tr><tr id="Semaphore Valve_Attributes_block"><td><code class="attributeName">block</code></td><td> |
||
| 2218 | <p>Flag to determine if a thread is blocked until a permit is available. |
||
| 2219 | The default value is <strong>true</strong>.</p> |
||
| 2220 | </td></tr><tr id="Semaphore Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2221 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2222 | <strong>org.apache.catalina.valves.SemaphoreValve</strong>.</p> |
||
| 2223 | </td></tr><tr id="Semaphore Valve_Attributes_concurrency"><td><code class="attributeName">concurrency</code></td><td> |
||
| 2224 | <p>Concurrency level of the semaphore. The default value is |
||
| 2225 | <strong>10</strong>.</p> |
||
| 2226 | </td></tr><tr id="Semaphore Valve_Attributes_fairness"><td><code class="attributeName">fairness</code></td><td> |
||
| 2227 | <p>Fairness of the semaphore. The default value is |
||
| 2228 | <strong>false</strong>.</p> |
||
| 2229 | </td></tr><tr id="Semaphore Valve_Attributes_highConcurrencyStatus"><td><code class="attributeName">highConcurrencyStatus</code></td><td> |
||
| 2230 | <p>The error status code which will be returned to the client, if the |
||
| 2231 | value is positive, when a permit cannot be acquired from the |
||
| 2232 | sepmaphore. The default value is <strong>-1</strong>, which will mean |
||
| 2233 | no error status will be sent back.</p> |
||
| 2234 | </td></tr><tr id="Semaphore Valve_Attributes_interruptible"><td><code class="attributeName">interruptible</code></td><td> |
||
| 2235 | <p>Flag to determine if a thread may be interrupted until a permit is |
||
| 2236 | available. The default value is <strong>false</strong>.</p> |
||
| 2237 | </td></tr></table> |
||
| 2238 | |||
| 2239 | </div></div> |
||
| 2240 | |||
| 2241 | </div><h3 id="Health_Check_Valve">Health Check Valve</h3><div class="text"> |
||
| 2242 | |||
| 2243 | <div class="subsection"><h4 id="Health_Check_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2244 | |||
| 2245 | <p>The <strong>Health Check Valve</strong> responds to |
||
| 2246 | cloud orchestrators health checks.</p> |
||
| 2247 | </div></div> |
||
| 2248 | |||
| 2249 | <div class="subsection"><h4 id="Health_Check_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2250 | |||
| 2251 | <p>The <strong>Health Check Valve</strong> supports the |
||
| 2252 | following configuration attributes:</p> |
||
| 2253 | |||
| 2254 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2255 | Attribute |
||
| 2256 | </th><th style="width: 85%;"> |
||
| 2257 | Description |
||
| 2258 | </th></tr><tr id="Health Check Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2259 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2260 | <strong>org.apache.catalina.valves.HealthCheckValve</strong>.</p> |
||
| 2261 | </td></tr><tr id="Health Check Valve_Attributes_path"><td><code class="attributeName">path</code></td><td> |
||
| 2262 | <p>Path by the cloud orchestrators health check logic. If the valve |
||
| 2263 | is associated with a context, then this will be relative to the context |
||
| 2264 | path. Otherwise, the valve will match the full URI. |
||
| 2265 | The default value is <strong>/health</strong>.</p> |
||
| 2266 | </td></tr><tr id="Health Check Valve_Attributes_checkContainersAvailable"><td><code class="attributeName">checkContainersAvailable</code></td><td> |
||
| 2267 | <p>If <code>true</code> the valve will check if its associated |
||
| 2268 | container and all its children are available. |
||
| 2269 | The default value is <strong>true</strong>.</p> |
||
| 2270 | </td></tr></table> |
||
| 2271 | |||
| 2272 | </div></div> |
||
| 2273 | |||
| 2274 | </div><h3 id="Persistent_Valve">Persistent Valve</h3><div class="text"> |
||
| 2275 | |||
| 2276 | <div class="subsection"><h4 id="Persistent_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2277 | |||
| 2278 | <p>The <strong>PersistentValve</strong> that implements per-request session |
||
| 2279 | persistence. It is intended to be used with non-sticky load-balancers.</p> |
||
| 2280 | |||
| 2281 | </div></div> |
||
| 2282 | |||
| 2283 | <div class="subsection"><h4 id="Persistent_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2284 | |||
| 2285 | <p>The <strong>PersistentValve Valve</strong> supports the |
||
| 2286 | following configuration attributes:</p> |
||
| 2287 | |||
| 2288 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2289 | Attribute |
||
| 2290 | </th><th style="width: 85%;"> |
||
| 2291 | Description |
||
| 2292 | </th></tr><tr id="Persistent Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2293 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2294 | <strong>org.apache.catalina.valves.PersistentValve</strong>.</p> |
||
| 2295 | </td></tr><tr id="Persistent Valve_Attributes_filter"><td><code class="attributeName">filter</code></td><td> |
||
| 2296 | <p>For known file extensions or urls, you can use this filter pattern to |
||
| 2297 | notify the valve that no session required during this request. If the |
||
| 2298 | request matches this filter pattern, the valve assumes there has been no |
||
| 2299 | need to restore session. An example filter would look like <code> |
||
| 2300 | filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"</code>. |
||
| 2301 | The filter is a regular expression using |
||
| 2302 | <code>java.util.regex</code>.</p> |
||
| 2303 | </td></tr><tr id="Persistent Valve_Attributes_semaphoreAcquireUninterruptibly"><td><code class="attributeName">semaphoreAcquireUninterruptibly</code></td><td> |
||
| 2304 | <p>Flag to determine if a thread that blocks waiting for the per session |
||
| 2305 | Semaphore should do so uninterruptibly. Has no effect if |
||
| 2306 | <strong>semaphoreBlockOnAcquire</strong> is <code>false</code>. If not |
||
| 2307 | specified, the default value of <code>true</code> will be used.</p> |
||
| 2308 | </td></tr><tr id="Persistent Valve_Attributes_semaphoreBlockOnAcquire"><td><code class="attributeName">semaphoreBlockOnAcquire</code></td><td> |
||
| 2309 | <p>Flag to determine if a thread that wishes to acquire the per session |
||
| 2310 | Semaphore when it is held by another thread should block until it can |
||
| 2311 | acquire the Semaphore or if the waiting request be rejected. If not |
||
| 2312 | specified, the default value of <code>true</code> will be used.</p> |
||
| 2313 | </td></tr><tr id="Persistent Valve_Attributes_semaphoreFairness"><td><code class="attributeName">semaphoreFairness</code></td><td> |
||
| 2314 | <p>Flag to determine if the per session Semaphore will grant requests |
||
| 2315 | for the Semaphore in the same order they were received. Has no effect if |
||
| 2316 | <strong>semaphoreBlockOnAcquire</strong> is <code>false</code>. If not |
||
| 2317 | specified, the default value of <code>true</code> will be used.</p> |
||
| 2318 | </td></tr></table> |
||
| 2319 | |||
| 2320 | </div></div> |
||
| 2321 | |||
| 2322 | </div><h3 id="Parameter_Limit_Valve">Parameter Limit Valve</h3><div class="text"> |
||
| 2323 | |||
| 2324 | <div class="subsection"><h4 id="Parameter_Limit_Valve/Introduction">Introduction</h4><div class="text"> |
||
| 2325 | |||
| 2326 | <p>The <strong>Parameter Limit Valve</strong> is used to limit the number of parameters allowed in HTTP requests |
||
| 2327 | overriding the Connector's value. The valve can be configured with specific limits for certain URL patterns. |
||
| 2328 | Requests exceeding the defined parameter limits will result in an HTTP 400 Bad Request error.</p> |
||
| 2329 | |||
| 2330 | </div></div> |
||
| 2331 | |||
| 2332 | <div class="subsection"><h4 id="Parameter_Limit_Valve/Attributes">Attributes</h4><div class="text"> |
||
| 2333 | |||
| 2334 | <p>The <strong>Parameter Limit Valve</strong> supports the following |
||
| 2335 | configuration attributes:</p> |
||
| 2336 | |||
| 2337 | <table class="defaultTable"><tr><th style="width: 15%;"> |
||
| 2338 | Attribute |
||
| 2339 | </th><th style="width: 85%;"> |
||
| 2340 | Description |
||
| 2341 | </th></tr><tr id="Parameter Limit Valve_Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td> |
||
| 2342 | <p>Java class name of the implementation to use. This MUST be set to |
||
| 2343 | <strong>org.apache.catalina.valves.ParameterLimitValve</strong>.</p> |
||
| 2344 | </td></tr><tr id="Parameter Limit Valve_Attributes_resourcePath"><td><code class="attributeName">resourcePath</code></td><td> |
||
| 2345 | <p>A file consisting of line-separated URL patterns and their respective parameter limits. |
||
| 2346 | Each entry should follow the format <code>urlPattern=limit</code>. |
||
| 2347 | The valve will apply the limit defined for a URL pattern when a request matches that pattern. |
||
| 2348 | If no pattern matches, the Connector's limit will be used. |
||
| 2349 | For example: |
||
| 2350 | <code> |
||
| 2351 | /api/.*=100 |
||
| 2352 | /admin/.*=50 |
||
| 2353 | /upload/.*=30,5,1024 |
||
| 2354 | </code> |
||
| 2355 | Default value: <code>parameter_limit.config</code>. |
||
| 2356 | It must be placed in the Host configuration folder or in the WEB-INF folder of the web application. |
||
| 2357 | </p> |
||
| 2358 | <p>If a single integer is provided, it is used for <code>maxParameterCount</code>. If three integers are |
||
| 2359 | provided, they are applied to <code>maxParameterCount</code>, <code>maxPartCount</code> and |
||
| 2360 | <code>maxPartHeaderSize</code> respectively. |
||
| 2361 | </p> |
||
| 2362 | </td></tr></table> |
||
| 2363 | |||
| 2364 | </div></div> |
||
| 2365 | |||
| 2366 | </div></div></div></div></div><footer><div id="footer"> |
||
| 2367 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 2368 | <br> |
||
| 2369 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 2370 | are either registered trademarks or trademarks of the Apache Software |
||
| 2371 | Foundation. |
||
| 2372 | </div></footer></div></body></html> |