granicus.if.org Git - apache/blob - docs/manual/mod/mod_reqtimeout.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_reqtimeout.xml.meta">
  24
  25 <name>mod_reqtimeout</name>
  26 <description>Set timeout and minimum data rate for receiving requests
  27 </description>
  28 <status>Extension</status>
  29 <sourcefile>mod_reqtimeout.c</sourcefile>
  30 <identifier>reqtimeout_module</identifier>
  31
  32 <summary>
  33     <p>This module provides a convenient way to set timeouts and minimum data
  34     rates for receiving requests. Should a timeout occur or a data rate be
  35     to low, the corresponding connection will be closed by the server.</p>
  36
  37     <p>This is logged at <directive module="core">LogLevel</directive>
  38     <code>info</code>.</p>
  39
  40     <p>If needed, the <directive module="core">LogLevel</directive> directive
  41     can be tweaked to explicitly log it:</p>
  42     <highlight language="config">
  43       LogLevel reqtimeout:info
  44     </highlight>
  45 </summary>
  46
  47 <section id="examples"><title>Examples</title>
  48
  49     <ol>
  50       <li>
  51         Allow for 5 seconds to complete the TLS handshake, 10 seconds to
  52         receive the request headers and 30 seconds for receiving the
  53         request body:
  54
  55         <highlight language="config">
  56           RequestReadTimeout handshake=5 header=10 body=30
  57         </highlight>
  58       </li>
  59
  60       <li>
  61         Allow at least 10 seconds to receive the request body.
  62         If the client sends data, increase the timeout by 1 second for every
  63         1000 bytes received, with no upper limit for the timeout (except for
  64         the limit given indirectly by
  65         <directive module="core">LimitRequestBody</directive>):
  66
  67         <highlight language="config">
  68           RequestReadTimeout body=10,MinRate=1000
  69         </highlight>
  70       </li>
  71
  72       <li>
  73         Allow at least 10 seconds to receive the request headers.
  74         If the client sends data, increase the timeout by 1 second for every
  75         500 bytes received. But do not allow more than 30 seconds for the
  76         request headers:
  77
  78         <highlight language="config">
  79           RequestReadTimeout header=10-30,MinRate=500
  80         </highlight>
  81       </li>
  82
  83       <li>
  84         Usually, a server should have both header and body timeouts configured.
  85         If a common configuration is used for http and https virtual hosts, the
  86         timeouts should not be set too low:
  87
  88         <highlight language="config">
  89           RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500
  90         </highlight>
  91       </li>
  92
  93     </ol>
  94 </section>
  95
  96 <directivesynopsis>
  97 <name>RequestReadTimeout</name>
  98 <description>Set timeout values for completing the TLS handshake, receiving
  99 the request headers and/or body from client.
 100 </description>
 101 <syntax>RequestReadTimeout
 102 [handshake=<var>timeout</var>[-<var>maxtimeout</var>][,MinRate=<var>rate</var>]
 103 [header=<var>timeout</var>[-<var>maxtimeout</var>][,MinRate=<var>rate</var>]
 104 [body=<var>timeout</var>[-<var>maxtimeout</var>][,MinRate=<var>rate</var>]
 105 </syntax>
 106 <default>RequestReadTimeout handshake=0 header=20-40,MinRate=500 body=20,MinRate=500</default>
 107 <contextlist><context>server config</context><context>virtual host</context>
 108 </contextlist>
 109 <compatibility>Defaulted to disabled in version 2.3.14 and earlier. The
 110 <code>handshake</code> stage is available since version 2.4.39.
 111 </compatibility>
 112
 113 <usage>
 114     <p>This directive can set various timeouts for completing the TLS handshake,
 115     receiving the request headers and/or the request body from the client.
 116     If the client fails to complete each of these stages within the configured
 117     time, a <code>408 REQUEST TIME OUT</code> error is sent.</p>
 118
 119     <p>For SSL virtual hosts, the <code>handshake</code> timeout values is the time
 120     needed to do the initial SSL handshake.  If the user's browser is configured to
 121     query certificate revocation lists and the CRL server is not reachable, the
 122     initial SSL handshake may take a significant time until the browser gives up
 123     waiting for the CRL.  Therefore the <code>handshake</code> timeout should take
 124     this possible overhead into consideration for SSL virtual hosts (if necessary).
 125     The body timeout values include the time needed for SSL renegotiation
 126     (if necessary).</p>
 127
 128     <p>When an <directive module="core">AcceptFilter</directive> is in use
 129     (usually the case on Linux and FreeBSD), the socket is not sent to the
 130     server process before at least one byte (or the whole request for
 131     <code>httpready</code>) is received. The handshake and header timeouts
 132     configured with <directive>RequestReadTimeout</directive> are only effective
 133     after the server process has received the socket.</p>
 134
 135     <p>For each of the three timeout stages (handshake, header or body), there are
 136     three ways to specify the timeout:
 137     </p>
 138
 139     <ul>
 140
 141     <li><strong>Fixed timeout value</strong>:<br />
 142
 143     <example><var>stage</var>=<var>timeout</var></example>
 144
 145     <p>The time in seconds allowed for completing the whole stage (handshaking,
 146     reading all of the request headers or body). A value of 0 means no limit.</p>
 147     </li>
 148
 149     <li><strong>Disable module for a vhost</strong>:<br />
 150
 151     <example>handshake=0 header=0 body=0</example>
 152
 153     <p>This disables <module>mod_reqtimeout</module> completely (note that
 154     <code>handshake=0</code> is the default already and could be omitted).</p>
 155     </li>
 156
 157     <li><strong>Timeout value that is increased when data is
 158     received</strong>:<br />
 159     <example>
 160     <var>stage</var>=<var>timeout</var>,MinRate=<var>data_rate</var>
 161     </example>
 162
 163     <p>Same as above, but whenever data is received, the timeout value is
 164     increased according to the specified minimum data rate (in bytes per
 165     second).</p>
 166     </li>
 167
 168     <li><strong>Timeout value that is increased when data is received, with an
 169     upper bound</strong>:<br />
 170     <example>
 171     <var>stage</var>=<var>timeout</var>-<var>maxtimeout</var>,MinRate=<var>data_rate</var>
 172     </example>
 173
 174     <p>Same as above, but the timeout will not be increased above the second
 175     value of the specified timeout range.</p>
 176     </li>
 177
 178     </ul>
 179
 180 </usage>
 181
 182 </directivesynopsis>
 183
 184 </modulesynopsis>