Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1 | ---------------------- |
Willy Tarreau | 8317b28 | 2014-04-23 01:49:41 +0200 | [diff] [blame] | 2 | HAProxy |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3 | Configuration Manual |
| 4 | ---------------------- |
Willy Tarreau | 8317b28 | 2014-04-23 01:49:41 +0200 | [diff] [blame] | 5 | version 1.5 |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 6 | willy tarreau |
Willy Tarreau | 8860dcd | 2014-04-26 00:08:14 +0200 | [diff] [blame] | 7 | 2014/04/26 |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8 | |
| 9 | |
| 10 | This document covers the configuration language as implemented in the version |
| 11 | specified above. It does not provide any hint, example or advice. For such |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12 | documentation, please refer to the Reference Manual or the Architecture Manual. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 13 | The summary below is meant to help you search sections by name and navigate |
| 14 | through the document. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 16 | Note to documentation contributors : |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 17 | This document is formatted with 80 columns per line, with even number of |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 18 | spaces for indentation and without tabs. Please follow these rules strictly |
| 19 | so that it remains easily printable everywhere. If a line needs to be |
| 20 | printed verbatim and does not fit, please end each line with a backslash |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 21 | ('\') and continue on next line, indented by two characters. It is also |
| 22 | sometimes useful to prefix all output lines (logs, console outs) with 3 |
| 23 | closing angle brackets ('>>>') in order to help get the difference between |
| 24 | inputs and outputs when it can become ambiguous. If you add sections, |
| 25 | please update the summary below for easier searching. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 26 | |
| 27 | |
| 28 | Summary |
| 29 | ------- |
| 30 | |
| 31 | 1. Quick reminder about HTTP |
| 32 | 1.1. The HTTP transaction model |
| 33 | 1.2. HTTP request |
| 34 | 1.2.1. The Request line |
| 35 | 1.2.2. The request headers |
| 36 | 1.3. HTTP response |
| 37 | 1.3.1. The Response line |
| 38 | 1.3.2. The response headers |
| 39 | |
| 40 | 2. Configuring HAProxy |
| 41 | 2.1. Configuration file format |
| 42 | 2.2. Time format |
Patrick Mezard | 35da19c | 2010-06-12 17:02:47 +0200 | [diff] [blame] | 43 | 2.3. Examples |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 44 | |
| 45 | 3. Global parameters |
| 46 | 3.1. Process management and security |
| 47 | 3.2. Performance tuning |
| 48 | 3.3. Debugging |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 49 | 3.4. Userlists |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 50 | 3.5. Peers |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 51 | |
| 52 | 4. Proxies |
| 53 | 4.1. Proxy keywords matrix |
| 54 | 4.2. Alphabetically sorted keywords reference |
| 55 | |
Willy Tarreau | 086fbf5 | 2012-09-24 20:34:51 +0200 | [diff] [blame] | 56 | 5. Bind and Server options |
| 57 | 5.1. Bind options |
| 58 | 5.2. Server and default-server options |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 59 | |
| 60 | 6. HTTP header manipulation |
| 61 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 62 | 7. Using ACLs and fetching samples |
| 63 | 7.1. ACL basics |
| 64 | 7.1.1. Matching booleans |
| 65 | 7.1.2. Matching integers |
| 66 | 7.1.3. Matching strings |
| 67 | 7.1.4. Matching regular expressions (regexes) |
| 68 | 7.1.5. Matching arbitrary data blocks |
| 69 | 7.1.6. Matching IPv4 and IPv6 addresses |
| 70 | 7.2. Using ACLs to form conditions |
| 71 | 7.3. Fetching samples |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 72 | 7.3.1. Converters |
| 73 | 7.3.2. Fetching samples from internal states |
| 74 | 7.3.3. Fetching samples at Layer 4 |
| 75 | 7.3.4. Fetching samples at Layer 5 |
| 76 | 7.3.5. Fetching samples from buffer contents (Layer 6) |
| 77 | 7.3.6. Fetching HTTP samples (Layer 7) |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 78 | 7.4. Pre-defined ACLs |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 79 | |
| 80 | 8. Logging |
| 81 | 8.1. Log levels |
| 82 | 8.2. Log formats |
| 83 | 8.2.1. Default log format |
| 84 | 8.2.2. TCP log format |
| 85 | 8.2.3. HTTP log format |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 86 | 8.2.4. Custom log format |
Willy Tarreau | 5f51e1a | 2012-12-03 18:40:10 +0100 | [diff] [blame] | 87 | 8.2.5. Error log format |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 88 | 8.3. Advanced logging options |
| 89 | 8.3.1. Disabling logging of external tests |
| 90 | 8.3.2. Logging before waiting for the session to terminate |
| 91 | 8.3.3. Raising log level upon errors |
| 92 | 8.3.4. Disabling logging of successful connections |
| 93 | 8.4. Timing events |
| 94 | 8.5. Session state at disconnection |
| 95 | 8.6. Non-printable characters |
| 96 | 8.7. Capturing HTTP cookies |
| 97 | 8.8. Capturing HTTP headers |
| 98 | 8.9. Examples of logs |
| 99 | |
| 100 | 9. Statistics and monitoring |
| 101 | 9.1. CSV format |
| 102 | 9.2. Unix Socket commands |
| 103 | |
| 104 | |
| 105 | 1. Quick reminder about HTTP |
| 106 | ---------------------------- |
| 107 | |
| 108 | When haproxy is running in HTTP mode, both the request and the response are |
| 109 | fully analyzed and indexed, thus it becomes possible to build matching criteria |
| 110 | on almost anything found in the contents. |
| 111 | |
| 112 | However, it is important to understand how HTTP requests and responses are |
| 113 | formed, and how HAProxy decomposes them. It will then become easier to write |
| 114 | correct rules and to debug existing configurations. |
| 115 | |
| 116 | |
| 117 | 1.1. The HTTP transaction model |
| 118 | ------------------------------- |
| 119 | |
| 120 | The HTTP protocol is transaction-driven. This means that each request will lead |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 121 | to one and only one response. Traditionally, a TCP connection is established |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 122 | from the client to the server, a request is sent by the client on the |
| 123 | connection, the server responds and the connection is closed. A new request |
| 124 | will involve a new connection : |
| 125 | |
| 126 | [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ... |
| 127 | |
| 128 | In this mode, called the "HTTP close" mode, there are as many connection |
| 129 | establishments as there are HTTP transactions. Since the connection is closed |
| 130 | by the server after the response, the client does not need to know the content |
| 131 | length. |
| 132 | |
| 133 | Due to the transactional nature of the protocol, it was possible to improve it |
| 134 | to avoid closing a connection between two subsequent transactions. In this mode |
| 135 | however, it is mandatory that the server indicates the content length for each |
| 136 | response so that the client does not wait indefinitely. For this, a special |
| 137 | header is used: "Content-length". This mode is called the "keep-alive" mode : |
| 138 | |
| 139 | [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ... |
| 140 | |
| 141 | Its advantages are a reduced latency between transactions, and less processing |
| 142 | power required on the server side. It is generally better than the close mode, |
| 143 | but not always because the clients often limit their concurrent connections to |
Patrick Mezard | 9ec2ec4 | 2010-06-12 17:02:45 +0200 | [diff] [blame] | 144 | a smaller value. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 145 | |
| 146 | A last improvement in the communications is the pipelining mode. It still uses |
| 147 | keep-alive, but the client does not wait for the first response to send the |
| 148 | second request. This is useful for fetching large number of images composing a |
| 149 | page : |
| 150 | |
| 151 | [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ... |
| 152 | |
| 153 | This can obviously have a tremendous benefit on performance because the network |
| 154 | latency is eliminated between subsequent requests. Many HTTP agents do not |
| 155 | correctly support pipelining since there is no way to associate a response with |
| 156 | the corresponding request in HTTP. For this reason, it is mandatory for the |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 157 | server to reply in the exact same order as the requests were received. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 158 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 159 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 160 | connections: for each connection it processes each request and response, and |
| 161 | leaves the connection idle on both sides between the end of a response and the |
| 162 | start of a new request. |
Patrick Mezard | 9ec2ec4 | 2010-06-12 17:02:45 +0200 | [diff] [blame] | 163 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 164 | HAProxy supports 5 connection modes : |
| 165 | - keep alive : all requests and responses are processed (default) |
| 166 | - tunnel : only the first request and response are processed, |
| 167 | everything else is forwarded with no analysis. |
| 168 | - passive close : tunnel with "Connection: close" added in both directions. |
| 169 | - server close : the server-facing connection is closed after the response. |
| 170 | - forced close : the connection is actively closed after end of response. |
| 171 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 172 | |
| 173 | 1.2. HTTP request |
| 174 | ----------------- |
| 175 | |
| 176 | First, let's consider this HTTP request : |
| 177 | |
| 178 | Line Contents |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 179 | number |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 180 | 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1 |
| 181 | 2 Host: www.mydomain.com |
| 182 | 3 User-agent: my small browser |
| 183 | 4 Accept: image/jpeg, image/gif |
| 184 | 5 Accept: image/png |
| 185 | |
| 186 | |
| 187 | 1.2.1. The Request line |
| 188 | ----------------------- |
| 189 | |
| 190 | Line 1 is the "request line". It is always composed of 3 fields : |
| 191 | |
| 192 | - a METHOD : GET |
| 193 | - a URI : /serv/login.php?lang=en&profile=2 |
| 194 | - a version tag : HTTP/1.1 |
| 195 | |
| 196 | All of them are delimited by what the standard calls LWS (linear white spaces), |
| 197 | which are commonly spaces, but can also be tabs or line feeds/carriage returns |
| 198 | followed by spaces/tabs. The method itself cannot contain any colon (':') and |
| 199 | is limited to alphabetic letters. All those various combinations make it |
| 200 | desirable that HAProxy performs the splitting itself rather than leaving it to |
| 201 | the user to write a complex or inaccurate regular expression. |
| 202 | |
| 203 | The URI itself can have several forms : |
| 204 | |
| 205 | - A "relative URI" : |
| 206 | |
| 207 | /serv/login.php?lang=en&profile=2 |
| 208 | |
| 209 | It is a complete URL without the host part. This is generally what is |
| 210 | received by servers, reverse proxies and transparent proxies. |
| 211 | |
| 212 | - An "absolute URI", also called a "URL" : |
| 213 | |
| 214 | http://192.168.0.12:8080/serv/login.php?lang=en&profile=2 |
| 215 | |
| 216 | It is composed of a "scheme" (the protocol name followed by '://'), a host |
| 217 | name or address, optionally a colon (':') followed by a port number, then |
| 218 | a relative URI beginning at the first slash ('/') after the address part. |
| 219 | This is generally what proxies receive, but a server supporting HTTP/1.1 |
| 220 | must accept this form too. |
| 221 | |
| 222 | - a star ('*') : this form is only accepted in association with the OPTIONS |
| 223 | method and is not relayable. It is used to inquiry a next hop's |
| 224 | capabilities. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 225 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 226 | - an address:port combination : 192.168.0.12:80 |
| 227 | This is used with the CONNECT method, which is used to establish TCP |
| 228 | tunnels through HTTP proxies, generally for HTTPS, but sometimes for |
| 229 | other protocols too. |
| 230 | |
| 231 | In a relative URI, two sub-parts are identified. The part before the question |
| 232 | mark is called the "path". It is typically the relative path to static objects |
| 233 | on the server. The part after the question mark is called the "query string". |
| 234 | It is mostly used with GET requests sent to dynamic scripts and is very |
| 235 | specific to the language, framework or application in use. |
| 236 | |
| 237 | |
| 238 | 1.2.2. The request headers |
| 239 | -------------------------- |
| 240 | |
| 241 | The headers start at the second line. They are composed of a name at the |
| 242 | beginning of the line, immediately followed by a colon (':'). Traditionally, |
| 243 | an LWS is added after the colon but that's not required. Then come the values. |
| 244 | Multiple identical headers may be folded into one single line, delimiting the |
| 245 | values with commas, provided that their order is respected. This is commonly |
| 246 | encountered in the "Cookie:" field. A header may span over multiple lines if |
| 247 | the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5 |
| 248 | define a total of 3 values for the "Accept:" header. |
| 249 | |
| 250 | Contrary to a common mis-conception, header names are not case-sensitive, and |
| 251 | their values are not either if they refer to other header names (such as the |
| 252 | "Connection:" header). |
| 253 | |
| 254 | The end of the headers is indicated by the first empty line. People often say |
| 255 | that it's a double line feed, which is not exact, even if a double line feed |
| 256 | is one valid form of empty line. |
| 257 | |
| 258 | Fortunately, HAProxy takes care of all these complex combinations when indexing |
| 259 | headers, checking values and counting them, so there is no reason to worry |
| 260 | about the way they could be written, but it is important not to accuse an |
| 261 | application of being buggy if it does unusual, valid things. |
| 262 | |
| 263 | Important note: |
| 264 | As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks |
| 265 | in the middle of headers by LWS in order to join multi-line headers. This |
| 266 | is necessary for proper analysis and helps less capable HTTP parsers to work |
| 267 | correctly and not to be fooled by such complex constructs. |
| 268 | |
| 269 | |
| 270 | 1.3. HTTP response |
| 271 | ------------------ |
| 272 | |
| 273 | An HTTP response looks very much like an HTTP request. Both are called HTTP |
| 274 | messages. Let's consider this HTTP response : |
| 275 | |
| 276 | Line Contents |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 277 | number |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 278 | 1 HTTP/1.1 200 OK |
| 279 | 2 Content-length: 350 |
| 280 | 3 Content-Type: text/html |
| 281 | |
Willy Tarreau | 816b979 | 2009-09-15 21:25:21 +0200 | [diff] [blame] | 282 | As a special case, HTTP supports so called "Informational responses" as status |
| 283 | codes 1xx. These messages are special in that they don't convey any part of the |
| 284 | response, they're just used as sort of a signaling message to ask a client to |
Willy Tarreau | 5843d1a | 2010-02-01 15:13:32 +0100 | [diff] [blame] | 285 | continue to post its request for instance. In the case of a status 100 response |
| 286 | the requested information will be carried by the next non-100 response message |
| 287 | following the informational one. This implies that multiple responses may be |
| 288 | sent to a single request, and that this only works when keep-alive is enabled |
| 289 | (1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to |
| 290 | correctly forward and skip them, and only process the next non-100 response. As |
| 291 | such, these messages are neither logged nor transformed, unless explicitly |
| 292 | state otherwise. Status 101 messages indicate that the protocol is changing |
| 293 | over the same connection and that haproxy must switch to tunnel mode, just as |
| 294 | if a CONNECT had occurred. Then the Upgrade header would contain additional |
| 295 | information about the type of protocol the connection is switching to. |
Willy Tarreau | 816b979 | 2009-09-15 21:25:21 +0200 | [diff] [blame] | 296 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 297 | |
| 298 | 1.3.1. The Response line |
| 299 | ------------------------ |
| 300 | |
| 301 | Line 1 is the "response line". It is always composed of 3 fields : |
| 302 | |
| 303 | - a version tag : HTTP/1.1 |
| 304 | - a status code : 200 |
| 305 | - a reason : OK |
| 306 | |
| 307 | The status code is always 3-digit. The first digit indicates a general status : |
Willy Tarreau | 816b979 | 2009-09-15 21:25:21 +0200 | [diff] [blame] | 308 | - 1xx = informational message to be skipped (eg: 100, 101) |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 309 | - 2xx = OK, content is following (eg: 200, 206) |
| 310 | - 3xx = OK, no content following (eg: 302, 304) |
| 311 | - 4xx = error caused by the client (eg: 401, 403, 404) |
| 312 | - 5xx = error caused by the server (eg: 500, 502, 503) |
| 313 | |
| 314 | Please refer to RFC2616 for the detailed meaning of all such codes. The |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 315 | "reason" field is just a hint, but is not parsed by clients. Anything can be |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 316 | found there, but it's a common practice to respect the well-established |
| 317 | messages. It can be composed of one or multiple words, such as "OK", "Found", |
| 318 | or "Authentication Required". |
| 319 | |
| 320 | Haproxy may emit the following status codes by itself : |
| 321 | |
| 322 | Code When / reason |
| 323 | 200 access to stats page, and when replying to monitoring requests |
| 324 | 301 when performing a redirection, depending on the configured code |
| 325 | 302 when performing a redirection, depending on the configured code |
| 326 | 303 when performing a redirection, depending on the configured code |
Willy Tarreau | b67fdc4 | 2013-03-29 19:28:11 +0100 | [diff] [blame] | 327 | 307 when performing a redirection, depending on the configured code |
| 328 | 308 when performing a redirection, depending on the configured code |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 329 | 400 for an invalid or too large request |
| 330 | 401 when an authentication is required to perform the action (when |
| 331 | accessing the stats page) |
| 332 | 403 when a request is forbidden by a "block" ACL or "reqdeny" filter |
| 333 | 408 when the request timeout strikes before the request is complete |
| 334 | 500 when haproxy encounters an unrecoverable internal error, such as a |
| 335 | memory allocation failure, which should never happen |
| 336 | 502 when the server returns an empty, invalid or incomplete response, or |
| 337 | when an "rspdeny" filter blocks the response. |
| 338 | 503 when no server was available to handle the request, or in response to |
| 339 | monitoring requests which match the "monitor fail" condition |
| 340 | 504 when the response timeout strikes before the server responds |
| 341 | |
| 342 | The error 4xx and 5xx codes above may be customized (see "errorloc" in section |
| 343 | 4.2). |
| 344 | |
| 345 | |
| 346 | 1.3.2. The response headers |
| 347 | --------------------------- |
| 348 | |
| 349 | Response headers work exactly like request headers, and as such, HAProxy uses |
| 350 | the same parsing function for both. Please refer to paragraph 1.2.2 for more |
| 351 | details. |
| 352 | |
| 353 | |
| 354 | 2. Configuring HAProxy |
| 355 | ---------------------- |
| 356 | |
| 357 | 2.1. Configuration file format |
| 358 | ------------------------------ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 359 | |
| 360 | HAProxy's configuration process involves 3 major sources of parameters : |
| 361 | |
| 362 | - the arguments from the command-line, which always take precedence |
| 363 | - the "global" section, which sets process-wide parameters |
| 364 | - the proxies sections which can take form of "defaults", "listen", |
| 365 | "frontend" and "backend". |
| 366 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 367 | The configuration file syntax consists in lines beginning with a keyword |
| 368 | referenced in this manual, optionally followed by one or several parameters |
| 369 | delimited by spaces. If spaces have to be entered in strings, then they must be |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 370 | preceded by a backslash ('\') to be escaped. Backslashes also have to be |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 371 | escaped by doubling them. |
| 372 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 373 | |
| 374 | 2.2. Time format |
| 375 | ---------------- |
| 376 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 377 | Some parameters involve values representing time, such as timeouts. These |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 378 | values are generally expressed in milliseconds (unless explicitly stated |
| 379 | otherwise) but may be expressed in any other unit by suffixing the unit to the |
| 380 | numeric value. It is important to consider this because it will not be repeated |
| 381 | for every keyword. Supported units are : |
| 382 | |
| 383 | - us : microseconds. 1 microsecond = 1/1000000 second |
| 384 | - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default. |
| 385 | - s : seconds. 1s = 1000ms |
| 386 | - m : minutes. 1m = 60s = 60000ms |
| 387 | - h : hours. 1h = 60m = 3600s = 3600000ms |
| 388 | - d : days. 1d = 24h = 1440m = 86400s = 86400000ms |
| 389 | |
| 390 | |
Patrick Mezard | 35da19c | 2010-06-12 17:02:47 +0200 | [diff] [blame] | 391 | 2.3. Examples |
| 392 | ------------- |
| 393 | |
| 394 | # Simple configuration for an HTTP proxy listening on port 80 on all |
| 395 | # interfaces and forwarding requests to a single backend "servers" with a |
| 396 | # single server "server1" listening on 127.0.0.1:8000 |
| 397 | global |
| 398 | daemon |
| 399 | maxconn 256 |
| 400 | |
| 401 | defaults |
| 402 | mode http |
| 403 | timeout connect 5000ms |
| 404 | timeout client 50000ms |
| 405 | timeout server 50000ms |
| 406 | |
| 407 | frontend http-in |
| 408 | bind *:80 |
| 409 | default_backend servers |
| 410 | |
| 411 | backend servers |
| 412 | server server1 127.0.0.1:8000 maxconn 32 |
| 413 | |
| 414 | |
| 415 | # The same configuration defined with a single listen block. Shorter but |
| 416 | # less expressive, especially in HTTP mode. |
| 417 | global |
| 418 | daemon |
| 419 | maxconn 256 |
| 420 | |
| 421 | defaults |
| 422 | mode http |
| 423 | timeout connect 5000ms |
| 424 | timeout client 50000ms |
| 425 | timeout server 50000ms |
| 426 | |
| 427 | listen http-in |
| 428 | bind *:80 |
| 429 | server server1 127.0.0.1:8000 maxconn 32 |
| 430 | |
| 431 | |
| 432 | Assuming haproxy is in $PATH, test these configurations in a shell with: |
| 433 | |
Willy Tarreau | ccb289d | 2010-12-11 20:19:38 +0100 | [diff] [blame] | 434 | $ sudo haproxy -f configuration.conf -c |
Patrick Mezard | 35da19c | 2010-06-12 17:02:47 +0200 | [diff] [blame] | 435 | |
| 436 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 437 | 3. Global parameters |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 438 | -------------------- |
| 439 | |
| 440 | Parameters in the "global" section are process-wide and often OS-specific. They |
| 441 | are generally set once for all and do not need being changed once correct. Some |
| 442 | of them have command-line equivalents. |
| 443 | |
| 444 | The following keywords are supported in the "global" section : |
| 445 | |
| 446 | * Process management and security |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 447 | - ca-base |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 448 | - chroot |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 449 | - crt-base |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 450 | - daemon |
| 451 | - gid |
| 452 | - group |
| 453 | - log |
Joe Williams | df5b38f | 2010-12-29 17:05:48 +0100 | [diff] [blame] | 454 | - log-send-hostname |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 455 | - nbproc |
| 456 | - pidfile |
| 457 | - uid |
| 458 | - ulimit-n |
| 459 | - user |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 460 | - stats |
Emeric Brun | 850efd5 | 2014-01-29 12:24:34 +0100 | [diff] [blame] | 461 | - ssl-server-verify |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 462 | - node |
| 463 | - description |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 464 | - unix-bind |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 465 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 466 | * Performance tuning |
Willy Tarreau | 1746eec | 2014-04-25 10:46:47 +0200 | [diff] [blame] | 467 | - max-spread-checks |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 468 | - maxconn |
Willy Tarreau | 81c25d0 | 2011-09-07 15:17:21 +0200 | [diff] [blame] | 469 | - maxconnrate |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 470 | - maxcomprate |
William Lallemand | 072a2bf | 2012-11-20 17:01:01 +0100 | [diff] [blame] | 471 | - maxcompcpuusage |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 472 | - maxpipes |
Willy Tarreau | 93e7c00 | 2013-10-07 18:51:07 +0200 | [diff] [blame] | 473 | - maxsessrate |
Willy Tarreau | 403edff | 2012-09-06 11:58:37 +0200 | [diff] [blame] | 474 | - maxsslconn |
Willy Tarreau | e43d532 | 2013-10-07 20:01:52 +0200 | [diff] [blame] | 475 | - maxsslrate |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 476 | - noepoll |
| 477 | - nokqueue |
| 478 | - nopoll |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 479 | - nosplice |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 480 | - nogetaddrinfo |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 481 | - spread-checks |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 482 | - tune.bufsize |
Willy Tarreau | 43961d5 | 2010-10-04 20:39:20 +0200 | [diff] [blame] | 483 | - tune.chksize |
William Lallemand | f374783 | 2012-11-09 12:33:10 +0100 | [diff] [blame] | 484 | - tune.comp.maxlevel |
Willy Tarreau | 193b8c6 | 2012-11-22 00:17:38 +0100 | [diff] [blame] | 485 | - tune.http.cookielen |
Willy Tarreau | ac1932d | 2011-10-24 19:14:41 +0200 | [diff] [blame] | 486 | - tune.http.maxhdr |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 487 | - tune.idletimer |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 488 | - tune.maxaccept |
| 489 | - tune.maxpollevents |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 490 | - tune.maxrewrite |
Willy Tarreau | bd9a0a7 | 2011-10-23 21:14:29 +0200 | [diff] [blame] | 491 | - tune.pipesize |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 492 | - tune.rcvbuf.client |
| 493 | - tune.rcvbuf.server |
| 494 | - tune.sndbuf.client |
| 495 | - tune.sndbuf.server |
Willy Tarreau | 6ec58db | 2012-11-16 16:32:15 +0100 | [diff] [blame] | 496 | - tune.ssl.cachesize |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 497 | - tune.ssl.lifetime |
Emeric Brun | 8dc6039 | 2014-05-09 13:52:00 +0200 | [diff] [blame] | 498 | - tune.ssl.force-private-cache |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 499 | - tune.ssl.maxrecord |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 500 | - tune.zlib.memlevel |
| 501 | - tune.zlib.windowsize |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 502 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 503 | * Debugging |
| 504 | - debug |
| 505 | - quiet |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 506 | |
| 507 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 508 | 3.1. Process management and security |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 509 | ------------------------------------ |
| 510 | |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 511 | ca-base <dir> |
| 512 | Assigns a default directory to fetch SSL CA certificates and CRLs from when a |
Emeric Brun | fd33a26 | 2012-10-11 16:28:27 +0200 | [diff] [blame] | 513 | relative path is used with "ca-file" or "crl-file" directives. Absolute |
| 514 | locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base". |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 515 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 516 | chroot <jail dir> |
| 517 | Changes current directory to <jail dir> and performs a chroot() there before |
| 518 | dropping privileges. This increases the security level in case an unknown |
| 519 | vulnerability would be exploited, since it would make it very hard for the |
| 520 | attacker to exploit the system. This only works when the process is started |
| 521 | with superuser privileges. It is important to ensure that <jail_dir> is both |
| 522 | empty and unwritable to anyone. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 523 | |
Willy Tarreau | fc6c032 | 2012-11-16 16:12:27 +0100 | [diff] [blame] | 524 | cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>... |
| 525 | On Linux 2.6 and above, it is possible to bind a process to a specific CPU |
| 526 | set. This means that the process will never run on other CPUs. The "cpu-map" |
| 527 | directive specifies CPU sets for process sets. The first argument is the |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 528 | process number to bind. This process must have a number between 1 and 32 or |
| 529 | 64, depending on the machine's word size, and any process IDs above nbproc |
| 530 | are ignored. It is possible to specify all processes at once using "all", |
| 531 | only odd numbers using "odd" or even numbers using "even", just like with the |
| 532 | "bind-process" directive. The second and forthcoming arguments are CPU sets. |
| 533 | Each CPU set is either a unique number between 0 and 31 or 63 or a range with |
| 534 | two such numbers delimited by a dash ('-'). Multiple CPU numbers or ranges |
| 535 | may be specified, and the processes will be allowed to bind to all of them. |
| 536 | Obviously, multiple "cpu-map" directives may be specified. Each "cpu-map" |
| 537 | directive will replace the previous ones when they overlap. |
Willy Tarreau | fc6c032 | 2012-11-16 16:12:27 +0100 | [diff] [blame] | 538 | |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 539 | crt-base <dir> |
| 540 | Assigns a default directory to fetch SSL certificates from when a relative |
| 541 | path is used with "crtfile" directives. Absolute locations specified after |
| 542 | "crtfile" prevail and ignore "crt-base". |
| 543 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 544 | daemon |
| 545 | Makes the process fork into background. This is the recommended mode of |
| 546 | operation. It is equivalent to the command line "-D" argument. It can be |
| 547 | disabled by the command line "-db" argument. |
| 548 | |
| 549 | gid <number> |
| 550 | Changes the process' group ID to <number>. It is recommended that the group |
| 551 | ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 552 | be started with a user belonging to this group, or with superuser privileges. |
Michael Scherer | ab012dd | 2013-01-12 18:35:19 +0100 | [diff] [blame] | 553 | Note that if haproxy is started from a user having supplementary groups, it |
| 554 | will only be able to drop these groups if started with superuser privileges. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 555 | See also "group" and "uid". |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 556 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 557 | group <group name> |
| 558 | Similar to "gid" but uses the GID of group name <group name> from /etc/group. |
| 559 | See also "gid" and "user". |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 560 | |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 561 | log <address> <facility> [max level [min level]] |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 562 | Adds a global syslog server. Up to two global servers can be defined. They |
| 563 | will receive logs for startups and exits, as well as all logs from proxies |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 564 | configured with "log global". |
| 565 | |
| 566 | <address> can be one of: |
| 567 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 568 | - An IPv4 address optionally followed by a colon and a UDP port. If |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 569 | no port is specified, 514 is used by default (the standard syslog |
| 570 | port). |
| 571 | |
David du Colombier | 24bb5f5 | 2011-03-17 10:40:23 +0100 | [diff] [blame] | 572 | - An IPv6 address followed by a colon and optionally a UDP port. If |
| 573 | no port is specified, 514 is used by default (the standard syslog |
| 574 | port). |
| 575 | |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 576 | - A filesystem path to a UNIX domain socket, keeping in mind |
| 577 | considerations for chroot (be sure the path is accessible inside |
| 578 | the chroot) and uid/gid (be sure the path is appropriately |
| 579 | writeable). |
| 580 | |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 581 | Any part of the address string may reference any number of environment |
| 582 | variables by preceding their name with a dollar sign ('$') and |
| 583 | optionally enclosing them with braces ('{}'), similarly to what is done |
| 584 | in Bourne shell. |
| 585 | |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 586 | <facility> must be one of the 24 standard syslog facilities : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 587 | |
| 588 | kern user mail daemon auth syslog lpr news |
| 589 | uucp cron auth2 ftp ntp audit alert cron2 |
| 590 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 591 | |
| 592 | An optional level can be specified to filter outgoing messages. By default, |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 593 | all messages are sent. If a maximum level is specified, only messages with a |
| 594 | severity at least as important as this level will be sent. An optional minimum |
| 595 | level can be specified. If it is set, logs emitted with a more severe level |
| 596 | than this one will be capped to this level. This is used to avoid sending |
| 597 | "emerg" messages on all terminals on some default syslog configurations. |
| 598 | Eight levels are known : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 599 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 600 | emerg alert crit err warning notice info debug |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 601 | |
Joe Williams | df5b38f | 2010-12-29 17:05:48 +0100 | [diff] [blame] | 602 | log-send-hostname [<string>] |
| 603 | Sets the hostname field in the syslog header. If optional "string" parameter |
| 604 | is set the header is set to the string contents, otherwise uses the hostname |
| 605 | of the system. Generally used if one is not relaying logs through an |
| 606 | intermediate syslog server or for simply customizing the hostname printed in |
| 607 | the logs. |
| 608 | |
Kevinm | 48936af | 2010-12-22 16:08:21 +0000 | [diff] [blame] | 609 | log-tag <string> |
| 610 | Sets the tag field in the syslog header to this string. It defaults to the |
| 611 | program name as launched from the command line, which usually is "haproxy". |
| 612 | Sometimes it can be useful to differentiate between multiple processes |
| 613 | running on the same host. |
| 614 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 615 | nbproc <number> |
| 616 | Creates <number> processes when going daemon. This requires the "daemon" |
| 617 | mode. By default, only one process is created, which is the recommended mode |
| 618 | of operation. For systems limited to small sets of file descriptors per |
| 619 | process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES |
| 620 | IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon". |
| 621 | |
| 622 | pidfile <pidfile> |
| 623 | Writes pids of all daemons into file <pidfile>. This option is equivalent to |
| 624 | the "-p" command line argument. The file must be accessible to the user |
| 625 | starting the process. See also "daemon". |
| 626 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 627 | stats bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ... |
Willy Tarreau | 35b7b16 | 2012-10-22 23:17:18 +0200 | [diff] [blame] | 628 | Limits the stats socket to a certain set of processes numbers. By default the |
| 629 | stats socket is bound to all processes, causing a warning to be emitted when |
| 630 | nbproc is greater than 1 because there is no way to select the target process |
| 631 | when connecting. However, by using this setting, it becomes possible to pin |
| 632 | the stats socket to a specific set of processes, typically the first one. The |
| 633 | warning will automatically be disabled when this setting is used, whatever |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 634 | the number of processes used. The maximum process ID depends on the machine's |
Willy Tarreau | ae30253 | 2014-05-07 19:22:24 +0200 | [diff] [blame] | 635 | word size (32 or 64). A better option consists in using the "process" setting |
| 636 | of the "stats socket" line to force the process on each line. |
Willy Tarreau | 35b7b16 | 2012-10-22 23:17:18 +0200 | [diff] [blame] | 637 | |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 638 | ssl-default-bind-ciphers <ciphers> |
| 639 | This setting is only available when support for OpenSSL was built in. It sets |
| 640 | the default string describing the list of cipher algorithms ("cipher suite") |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 641 | that are negotiated during the SSL/TLS handshake for all "bind" lines which |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 642 | do not explicitly define theirs. The format of the string is defined in |
| 643 | "man 1 ciphers" from OpenSSL man pages, and can be for instance a string such |
| 644 | as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). Please check the |
| 645 | "bind" keyword for more information. |
| 646 | |
| 647 | ssl-default-server-ciphers <ciphers> |
| 648 | This setting is only available when support for OpenSSL was built in. It |
| 649 | sets the default string describing the list of cipher algorithms that are |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 650 | negotiated during the SSL/TLS handshake with the server, for all "server" |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 651 | lines which do not explicitly define theirs. The format of the string is |
| 652 | defined in "man 1 ciphers". Please check the "server" keyword for more |
| 653 | information. |
| 654 | |
Emeric Brun | 850efd5 | 2014-01-29 12:24:34 +0100 | [diff] [blame] | 655 | ssl-server-verify [none|required] |
| 656 | The default behavior for SSL verify on servers side. If specified to 'none', |
| 657 | servers certificates are not verified. The default is 'required' except if |
| 658 | forced using cmdline option '-dV'. |
| 659 | |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 660 | stats socket [<address:port>|<path>] [param*] |
| 661 | Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>. |
| 662 | Connections to this socket will return various statistics outputs and even |
| 663 | allow some commands to be issued to change some runtime settings. Please |
| 664 | consult section 9.2 "Unix Socket commands" for more details. |
Willy Tarreau | 6162db2 | 2009-10-10 17:13:00 +0200 | [diff] [blame] | 665 | |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 666 | All parameters supported by "bind" lines are supported, for instance to |
| 667 | restrict access to some users or their access rights. Please consult |
| 668 | section 5.1 for more information. |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 669 | |
| 670 | stats timeout <timeout, in milliseconds> |
| 671 | The default timeout on the stats socket is set to 10 seconds. It is possible |
| 672 | to change this value with "stats timeout". The value must be passed in |
Willy Tarreau | befdff1 | 2007-12-02 22:27:38 +0100 | [diff] [blame] | 673 | milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }. |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 674 | |
| 675 | stats maxconn <connections> |
| 676 | By default, the stats socket is limited to 10 concurrent connections. It is |
| 677 | possible to change this value with "stats maxconn". |
| 678 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 679 | uid <number> |
| 680 | Changes the process' user ID to <number>. It is recommended that the user ID |
| 681 | is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 682 | be started with superuser privileges in order to be able to switch to another |
| 683 | one. See also "gid" and "user". |
| 684 | |
| 685 | ulimit-n <number> |
| 686 | Sets the maximum number of per-process file-descriptors to <number>. By |
| 687 | default, it is automatically computed, so it is recommended not to use this |
| 688 | option. |
| 689 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 690 | unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] |
| 691 | [ group <group> ] [ gid <gid> ] |
| 692 | |
| 693 | Fixes common settings to UNIX listening sockets declared in "bind" statements. |
| 694 | This is mainly used to simplify declaration of those UNIX sockets and reduce |
| 695 | the risk of errors, since those settings are most commonly required but are |
| 696 | also process-specific. The <prefix> setting can be used to force all socket |
| 697 | path to be relative to that directory. This might be needed to access another |
| 698 | component's chroot. Note that those paths are resolved before haproxy chroots |
| 699 | itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid> |
| 700 | all have the same meaning as their homonyms used by the "bind" statement. If |
| 701 | both are specified, the "bind" statement has priority, meaning that the |
| 702 | "unix-bind" settings may be seen as process-wide default settings. |
| 703 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 704 | user <user name> |
| 705 | Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. |
| 706 | See also "uid" and "group". |
| 707 | |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 708 | node <name> |
| 709 | Only letters, digits, hyphen and underscore are allowed, like in DNS names. |
| 710 | |
| 711 | This statement is useful in HA configurations where two or more processes or |
| 712 | servers share the same IP address. By setting a different node-name on all |
| 713 | nodes, it becomes easy to immediately spot what server is handling the |
| 714 | traffic. |
| 715 | |
| 716 | description <text> |
| 717 | Add a text that describes the instance. |
| 718 | |
| 719 | Please note that it is required to escape certain characters (# for example) |
| 720 | and this text is inserted into a html page so you should avoid using |
| 721 | "<" and ">" characters. |
| 722 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 723 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 724 | 3.2. Performance tuning |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 725 | ----------------------- |
| 726 | |
Willy Tarreau | 1746eec | 2014-04-25 10:46:47 +0200 | [diff] [blame] | 727 | max-spread-checks <delay in milliseconds> |
| 728 | By default, haproxy tries to spread the start of health checks across the |
| 729 | smallest health check interval of all the servers in a farm. The principle is |
| 730 | to avoid hammering services running on the same server. But when using large |
| 731 | check intervals (10 seconds or more), the last servers in the farm take some |
| 732 | time before starting to be tested, which can be a problem. This parameter is |
| 733 | used to enforce an upper bound on delay between the first and the last check, |
| 734 | even if the servers' check intervals are larger. When servers run with |
| 735 | shorter intervals, their intervals will be respected though. |
| 736 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 737 | maxconn <number> |
| 738 | Sets the maximum per-process number of concurrent connections to <number>. It |
| 739 | is equivalent to the command-line argument "-n". Proxies will stop accepting |
| 740 | connections when this limit is reached. The "ulimit-n" parameter is |
| 741 | automatically adjusted according to this value. See also "ulimit-n". |
| 742 | |
Willy Tarreau | 81c25d0 | 2011-09-07 15:17:21 +0200 | [diff] [blame] | 743 | maxconnrate <number> |
| 744 | Sets the maximum per-process number of connections per second to <number>. |
| 745 | Proxies will stop accepting connections when this limit is reached. It can be |
| 746 | used to limit the global capacity regardless of each frontend capacity. It is |
| 747 | important to note that this can only be used as a service protection measure, |
| 748 | as there will not necessarily be a fair share between frontends when the |
| 749 | limit is reached, so it's a good idea to also limit each frontend to some |
| 750 | value close to its expected share. Also, lowering tune.maxaccept can improve |
| 751 | fairness. |
| 752 | |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 753 | maxcomprate <number> |
| 754 | Sets the maximum per-process input compression rate to <number> kilobytes |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 755 | per second. For each session, if the maximum is reached, the compression |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 756 | level will be decreased during the session. If the maximum is reached at the |
| 757 | beginning of a session, the session will not compress at all. If the maximum |
| 758 | is not reached, the compression level will be increased up to |
| 759 | tune.comp.maxlevel. A value of zero means there is no limit, this is the |
| 760 | default value. |
| 761 | |
William Lallemand | 072a2bf | 2012-11-20 17:01:01 +0100 | [diff] [blame] | 762 | maxcompcpuusage <number> |
| 763 | Sets the maximum CPU usage HAProxy can reach before stopping the compression |
| 764 | for new requests or decreasing the compression level of current requests. |
| 765 | It works like 'maxcomprate' but measures CPU usage instead of incoming data |
| 766 | bandwidth. The value is expressed in percent of the CPU used by haproxy. In |
| 767 | case of multiple processes (nbproc > 1), each process manages its individual |
| 768 | usage. A value of 100 disable the limit. The default value is 100. Setting |
| 769 | a lower value will prevent the compression work from slowing the whole |
| 770 | process down and from introducing high latencies. |
| 771 | |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 772 | maxpipes <number> |
| 773 | Sets the maximum per-process number of pipes to <number>. Currently, pipes |
| 774 | are only used by kernel-based tcp splicing. Since a pipe contains two file |
| 775 | descriptors, the "ulimit-n" value will be increased accordingly. The default |
| 776 | value is maxconn/4, which seems to be more than enough for most heavy usages. |
| 777 | The splice code dynamically allocates and releases pipes, and can fall back |
| 778 | to standard copy, so setting this value too low may only impact performance. |
| 779 | |
Willy Tarreau | 93e7c00 | 2013-10-07 18:51:07 +0200 | [diff] [blame] | 780 | maxsessrate <number> |
| 781 | Sets the maximum per-process number of sessions per second to <number>. |
| 782 | Proxies will stop accepting connections when this limit is reached. It can be |
| 783 | used to limit the global capacity regardless of each frontend capacity. It is |
| 784 | important to note that this can only be used as a service protection measure, |
| 785 | as there will not necessarily be a fair share between frontends when the |
| 786 | limit is reached, so it's a good idea to also limit each frontend to some |
| 787 | value close to its expected share. Also, lowering tune.maxaccept can improve |
| 788 | fairness. |
| 789 | |
Willy Tarreau | 403edff | 2012-09-06 11:58:37 +0200 | [diff] [blame] | 790 | maxsslconn <number> |
| 791 | Sets the maximum per-process number of concurrent SSL connections to |
| 792 | <number>. By default there is no SSL-specific limit, which means that the |
| 793 | global maxconn setting will apply to all connections. Setting this limit |
| 794 | avoids having openssl use too much memory and crash when malloc returns NULL |
| 795 | (since it unfortunately does not reliably check for such conditions). Note |
| 796 | that the limit applies both to incoming and outgoing connections, so one |
| 797 | connection which is deciphered then ciphered accounts for 2 SSL connections. |
| 798 | |
Willy Tarreau | e43d532 | 2013-10-07 20:01:52 +0200 | [diff] [blame] | 799 | maxsslrate <number> |
| 800 | Sets the maximum per-process number of SSL sessions per second to <number>. |
| 801 | SSL listeners will stop accepting connections when this limit is reached. It |
| 802 | can be used to limit the global SSL CPU usage regardless of each frontend |
| 803 | capacity. It is important to note that this can only be used as a service |
| 804 | protection measure, as there will not necessarily be a fair share between |
| 805 | frontends when the limit is reached, so it's a good idea to also limit each |
| 806 | frontend to some value close to its expected share. It is also important to |
| 807 | note that the sessions are accounted before they enter the SSL stack and not |
| 808 | after, which also protects the stack against bad handshakes. Also, lowering |
| 809 | tune.maxaccept can improve fairness. |
| 810 | |
William Lallemand | 9d5f548 | 2012-11-07 16:12:57 +0100 | [diff] [blame] | 811 | maxzlibmem <number> |
| 812 | Sets the maximum amount of RAM in megabytes per process usable by the zlib. |
| 813 | When the maximum amount is reached, future sessions will not compress as long |
| 814 | as RAM is unavailable. When sets to 0, there is no limit. |
William Lallemand | e3a7d99 | 2012-11-20 11:25:20 +0100 | [diff] [blame] | 815 | The default value is 0. The value is available in bytes on the UNIX socket |
| 816 | with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is |
| 817 | "ZlibMemUsage" in bytes. |
| 818 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 819 | noepoll |
| 820 | Disables the use of the "epoll" event polling system on Linux. It is |
| 821 | equivalent to the command-line argument "-de". The next polling system |
Willy Tarreau | e9f49e7 | 2012-11-11 17:42:00 +0100 | [diff] [blame] | 822 | used will generally be "poll". See also "nopoll". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 823 | |
| 824 | nokqueue |
| 825 | Disables the use of the "kqueue" event polling system on BSD. It is |
| 826 | equivalent to the command-line argument "-dk". The next polling system |
| 827 | used will generally be "poll". See also "nopoll". |
| 828 | |
| 829 | nopoll |
| 830 | Disables the use of the "poll" event polling system. It is equivalent to the |
| 831 | command-line argument "-dp". The next polling system used will be "select". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 832 | It should never be needed to disable "poll" since it's available on all |
Willy Tarreau | e9f49e7 | 2012-11-11 17:42:00 +0100 | [diff] [blame] | 833 | platforms supported by HAProxy. See also "nokqueue" and "noepoll". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 834 | |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 835 | nosplice |
| 836 | Disables the use of kernel tcp splicing between sockets on Linux. It is |
| 837 | equivalent to the command line argument "-dS". Data will then be copied |
| 838 | using conventional and more portable recv/send calls. Kernel tcp splicing is |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 839 | limited to some very recent instances of kernel 2.6. Most versions between |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 840 | 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not |
| 841 | be used. This option makes it easier to globally disable kernel splicing in |
| 842 | case of doubt. See also "option splice-auto", "option splice-request" and |
| 843 | "option splice-response". |
| 844 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 845 | nogetaddrinfo |
| 846 | Disables the use of getaddrinfo(3) for name resolving. It is equivalent to |
| 847 | the command line argument "-dG". Deprecated gethostbyname(3) will be used. |
| 848 | |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 849 | spread-checks <0..50, in percent> |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 850 | Sometimes it is desirable to avoid sending agent and health checks to |
| 851 | servers at exact intervals, for instance when many logical servers are |
| 852 | located on the same physical server. With the help of this parameter, it |
| 853 | becomes possible to add some randomness in the check interval between 0 |
| 854 | and +/- 50%. A value between 2 and 5 seems to show good results. The |
| 855 | default value remains at 0. |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 856 | |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 857 | tune.bufsize <number> |
| 858 | Sets the buffer size to this size (in bytes). Lower values allow more |
| 859 | sessions to coexist in the same amount of RAM, and higher values allow some |
| 860 | applications with very large cookies to work. The default value is 16384 and |
| 861 | can be changed at build time. It is strongly recommended not to change this |
| 862 | from the default value, as very low values will break some services such as |
| 863 | statistics, and values larger than default size will increase memory usage, |
| 864 | possibly causing the system to run out of memory. At least the global maxconn |
| 865 | parameter should be decreased by the same factor as this one is increased. |
Dmitry Sivachenko | f6f4f7b | 2012-10-21 18:10:25 +0400 | [diff] [blame] | 866 | If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will |
| 867 | return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger |
| 868 | than this size, haproxy will return HTTP 502 (Bad Gateway). |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 869 | |
Willy Tarreau | 43961d5 | 2010-10-04 20:39:20 +0200 | [diff] [blame] | 870 | tune.chksize <number> |
| 871 | Sets the check buffer size to this size (in bytes). Higher values may help |
| 872 | find string or regex patterns in very large pages, though doing so may imply |
| 873 | more memory and CPU usage. The default value is 16384 and can be changed at |
| 874 | build time. It is not recommended to change this value, but to use better |
| 875 | checks whenever possible. |
| 876 | |
William Lallemand | f374783 | 2012-11-09 12:33:10 +0100 | [diff] [blame] | 877 | tune.comp.maxlevel <number> |
| 878 | Sets the maximum compression level. The compression level affects CPU |
| 879 | usage during compression. This value affects CPU usage during compression. |
| 880 | Each session using compression initializes the compression algorithm with |
| 881 | this value. The default value is 1. |
| 882 | |
Willy Tarreau | 193b8c6 | 2012-11-22 00:17:38 +0100 | [diff] [blame] | 883 | tune.http.cookielen <number> |
| 884 | Sets the maximum length of captured cookies. This is the maximum value that |
| 885 | the "capture cookie xxx len yyy" will be allowed to take, and any upper value |
| 886 | will automatically be truncated to this one. It is important not to set too |
| 887 | high a value because all cookie captures still allocate this size whatever |
| 888 | their configured value (they share a same pool). This value is per request |
| 889 | per response, so the memory allocated is twice this value per connection. |
| 890 | When not specified, the limit is set to 63 characters. It is recommended not |
| 891 | to change this value. |
| 892 | |
Willy Tarreau | ac1932d | 2011-10-24 19:14:41 +0200 | [diff] [blame] | 893 | tune.http.maxhdr <number> |
| 894 | Sets the maximum number of headers in a request. When a request comes with a |
| 895 | number of headers greater than this value (including the first line), it is |
| 896 | rejected with a "400 Bad Request" status code. Similarly, too large responses |
| 897 | are blocked with "502 Bad Gateway". The default value is 101, which is enough |
| 898 | for all usages, considering that the widely deployed Apache server uses the |
| 899 | same limit. It can be useful to push this limit further to temporarily allow |
| 900 | a buggy application to work by the time it gets fixed. Keep in mind that each |
| 901 | new header consumes 32bits of memory for each session, so don't push this |
| 902 | limit too high. |
| 903 | |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 904 | tune.idletimer <timeout> |
| 905 | Sets the duration after which haproxy will consider that an empty buffer is |
| 906 | probably associated with an idle stream. This is used to optimally adjust |
| 907 | some packet sizes while forwarding large and small data alternatively. The |
| 908 | decision to use splice() or to send large buffers in SSL is modulated by this |
| 909 | parameter. The value is in milliseconds between 0 and 65535. A value of zero |
| 910 | means that haproxy will not try to detect idle streams. The default is 1000, |
| 911 | which seems to correctly detect end user pauses (eg: read a page before |
| 912 | clicking). There should be not reason for changing this value. Please check |
| 913 | tune.ssl.maxrecord below. |
| 914 | |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 915 | tune.maxaccept <number> |
Willy Tarreau | 16a2147 | 2012-11-19 12:39:59 +0100 | [diff] [blame] | 916 | Sets the maximum number of consecutive connections a process may accept in a |
| 917 | row before switching to other work. In single process mode, higher numbers |
| 918 | give better performance at high connection rates. However in multi-process |
| 919 | modes, keeping a bit of fairness between processes generally is better to |
| 920 | increase performance. This value applies individually to each listener, so |
| 921 | that the number of processes a listener is bound to is taken into account. |
| 922 | This value defaults to 64. In multi-process mode, it is divided by twice |
| 923 | the number of processes the listener is bound to. Setting this value to -1 |
| 924 | completely disables the limitation. It should normally not be needed to tweak |
| 925 | this value. |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 926 | |
| 927 | tune.maxpollevents <number> |
| 928 | Sets the maximum amount of events that can be processed at once in a call to |
| 929 | the polling system. The default value is adapted to the operating system. It |
| 930 | has been noticed that reducing it below 200 tends to slightly decrease |
| 931 | latency at the expense of network bandwidth, and increasing it above 200 |
| 932 | tends to trade latency for slightly increased bandwidth. |
| 933 | |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 934 | tune.maxrewrite <number> |
| 935 | Sets the reserved buffer space to this size in bytes. The reserved space is |
| 936 | used for header rewriting or appending. The first reads on sockets will never |
| 937 | fill more than bufsize-maxrewrite. Historically it has defaulted to half of |
| 938 | bufsize, though that does not make much sense since there are rarely large |
| 939 | numbers of headers to add. Setting it too high prevents processing of large |
| 940 | requests or responses. Setting it too low prevents addition of new headers |
| 941 | to already large requests or to POST requests. It is generally wise to set it |
| 942 | to about 1024. It is automatically readjusted to half of bufsize if it is |
| 943 | larger than that. This means you don't have to worry about it when changing |
| 944 | bufsize. |
| 945 | |
Willy Tarreau | bd9a0a7 | 2011-10-23 21:14:29 +0200 | [diff] [blame] | 946 | tune.pipesize <number> |
| 947 | Sets the kernel pipe buffer size to this size (in bytes). By default, pipes |
| 948 | are the default size for the system. But sometimes when using TCP splicing, |
| 949 | it can improve performance to increase pipe sizes, especially if it is |
| 950 | suspected that pipes are not filled and that many calls to splice() are |
| 951 | performed. This has an impact on the kernel's memory footprint, so this must |
| 952 | not be changed if impacts are not understood. |
| 953 | |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 954 | tune.rcvbuf.client <number> |
| 955 | tune.rcvbuf.server <number> |
| 956 | Forces the kernel socket receive buffer size on the client or the server side |
| 957 | to the specified value in bytes. This value applies to all TCP/HTTP frontends |
| 958 | and backends. It should normally never be set, and the default size (0) lets |
| 959 | the kernel autotune this value depending on the amount of available memory. |
| 960 | However it can sometimes help to set it to very low values (eg: 4096) in |
| 961 | order to save kernel memory by preventing it from buffering too large amounts |
| 962 | of received data. Lower values will significantly increase CPU usage though. |
| 963 | |
| 964 | tune.sndbuf.client <number> |
| 965 | tune.sndbuf.server <number> |
| 966 | Forces the kernel socket send buffer size on the client or the server side to |
| 967 | the specified value in bytes. This value applies to all TCP/HTTP frontends |
| 968 | and backends. It should normally never be set, and the default size (0) lets |
| 969 | the kernel autotune this value depending on the amount of available memory. |
| 970 | However it can sometimes help to set it to very low values (eg: 4096) in |
| 971 | order to save kernel memory by preventing it from buffering too large amounts |
| 972 | of received data. Lower values will significantly increase CPU usage though. |
| 973 | Another use case is to prevent write timeouts with extremely slow clients due |
| 974 | to the kernel waiting for a large part of the buffer to be read before |
| 975 | notifying haproxy again. |
| 976 | |
Willy Tarreau | 6ec58db | 2012-11-16 16:32:15 +0100 | [diff] [blame] | 977 | tune.ssl.cachesize <number> |
Emeric Brun | af9619d | 2012-11-28 18:47:52 +0100 | [diff] [blame] | 978 | Sets the size of the global SSL session cache, in a number of blocks. A block |
| 979 | is large enough to contain an encoded session without peer certificate. |
| 980 | An encoded session with peer certificate is stored in multiple blocks |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 981 | depending on the size of the peer certificate. A block uses approximately |
Emeric Brun | af9619d | 2012-11-28 18:47:52 +0100 | [diff] [blame] | 982 | 200 bytes of memory. The default value may be forced at build time, otherwise |
| 983 | defaults to 20000. When the cache is full, the most idle entries are purged |
| 984 | and reassigned. Higher values reduce the occurrence of such a purge, hence |
| 985 | the number of CPU-intensive SSL handshakes by ensuring that all users keep |
| 986 | their session as long as possible. All entries are pre-allocated upon startup |
Emeric Brun | 22890a1 | 2012-12-28 14:41:32 +0100 | [diff] [blame] | 987 | and are shared between all processes if "nbproc" is greater than 1. Setting |
| 988 | this value to 0 disables the SSL session cache. |
Willy Tarreau | 6ec58db | 2012-11-16 16:32:15 +0100 | [diff] [blame] | 989 | |
Emeric Brun | 8dc6039 | 2014-05-09 13:52:00 +0200 | [diff] [blame] | 990 | tune.ssl.force-private-cache |
| 991 | This boolean disables SSL session cache sharing between all processes. It |
| 992 | should normally not be used since it will force many renegotiations due to |
| 993 | clients hitting a random process. But it may be required on some operating |
| 994 | systems where none of the SSL cache synchronization method may be used. In |
| 995 | this case, adding a first layer of hash-based load balancing before the SSL |
| 996 | layer might limit the impact of the lack of session sharing. |
| 997 | |
Emeric Brun | 4f65bff | 2012-11-16 15:11:00 +0100 | [diff] [blame] | 998 | tune.ssl.lifetime <timeout> |
| 999 | Sets how long a cached SSL session may remain valid. This time is expressed |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 1000 | in seconds and defaults to 300 (5 min). It is important to understand that it |
Emeric Brun | 4f65bff | 2012-11-16 15:11:00 +0100 | [diff] [blame] | 1001 | does not guarantee that sessions will last that long, because if the cache is |
| 1002 | full, the longest idle sessions will be purged despite their configured |
| 1003 | lifetime. The real usefulness of this setting is to prevent sessions from |
| 1004 | being used for too long. |
| 1005 | |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 1006 | tune.ssl.maxrecord <number> |
| 1007 | Sets the maximum amount of bytes passed to SSL_write() at a time. Default |
| 1008 | value 0 means there is no limit. Over SSL/TLS, the client can decipher the |
| 1009 | data only once it has received a full record. With large records, it means |
| 1010 | that clients might have to download up to 16kB of data before starting to |
| 1011 | process them. Limiting the value can improve page load times on browsers |
| 1012 | located over high latency or low bandwidth networks. It is suggested to find |
| 1013 | optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over |
| 1014 | Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled), |
| 1015 | keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and |
| 1016 | 2859 gave good results during tests. Use "strace -e trace=write" to find the |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 1017 | best value. Haproxy will automatically switch to this setting after an idle |
| 1018 | stream has been detected (see tune.idletimer above). |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 1019 | |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 1020 | tune.zlib.memlevel <number> |
| 1021 | Sets the memLevel parameter in zlib initialization for each session. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 1022 | defines how much memory should be allocated for the internal compression |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 1023 | state. A value of 1 uses minimum memory but is slow and reduces compression |
| 1024 | ratio, a value of 9 uses maximum memory for optimal speed. Can be a value |
| 1025 | between 1 and 9. The default value is 8. |
| 1026 | |
| 1027 | tune.zlib.windowsize <number> |
| 1028 | Sets the window size (the size of the history buffer) as a parameter of the |
| 1029 | zlib initialization for each session. Larger values of this parameter result |
| 1030 | in better compression at the expense of memory usage. Can be a value between |
| 1031 | 8 and 15. The default value is 15. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1032 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1033 | 3.3. Debugging |
| 1034 | -------------- |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1035 | |
| 1036 | debug |
| 1037 | Enables debug mode which dumps to stdout all exchanges, and disables forking |
| 1038 | into background. It is the equivalent of the command-line argument "-d". It |
| 1039 | should never be used in a production configuration since it may prevent full |
| 1040 | system startup. |
| 1041 | |
| 1042 | quiet |
| 1043 | Do not display any message during startup. It is equivalent to the command- |
| 1044 | line argument "-q". |
| 1045 | |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1046 | |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1047 | 3.4. Userlists |
| 1048 | -------------- |
| 1049 | It is possible to control access to frontend/backend/listen sections or to |
| 1050 | http stats by allowing only authenticated and authorized users. To do this, |
| 1051 | it is required to create at least one userlist and to define users. |
| 1052 | |
| 1053 | userlist <listname> |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 1054 | Creates new userlist with name <listname>. Many independent userlists can be |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1055 | used to store authentication & authorization data for independent customers. |
| 1056 | |
| 1057 | group <groupname> [users <user>,<user>,(...)] |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 1058 | Adds group <groupname> to the current userlist. It is also possible to |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1059 | attach users to this group by using a comma separated list of names |
| 1060 | proceeded by "users" keyword. |
| 1061 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 1062 | user <username> [password|insecure-password <password>] |
| 1063 | [groups <group>,<group>,(...)] |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1064 | Adds user <username> to the current userlist. Both secure (encrypted) and |
| 1065 | insecure (unencrypted) passwords can be used. Encrypted passwords are |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 1066 | evaluated using the crypt(3) function so depending of the system's |
| 1067 | capabilities, different algorithms are supported. For example modern Glibc |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1068 | based Linux system supports MD5, SHA-256, SHA-512 and of course classic, |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 1069 | DES-based method of encrypting passwords. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1070 | |
| 1071 | |
| 1072 | Example: |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 1073 | userlist L1 |
| 1074 | group G1 users tiger,scott |
| 1075 | group G2 users xdb,scott |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1076 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 1077 | user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91 |
| 1078 | user scott insecure-password elgato |
| 1079 | user xdb insecure-password hello |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1080 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 1081 | userlist L2 |
| 1082 | group G1 |
| 1083 | group G2 |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1084 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 1085 | user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1 |
| 1086 | user scott insecure-password elgato groups G1,G2 |
| 1087 | user xdb insecure-password hello groups G2 |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 1088 | |
| 1089 | Please note that both lists are functionally identical. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1090 | |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1091 | |
| 1092 | 3.5. Peers |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1093 | ---------- |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1094 | It is possible to synchronize server entries in stick tables between several |
| 1095 | haproxy instances over TCP connections in a multi-master fashion. Each instance |
| 1096 | pushes its local updates and insertions to remote peers. Server IDs are used to |
| 1097 | identify servers remotely, so it is important that configurations look similar |
| 1098 | or at least that the same IDs are forced on each server on all participants. |
| 1099 | Interrupted exchanges are automatically detected and recovered from the last |
| 1100 | known point. In addition, during a soft restart, the old process connects to |
| 1101 | the new one using such a TCP connection to push all its entries before the new |
| 1102 | process tries to connect to other peers. That ensures very fast replication |
| 1103 | during a reload, it typically takes a fraction of a second even for large |
| 1104 | tables. |
| 1105 | |
| 1106 | peers <peersect> |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 1107 | Creates a new peer list with name <peersect>. It is an independent section, |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1108 | which is referenced by one or more stick-tables. |
| 1109 | |
| 1110 | peer <peername> <ip>:<port> |
| 1111 | Defines a peer inside a peers section. |
| 1112 | If <peername> is set to the local peer name (by default hostname, or forced |
| 1113 | using "-L" command line option), haproxy will listen for incoming remote peer |
| 1114 | connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to |
| 1115 | to join the remote peer, and <peername> is used at the protocol level to |
| 1116 | identify and validate the remote peer on the server side. |
| 1117 | |
| 1118 | During a soft restart, local peer <ip>:<port> is used by the old instance to |
| 1119 | connect the new one and initiate a complete replication (teaching process). |
| 1120 | |
| 1121 | It is strongly recommended to have the exact same peers declaration on all |
| 1122 | peers and to only rely on the "-L" command line argument to change the local |
| 1123 | peer name. This makes it easier to maintain coherent configuration files |
| 1124 | across all peers. |
| 1125 | |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 1126 | Any part of the address string may reference any number of environment |
| 1127 | variables by preceding their name with a dollar sign ('$') and optionally |
| 1128 | enclosing them with braces ('{}'), similarly to what is done in Bourne shell. |
| 1129 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1130 | Example: |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1131 | peers mypeers |
Willy Tarreau | f7b30a9 | 2010-12-06 22:59:17 +0100 | [diff] [blame] | 1132 | peer haproxy1 192.168.0.1:1024 |
| 1133 | peer haproxy2 192.168.0.2:1024 |
| 1134 | peer haproxy3 10.2.0.1:1024 |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1135 | |
| 1136 | backend mybackend |
| 1137 | mode tcp |
| 1138 | balance roundrobin |
| 1139 | stick-table type ip size 20k peers mypeers |
| 1140 | stick on src |
| 1141 | |
Willy Tarreau | f7b30a9 | 2010-12-06 22:59:17 +0100 | [diff] [blame] | 1142 | server srv1 192.168.0.30:80 |
| 1143 | server srv2 192.168.0.31:80 |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 1144 | |
| 1145 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1146 | 4. Proxies |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1147 | ---------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1148 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1149 | Proxy configuration can be located in a set of sections : |
| 1150 | - defaults <name> |
| 1151 | - frontend <name> |
| 1152 | - backend <name> |
| 1153 | - listen <name> |
| 1154 | |
| 1155 | A "defaults" section sets default parameters for all other sections following |
| 1156 | its declaration. Those default parameters are reset by the next "defaults" |
| 1157 | section. See below for the list of parameters which can be set in a "defaults" |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1158 | section. The name is optional but its use is encouraged for better readability. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1159 | |
| 1160 | A "frontend" section describes a set of listening sockets accepting client |
| 1161 | connections. |
| 1162 | |
| 1163 | A "backend" section describes a set of servers to which the proxy will connect |
| 1164 | to forward incoming connections. |
| 1165 | |
| 1166 | A "listen" section defines a complete proxy with its frontend and backend |
| 1167 | parts combined in one section. It is generally useful for TCP-only traffic. |
| 1168 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1169 | All proxy names must be formed from upper and lower case letters, digits, |
| 1170 | '-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are |
| 1171 | case-sensitive, which means that "www" and "WWW" are two different proxies. |
| 1172 | |
| 1173 | Historically, all proxy names could overlap, it just caused troubles in the |
| 1174 | logs. Since the introduction of content switching, it is mandatory that two |
| 1175 | proxies with overlapping capabilities (frontend/backend) have different names. |
| 1176 | However, it is still permitted that a frontend and a backend share the same |
| 1177 | name, as this configuration seems to be commonly encountered. |
| 1178 | |
| 1179 | Right now, two major proxy modes are supported : "tcp", also known as layer 4, |
| 1180 | and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1181 | bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1182 | protocol, and can interact with it by allowing, blocking, switching, adding, |
| 1183 | modifying, or removing arbitrary contents in requests or responses, based on |
| 1184 | arbitrary criteria. |
| 1185 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 1186 | In HTTP mode, the processing applied to requests and responses flowing over |
| 1187 | a connection depends in the combination of the frontend's HTTP options and |
| 1188 | the backend's. HAProxy supports 5 connection modes : |
| 1189 | |
| 1190 | - KAL : keep alive ("option http-keep-alive") which is the default mode : all |
| 1191 | requests and responses are processed, and connections remain open but idle |
| 1192 | between responses and new requests. |
| 1193 | |
| 1194 | - TUN: tunnel ("option http-tunnel") : this was the default mode for versions |
| 1195 | 1.0 to 1.5-dev21 : only the first request and response are processed, and |
| 1196 | everything else is forwarded with no analysis at all. This mode should not |
| 1197 | be used as it creates lots of trouble with logging and HTTP processing. |
| 1198 | |
| 1199 | - PCL: passive close ("option httpclose") : exactly the same as tunnel mode, |
| 1200 | but with "Connection: close" appended in both directions to try to make |
| 1201 | both ends close after the first request/response exchange. |
| 1202 | |
| 1203 | - SCL: server close ("option http-server-close") : the server-facing |
| 1204 | connection is closed after the end of the response is received, but the |
| 1205 | client-facing connection remains open. |
| 1206 | |
| 1207 | - FCL: forced close ("option forceclose") : the connection is actively closed |
| 1208 | after the end of the response. |
| 1209 | |
| 1210 | The effective mode that will be applied to a connection passing through a |
| 1211 | frontend and a backend can be determined by both proxy modes according to the |
| 1212 | following matrix, but in short, the modes are symmetric, keep-alive is the |
| 1213 | weakest option and force close is the strongest. |
| 1214 | |
| 1215 | Backend mode |
| 1216 | |
| 1217 | | KAL | TUN | PCL | SCL | FCL |
| 1218 | ----+-----+-----+-----+-----+---- |
| 1219 | KAL | KAL | TUN | PCL | SCL | FCL |
| 1220 | ----+-----+-----+-----+-----+---- |
| 1221 | TUN | TUN | TUN | PCL | SCL | FCL |
| 1222 | Frontend ----+-----+-----+-----+-----+---- |
| 1223 | mode PCL | PCL | PCL | PCL | FCL | FCL |
| 1224 | ----+-----+-----+-----+-----+---- |
| 1225 | SCL | SCL | SCL | FCL | SCL | FCL |
| 1226 | ----+-----+-----+-----+-----+---- |
| 1227 | FCL | FCL | FCL | FCL | FCL | FCL |
| 1228 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1229 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 1230 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1231 | 4.1. Proxy keywords matrix |
| 1232 | -------------------------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1233 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1234 | The following list of keywords is supported. Most of them may only be used in a |
| 1235 | limited set of section types. Some of them are marked as "deprecated" because |
| 1236 | they are inherited from an old syntax which may be confusing or functionally |
| 1237 | limited, and there are new recommended keywords to replace them. Keywords |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1238 | marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1239 | option contstats". This makes sense when the option has been enabled by default |
Willy Tarreau | 3842f00 | 2009-06-14 11:39:52 +0200 | [diff] [blame] | 1240 | and must be disabled for a specific instance. Such options may also be prefixed |
| 1241 | with "default" in order to restore default settings regardless of what has been |
| 1242 | specified in a previous "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1243 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1244 | |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1245 | keyword defaults frontend listen backend |
| 1246 | ------------------------------------+----------+----------+---------+--------- |
| 1247 | acl - X X X |
| 1248 | appsession - - X X |
| 1249 | backlog X X X - |
| 1250 | balance X - X X |
| 1251 | bind - X X - |
| 1252 | bind-process X X X X |
| 1253 | block - X X X |
| 1254 | capture cookie - X X - |
| 1255 | capture request header - X X - |
| 1256 | capture response header - X X - |
| 1257 | clitimeout (deprecated) X X X - |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 1258 | compression X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1259 | contimeout (deprecated) X - X X |
| 1260 | cookie X - X X |
| 1261 | default-server X - X X |
| 1262 | default_backend X X X - |
| 1263 | description - X X X |
| 1264 | disabled X X X X |
| 1265 | dispatch - - X X |
| 1266 | enabled X X X X |
| 1267 | errorfile X X X X |
| 1268 | errorloc X X X X |
| 1269 | errorloc302 X X X X |
| 1270 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 1271 | errorloc303 X X X X |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 1272 | force-persist - X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1273 | fullconn X - X X |
| 1274 | grace X X X X |
| 1275 | hash-type X - X X |
| 1276 | http-check disable-on-404 X - X X |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 1277 | http-check expect - - X X |
Willy Tarreau | 7ab6aff | 2010-10-12 06:30:16 +0200 | [diff] [blame] | 1278 | http-check send-state X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1279 | http-request - X X X |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 1280 | http-response - X X X |
Baptiste Assmann | 2c42ef5 | 2013-10-09 21:57:02 +0200 | [diff] [blame] | 1281 | http-send-name-header - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1282 | id - X X X |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 1283 | ignore-persist - X X X |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 1284 | log (*) X X X X |
Willy Tarreau | c35362a | 2014-04-25 13:58:37 +0200 | [diff] [blame] | 1285 | max-keep-alive-queue X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1286 | maxconn X X X - |
| 1287 | mode X X X X |
| 1288 | monitor fail - X X - |
| 1289 | monitor-net X X X - |
| 1290 | monitor-uri X X X - |
| 1291 | option abortonclose (*) X - X X |
| 1292 | option accept-invalid-http-request (*) X X X - |
| 1293 | option accept-invalid-http-response (*) X - X X |
| 1294 | option allbackups (*) X - X X |
| 1295 | option checkcache (*) X - X X |
| 1296 | option clitcpka (*) X X X - |
| 1297 | option contstats (*) X X X - |
| 1298 | option dontlog-normal (*) X X X - |
| 1299 | option dontlognull (*) X X X - |
| 1300 | option forceclose (*) X X X X |
| 1301 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 1302 | option forwardfor X X X X |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 1303 | option http-keep-alive (*) X X X X |
Willy Tarreau | 96e3121 | 2011-05-30 18:10:30 +0200 | [diff] [blame] | 1304 | option http-no-delay (*) X X X X |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 1305 | option http-pretend-keepalive (*) X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1306 | option http-server-close (*) X X X X |
Willy Tarreau | 02bce8b | 2014-01-30 00:15:28 +0100 | [diff] [blame] | 1307 | option http-tunnel (*) X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1308 | option http-use-proxy-header (*) X X X - |
| 1309 | option httpchk X - X X |
| 1310 | option httpclose (*) X X X X |
| 1311 | option httplog X X X X |
| 1312 | option http_proxy (*) X X X X |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 1313 | option independent-streams (*) X X X X |
Gabor Lekeny | b4c81e4 | 2010-09-29 18:17:05 +0200 | [diff] [blame] | 1314 | option ldap-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1315 | option log-health-checks (*) X - X X |
| 1316 | option log-separate-errors (*) X X X - |
| 1317 | option logasap (*) X X X - |
| 1318 | option mysql-check X - X X |
Rauf Kuliyev | 38b4156 | 2011-01-04 15:14:13 +0100 | [diff] [blame] | 1319 | option pgsql-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1320 | option nolinger (*) X X X X |
| 1321 | option originalto X X X X |
| 1322 | option persist (*) X - X X |
| 1323 | option redispatch (*) X - X X |
Hervé COMMOWICK | ec032d6 | 2011-08-05 16:23:48 +0200 | [diff] [blame] | 1324 | option redis-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1325 | option smtpchk X - X X |
| 1326 | option socket-stats (*) X X X - |
| 1327 | option splice-auto (*) X X X X |
| 1328 | option splice-request (*) X X X X |
| 1329 | option splice-response (*) X X X X |
| 1330 | option srvtcpka (*) X - X X |
| 1331 | option ssl-hello-chk X - X X |
| 1332 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 1333 | option tcp-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1334 | option tcp-smart-accept (*) X X X - |
| 1335 | option tcp-smart-connect (*) X - X X |
| 1336 | option tcpka X X X X |
| 1337 | option tcplog X X X X |
| 1338 | option transparent (*) X - X X |
| 1339 | persist rdp-cookie X - X X |
| 1340 | rate-limit sessions X X X - |
| 1341 | redirect - X X X |
| 1342 | redisp (deprecated) X - X X |
| 1343 | redispatch (deprecated) X - X X |
| 1344 | reqadd - X X X |
| 1345 | reqallow - X X X |
| 1346 | reqdel - X X X |
| 1347 | reqdeny - X X X |
| 1348 | reqiallow - X X X |
| 1349 | reqidel - X X X |
| 1350 | reqideny - X X X |
| 1351 | reqipass - X X X |
| 1352 | reqirep - X X X |
| 1353 | reqisetbe - X X X |
| 1354 | reqitarpit - X X X |
| 1355 | reqpass - X X X |
| 1356 | reqrep - X X X |
| 1357 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 1358 | reqsetbe - X X X |
| 1359 | reqtarpit - X X X |
| 1360 | retries X - X X |
| 1361 | rspadd - X X X |
| 1362 | rspdel - X X X |
| 1363 | rspdeny - X X X |
| 1364 | rspidel - X X X |
| 1365 | rspideny - X X X |
| 1366 | rspirep - X X X |
| 1367 | rsprep - X X X |
| 1368 | server - - X X |
| 1369 | source X - X X |
| 1370 | srvtimeout (deprecated) X - X X |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 1371 | stats admin - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1372 | stats auth X - X X |
| 1373 | stats enable X - X X |
| 1374 | stats hide-version X - X X |
Cyril Bonté | 2be1b3f | 2010-09-30 23:46:30 +0200 | [diff] [blame] | 1375 | stats http-request - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1376 | stats realm X - X X |
| 1377 | stats refresh X - X X |
| 1378 | stats scope X - X X |
| 1379 | stats show-desc X - X X |
| 1380 | stats show-legends X - X X |
| 1381 | stats show-node X - X X |
| 1382 | stats uri X - X X |
| 1383 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 1384 | stick match - - X X |
| 1385 | stick on - - X X |
| 1386 | stick store-request - - X X |
Willy Tarreau | d8dc99f | 2011-07-01 11:33:25 +0200 | [diff] [blame] | 1387 | stick store-response - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1388 | stick-table - - X X |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 1389 | tcp-check connect - - X X |
| 1390 | tcp-check expect - - X X |
| 1391 | tcp-check send - - X X |
| 1392 | tcp-check send-binary - - X X |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 1393 | tcp-request connection - X X - |
| 1394 | tcp-request content - X X X |
Willy Tarreau | a56235c | 2010-09-14 11:31:36 +0200 | [diff] [blame] | 1395 | tcp-request inspect-delay - X X X |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 1396 | tcp-response content - - X X |
| 1397 | tcp-response inspect-delay - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1398 | timeout check X - X X |
| 1399 | timeout client X X X - |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 1400 | timeout client-fin X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1401 | timeout clitimeout (deprecated) X X X - |
| 1402 | timeout connect X - X X |
| 1403 | timeout contimeout (deprecated) X - X X |
| 1404 | timeout http-keep-alive X X X X |
| 1405 | timeout http-request X X X X |
| 1406 | timeout queue X - X X |
| 1407 | timeout server X - X X |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 1408 | timeout server-fin X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1409 | timeout srvtimeout (deprecated) X - X X |
| 1410 | timeout tarpit X X X X |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 1411 | timeout tunnel X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1412 | transparent (deprecated) X - X X |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 1413 | unique-id-format X X X - |
| 1414 | unique-id-header X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1415 | use_backend - X X - |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 1416 | use-server - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 1417 | ------------------------------------+----------+----------+---------+--------- |
| 1418 | keyword defaults frontend listen backend |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1419 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1420 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1421 | 4.2. Alphabetically sorted keywords reference |
| 1422 | --------------------------------------------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1423 | |
| 1424 | This section provides a description of each keyword and its usage. |
| 1425 | |
| 1426 | |
| 1427 | acl <aclname> <criterion> [flags] [operator] <value> ... |
| 1428 | Declare or complete an access list. |
| 1429 | May be used in sections : defaults | frontend | listen | backend |
| 1430 | no | yes | yes | yes |
| 1431 | Example: |
| 1432 | acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| 1433 | acl invalid_src src_port 0:1023 |
| 1434 | acl local_dst hdr(host) -i localhost |
| 1435 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1436 | See section 7 about ACL usage. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1437 | |
| 1438 | |
Cyril Bonté | b21570a | 2009-11-29 20:04:48 +0100 | [diff] [blame] | 1439 | appsession <cookie> len <length> timeout <holdtime> |
| 1440 | [request-learn] [prefix] [mode <path-parameters|query-string>] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1441 | Define session stickiness on an existing application cookie. |
| 1442 | May be used in sections : defaults | frontend | listen | backend |
| 1443 | no | no | yes | yes |
| 1444 | Arguments : |
| 1445 | <cookie> this is the name of the cookie used by the application and which |
| 1446 | HAProxy will have to learn for each new session. |
| 1447 | |
Cyril Bonté | b21570a | 2009-11-29 20:04:48 +0100 | [diff] [blame] | 1448 | <length> this is the max number of characters that will be memorized and |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1449 | checked in each cookie value. |
| 1450 | |
| 1451 | <holdtime> this is the time after which the cookie will be removed from |
| 1452 | memory if unused. If no unit is specified, this time is in |
| 1453 | milliseconds. |
| 1454 | |
Cyril Bonté | bf47aeb | 2009-10-15 00:15:40 +0200 | [diff] [blame] | 1455 | request-learn |
| 1456 | If this option is specified, then haproxy will be able to learn |
| 1457 | the cookie found in the request in case the server does not |
| 1458 | specify any in response. This is typically what happens with |
| 1459 | PHPSESSID cookies, or when haproxy's session expires before |
| 1460 | the application's session and the correct server is selected. |
| 1461 | It is recommended to specify this option to improve reliability. |
| 1462 | |
Cyril Bonté | b21570a | 2009-11-29 20:04:48 +0100 | [diff] [blame] | 1463 | prefix When this option is specified, haproxy will match on the cookie |
| 1464 | prefix (or URL parameter prefix). The appsession value is the |
| 1465 | data following this prefix. |
| 1466 | |
| 1467 | Example : |
| 1468 | appsession ASPSESSIONID len 64 timeout 3h prefix |
| 1469 | |
| 1470 | This will match the cookie ASPSESSIONIDXXXX=XXXXX, |
| 1471 | the appsession value will be XXXX=XXXXX. |
| 1472 | |
| 1473 | mode This option allows to change the URL parser mode. |
| 1474 | 2 modes are currently supported : |
| 1475 | - path-parameters : |
| 1476 | The parser looks for the appsession in the path parameters |
| 1477 | part (each parameter is separated by a semi-colon), which is |
| 1478 | convenient for JSESSIONID for example. |
| 1479 | This is the default mode if the option is not set. |
| 1480 | - query-string : |
| 1481 | In this mode, the parser will look for the appsession in the |
| 1482 | query string. |
| 1483 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1484 | When an application cookie is defined in a backend, HAProxy will check when |
| 1485 | the server sets such a cookie, and will store its value in a table, and |
| 1486 | associate it with the server's identifier. Up to <length> characters from |
| 1487 | the value will be retained. On each connection, haproxy will look for this |
Cyril Bonté | b21570a | 2009-11-29 20:04:48 +0100 | [diff] [blame] | 1488 | cookie both in the "Cookie:" headers, and as a URL parameter (depending on |
| 1489 | the mode used). If a known value is found, the client will be directed to the |
| 1490 | server associated with this value. Otherwise, the load balancing algorithm is |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1491 | applied. Cookies are automatically removed from memory when they have been |
| 1492 | unused for a duration longer than <holdtime>. |
| 1493 | |
| 1494 | The definition of an application cookie is limited to one per backend. |
| 1495 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 1496 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 1497 | unless you know what you do : memory is not shared between the |
| 1498 | processes, which can result in random behaviours. |
| 1499 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1500 | Example : |
| 1501 | appsession JSESSIONID len 52 timeout 3h |
| 1502 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 1503 | See also : "cookie", "capture cookie", "balance", "stick", "stick-table", |
| 1504 | "ignore-persist", "nbproc" and "bind-process". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1505 | |
| 1506 | |
Willy Tarreau | c73ce2b | 2008-01-06 10:55:10 +0100 | [diff] [blame] | 1507 | backlog <conns> |
| 1508 | Give hints to the system about the approximate listen backlog desired size |
| 1509 | May be used in sections : defaults | frontend | listen | backend |
| 1510 | yes | yes | yes | no |
| 1511 | Arguments : |
| 1512 | <conns> is the number of pending connections. Depending on the operating |
| 1513 | system, it may represent the number of already acknowledged |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1514 | connections, of non-acknowledged ones, or both. |
Willy Tarreau | c73ce2b | 2008-01-06 10:55:10 +0100 | [diff] [blame] | 1515 | |
| 1516 | In order to protect against SYN flood attacks, one solution is to increase |
| 1517 | the system's SYN backlog size. Depending on the system, sometimes it is just |
| 1518 | tunable via a system parameter, sometimes it is not adjustable at all, and |
| 1519 | sometimes the system relies on hints given by the application at the time of |
| 1520 | the listen() syscall. By default, HAProxy passes the frontend's maxconn value |
| 1521 | to the listen() syscall. On systems which can make use of this value, it can |
| 1522 | sometimes be useful to be able to specify a different value, hence this |
| 1523 | backlog parameter. |
| 1524 | |
| 1525 | On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is |
| 1526 | used as a hint and the system accepts up to the smallest greater power of |
| 1527 | two, and never more than some limits (usually 32768). |
| 1528 | |
| 1529 | See also : "maxconn" and the target operating system's tuning guide. |
| 1530 | |
| 1531 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1532 | balance <algorithm> [ <arguments> ] |
Willy Tarreau | 226071e | 2014-04-10 11:55:45 +0200 | [diff] [blame] | 1533 | balance url_param <param> [check_post] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1534 | Define the load balancing algorithm to be used in a backend. |
| 1535 | May be used in sections : defaults | frontend | listen | backend |
| 1536 | yes | no | yes | yes |
| 1537 | Arguments : |
| 1538 | <algorithm> is the algorithm used to select a server when doing load |
| 1539 | balancing. This only applies when no persistence information |
| 1540 | is available, or when a connection is redispatched to another |
| 1541 | server. <algorithm> may be one of the following : |
| 1542 | |
| 1543 | roundrobin Each server is used in turns, according to their weights. |
| 1544 | This is the smoothest and fairest algorithm when the server's |
| 1545 | processing time remains equally distributed. This algorithm |
| 1546 | is dynamic, which means that server weights may be adjusted |
Willy Tarreau | 9757a38 | 2009-10-03 12:56:50 +0200 | [diff] [blame] | 1547 | on the fly for slow starts for instance. It is limited by |
Godbach | a34bdc0 | 2013-07-22 07:44:53 +0800 | [diff] [blame] | 1548 | design to 4095 active servers per backend. Note that in some |
Willy Tarreau | 9757a38 | 2009-10-03 12:56:50 +0200 | [diff] [blame] | 1549 | large farms, when a server becomes up after having been down |
| 1550 | for a very short time, it may sometimes take a few hundreds |
| 1551 | requests for it to be re-integrated into the farm and start |
| 1552 | receiving traffic. This is normal, though very rare. It is |
| 1553 | indicated here in case you would have the chance to observe |
| 1554 | it, so that you don't worry. |
| 1555 | |
| 1556 | static-rr Each server is used in turns, according to their weights. |
| 1557 | This algorithm is as similar to roundrobin except that it is |
| 1558 | static, which means that changing a server's weight on the |
| 1559 | fly will have no effect. On the other hand, it has no design |
| 1560 | limitation on the number of servers, and when a server goes |
| 1561 | up, it is always immediately reintroduced into the farm, once |
| 1562 | the full map is recomputed. It also uses slightly less CPU to |
| 1563 | run (around -1%). |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1564 | |
Willy Tarreau | 2d2a7f8 | 2008-03-17 12:07:56 +0100 | [diff] [blame] | 1565 | leastconn The server with the lowest number of connections receives the |
| 1566 | connection. Round-robin is performed within groups of servers |
| 1567 | of the same load to ensure that all servers will be used. Use |
| 1568 | of this algorithm is recommended where very long sessions are |
| 1569 | expected, such as LDAP, SQL, TSE, etc... but is not very well |
| 1570 | suited for protocols using short sessions such as HTTP. This |
| 1571 | algorithm is dynamic, which means that server weights may be |
| 1572 | adjusted on the fly for slow starts for instance. |
| 1573 | |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 1574 | first The first server with available connection slots receives the |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 1575 | connection. The servers are chosen from the lowest numeric |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 1576 | identifier to the highest (see server parameter "id"), which |
| 1577 | defaults to the server's position in the farm. Once a server |
Willy Tarreau | 64559c5 | 2012-04-07 09:08:45 +0200 | [diff] [blame] | 1578 | reaches its maxconn value, the next server is used. It does |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 1579 | not make sense to use this algorithm without setting maxconn. |
| 1580 | The purpose of this algorithm is to always use the smallest |
| 1581 | number of servers so that extra servers can be powered off |
| 1582 | during non-intensive hours. This algorithm ignores the server |
| 1583 | weight, and brings more benefit to long session such as RDP |
Willy Tarreau | 64559c5 | 2012-04-07 09:08:45 +0200 | [diff] [blame] | 1584 | or IMAP than HTTP, though it can be useful there too. In |
| 1585 | order to use this algorithm efficiently, it is recommended |
| 1586 | that a cloud controller regularly checks server usage to turn |
| 1587 | them off when unused, and regularly checks backend queue to |
| 1588 | turn new servers on when the queue inflates. Alternatively, |
| 1589 | using "http-check send-state" may inform servers on the load. |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 1590 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1591 | source The source IP address is hashed and divided by the total |
| 1592 | weight of the running servers to designate which server will |
| 1593 | receive the request. This ensures that the same client IP |
| 1594 | address will always reach the same server as long as no |
| 1595 | server goes down or up. If the hash result changes due to the |
| 1596 | number of running servers changing, many clients will be |
| 1597 | directed to a different server. This algorithm is generally |
| 1598 | used in TCP mode where no cookie may be inserted. It may also |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1599 | be used on the Internet to provide a best-effort stickiness |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1600 | to clients which refuse session cookies. This algorithm is |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 1601 | static by default, which means that changing a server's |
| 1602 | weight on the fly will have no effect, but this can be |
| 1603 | changed using "hash-type". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1604 | |
Oskar Stolc | 8dc4184 | 2012-05-19 10:19:54 +0100 | [diff] [blame] | 1605 | uri This algorithm hashes either the left part of the URI (before |
| 1606 | the question mark) or the whole URI (if the "whole" parameter |
| 1607 | is present) and divides the hash value by the total weight of |
| 1608 | the running servers. The result designates which server will |
| 1609 | receive the request. This ensures that the same URI will |
| 1610 | always be directed to the same server as long as no server |
| 1611 | goes up or down. This is used with proxy caches and |
| 1612 | anti-virus proxies in order to maximize the cache hit rate. |
| 1613 | Note that this algorithm may only be used in an HTTP backend. |
| 1614 | This algorithm is static by default, which means that |
| 1615 | changing a server's weight on the fly will have no effect, |
| 1616 | but this can be changed using "hash-type". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1617 | |
Oskar Stolc | 8dc4184 | 2012-05-19 10:19:54 +0100 | [diff] [blame] | 1618 | This algorithm supports two optional parameters "len" and |
Marek Majkowski | 9c30fc1 | 2008-04-27 23:25:55 +0200 | [diff] [blame] | 1619 | "depth", both followed by a positive integer number. These |
| 1620 | options may be helpful when it is needed to balance servers |
| 1621 | based on the beginning of the URI only. The "len" parameter |
| 1622 | indicates that the algorithm should only consider that many |
| 1623 | characters at the beginning of the URI to compute the hash. |
| 1624 | Note that having "len" set to 1 rarely makes sense since most |
| 1625 | URIs start with a leading "/". |
| 1626 | |
| 1627 | The "depth" parameter indicates the maximum directory depth |
| 1628 | to be used to compute the hash. One level is counted for each |
| 1629 | slash in the request. If both parameters are specified, the |
| 1630 | evaluation stops when either is reached. |
| 1631 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1632 | url_param The URL parameter specified in argument will be looked up in |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1633 | the query string of each HTTP GET request. |
| 1634 | |
| 1635 | If the modifier "check_post" is used, then an HTTP POST |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1636 | request entity will be searched for the parameter argument, |
| 1637 | when it is not found in a query string after a question mark |
Willy Tarreau | 226071e | 2014-04-10 11:55:45 +0200 | [diff] [blame] | 1638 | ('?') in the URL. The message body will only start to be |
| 1639 | analyzed once either the advertised amount of data has been |
| 1640 | received or the request buffer is full. In the unlikely event |
| 1641 | that chunked encoding is used, only the first chunk is |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1642 | scanned. Parameter values separated by a chunk boundary, may |
Willy Tarreau | 226071e | 2014-04-10 11:55:45 +0200 | [diff] [blame] | 1643 | be randomly balanced if at all. This keyword used to support |
| 1644 | an optional <max_wait> parameter which is now ignored. |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1645 | |
| 1646 | If the parameter is found followed by an equal sign ('=') and |
| 1647 | a value, then the value is hashed and divided by the total |
| 1648 | weight of the running servers. The result designates which |
| 1649 | server will receive the request. |
| 1650 | |
| 1651 | This is used to track user identifiers in requests and ensure |
| 1652 | that a same user ID will always be sent to the same server as |
| 1653 | long as no server goes up or down. If no value is found or if |
| 1654 | the parameter is not found, then a round robin algorithm is |
| 1655 | applied. Note that this algorithm may only be used in an HTTP |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 1656 | backend. This algorithm is static by default, which means |
| 1657 | that changing a server's weight on the fly will have no |
| 1658 | effect, but this can be changed using "hash-type". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1659 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1660 | hdr(<name>) The HTTP header <name> will be looked up in each HTTP |
| 1661 | request. Just as with the equivalent ACL 'hdr()' function, |
| 1662 | the header name in parenthesis is not case sensitive. If the |
| 1663 | header is absent or if it does not contain any value, the |
| 1664 | roundrobin algorithm is applied instead. |
Benoit | affb481 | 2009-03-25 13:02:10 +0100 | [diff] [blame] | 1665 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1666 | An optional 'use_domain_only' parameter is available, for |
Benoit | affb481 | 2009-03-25 13:02:10 +0100 | [diff] [blame] | 1667 | reducing the hash algorithm to the main domain part with some |
| 1668 | specific headers such as 'Host'. For instance, in the Host |
| 1669 | value "haproxy.1wt.eu", only "1wt" will be considered. |
| 1670 | |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 1671 | This algorithm is static by default, which means that |
| 1672 | changing a server's weight on the fly will have no effect, |
| 1673 | but this can be changed using "hash-type". |
| 1674 | |
Emeric Brun | 736aa23 | 2009-06-30 17:56:00 +0200 | [diff] [blame] | 1675 | rdp-cookie |
Hervé COMMOWICK | a3eb39c | 2011-08-05 18:48:51 +0200 | [diff] [blame] | 1676 | rdp-cookie(<name>) |
Emeric Brun | 736aa23 | 2009-06-30 17:56:00 +0200 | [diff] [blame] | 1677 | The RDP cookie <name> (or "mstshash" if omitted) will be |
| 1678 | looked up and hashed for each incoming TCP request. Just as |
| 1679 | with the equivalent ACL 'req_rdp_cookie()' function, the name |
| 1680 | is not case-sensitive. This mechanism is useful as a degraded |
| 1681 | persistence mode, as it makes it possible to always send the |
| 1682 | same user (or the same session ID) to the same server. If the |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1683 | cookie is not found, the normal roundrobin algorithm is |
Emeric Brun | 736aa23 | 2009-06-30 17:56:00 +0200 | [diff] [blame] | 1684 | used instead. |
| 1685 | |
| 1686 | Note that for this to work, the frontend must ensure that an |
| 1687 | RDP cookie is already present in the request buffer. For this |
| 1688 | you must use 'tcp-request content accept' rule combined with |
| 1689 | a 'req_rdp_cookie_cnt' ACL. |
| 1690 | |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 1691 | This algorithm is static by default, which means that |
| 1692 | changing a server's weight on the fly will have no effect, |
| 1693 | but this can be changed using "hash-type". |
| 1694 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1695 | See also the rdp_cookie pattern fetch function. |
Simon Horman | ab814e0 | 2011-06-24 14:50:20 +0900 | [diff] [blame] | 1696 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1697 | <arguments> is an optional list of arguments which may be needed by some |
Marek Majkowski | 9c30fc1 | 2008-04-27 23:25:55 +0200 | [diff] [blame] | 1698 | algorithms. Right now, only "url_param" and "uri" support an |
| 1699 | optional argument. |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1700 | |
Willy Tarreau | 3cd9af2 | 2009-03-15 14:06:41 +0100 | [diff] [blame] | 1701 | The load balancing algorithm of a backend is set to roundrobin when no other |
| 1702 | algorithm, mode nor option have been set. The algorithm may only be set once |
| 1703 | for each backend. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1704 | |
| 1705 | Examples : |
| 1706 | balance roundrobin |
| 1707 | balance url_param userid |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1708 | balance url_param session_id check_post 64 |
Benoit | affb481 | 2009-03-25 13:02:10 +0100 | [diff] [blame] | 1709 | balance hdr(User-Agent) |
| 1710 | balance hdr(host) |
| 1711 | balance hdr(Host) use_domain_only |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1712 | |
| 1713 | Note: the following caveats and limitations on using the "check_post" |
| 1714 | extension with "url_param" must be considered : |
| 1715 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1716 | - all POST requests are eligible for consideration, because there is no way |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1717 | to determine if the parameters will be found in the body or entity which |
| 1718 | may contain binary data. Therefore another method may be required to |
| 1719 | restrict consideration of POST requests that have no URL parameters in |
| 1720 | the body. (see acl reqideny http_end) |
| 1721 | |
| 1722 | - using a <max_wait> value larger than the request buffer size does not |
| 1723 | make sense and is useless. The buffer size is set at build time, and |
| 1724 | defaults to 16 kB. |
| 1725 | |
| 1726 | - Content-Encoding is not supported, the parameter search will probably |
| 1727 | fail; and load balancing will fall back to Round Robin. |
| 1728 | |
| 1729 | - Expect: 100-continue is not supported, load balancing will fall back to |
| 1730 | Round Robin. |
| 1731 | |
| 1732 | - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk. |
| 1733 | If the entire parameter value is not present in the first chunk, the |
| 1734 | selection of server is undefined (actually, defined by how little |
| 1735 | actually appeared in the first chunk). |
| 1736 | |
| 1737 | - This feature does not support generation of a 100, 411 or 501 response. |
| 1738 | |
| 1739 | - In some cases, requesting "check_post" MAY attempt to scan the entire |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1740 | contents of a message body. Scanning normally terminates when linear |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 1741 | white space or control characters are found, indicating the end of what |
| 1742 | might be a URL parameter list. This is probably not a concern with SGML |
| 1743 | type message bodies. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1744 | |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 1745 | See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and |
| 1746 | "http_proxy". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1747 | |
| 1748 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 1749 | bind [<address>]:<port_range> [, ...] [param*] |
| 1750 | bind /<path> [, ...] [param*] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1751 | Define one or several listening addresses and/or ports in a frontend. |
| 1752 | May be used in sections : defaults | frontend | listen | backend |
| 1753 | no | yes | yes | no |
| 1754 | Arguments : |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 1755 | <address> is optional and can be a host name, an IPv4 address, an IPv6 |
| 1756 | address, or '*'. It designates the address the frontend will |
| 1757 | listen on. If unset, all IPv4 addresses of the system will be |
| 1758 | listened on. The same will apply for '*' or the system's |
David du Colombier | 9c938da | 2011-03-17 10:40:27 +0100 | [diff] [blame] | 1759 | special address "0.0.0.0". The IPv6 equivalent is '::'. |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 1760 | Optionally, an address family prefix may be used before the |
| 1761 | address to force the family regardless of the address format, |
| 1762 | which can be useful to specify a path to a unix socket with |
| 1763 | no slash ('/'). Currently supported prefixes are : |
| 1764 | - 'ipv4@' -> address is always IPv4 |
| 1765 | - 'ipv6@' -> address is always IPv6 |
| 1766 | - 'unix@' -> address is a path to a local unix socket |
Willy Tarreau | ccfccef | 2014-05-10 01:49:15 +0200 | [diff] [blame] | 1767 | - 'abns@' -> address is in abstract namespace (Linux only) |
Willy Tarreau | 40aa070 | 2013-03-10 23:51:38 +0100 | [diff] [blame] | 1768 | - 'fd@<n>' -> use file descriptor <n> inherited from the |
| 1769 | parent. The fd must be bound and may or may not already |
| 1770 | be listening. |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 1771 | Any part of the address string may reference any number of |
| 1772 | environment variables by preceding their name with a dollar |
| 1773 | sign ('$') and optionally enclosing them with braces ('{}'), |
| 1774 | similarly to what is done in Bourne shell. |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 1775 | |
Willy Tarreau | c5011ca | 2010-03-22 11:53:56 +0100 | [diff] [blame] | 1776 | <port_range> is either a unique TCP port, or a port range for which the |
| 1777 | proxy will accept connections for the IP address specified |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 1778 | above. The port is mandatory for TCP listeners. Note that in |
| 1779 | the case of an IPv6 address, the port is always the number |
| 1780 | after the last colon (':'). A range can either be : |
Willy Tarreau | c5011ca | 2010-03-22 11:53:56 +0100 | [diff] [blame] | 1781 | - a numerical port (ex: '80') |
| 1782 | - a dash-delimited ports range explicitly stating the lower |
| 1783 | and upper bounds (ex: '2000-2100') which are included in |
| 1784 | the range. |
| 1785 | |
| 1786 | Particular care must be taken against port ranges, because |
| 1787 | every <address:port> couple consumes one socket (= a file |
| 1788 | descriptor), so it's easy to consume lots of descriptors |
| 1789 | with a simple range, and to run out of sockets. Also, each |
| 1790 | <address:port> couple must be used only once among all |
| 1791 | instances running on a same system. Please note that binding |
| 1792 | to ports lower than 1024 generally require particular |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 1793 | privileges to start the program, which are independent of |
Willy Tarreau | c5011ca | 2010-03-22 11:53:56 +0100 | [diff] [blame] | 1794 | the 'uid' parameter. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1795 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 1796 | <path> is a UNIX socket path beginning with a slash ('/'). This is |
| 1797 | alternative to the TCP listening port. Haproxy will then |
| 1798 | receive UNIX connections on the socket located at this place. |
| 1799 | The path must begin with a slash and by default is absolute. |
| 1800 | It can be relative to the prefix defined by "unix-bind" in |
| 1801 | the global section. Note that the total length of the prefix |
| 1802 | followed by the socket path cannot exceed some system limits |
| 1803 | for UNIX sockets, which commonly are set to 107 characters. |
| 1804 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 1805 | <param*> is a list of parameters common to all sockets declared on the |
| 1806 | same line. These numerous parameters depend on OS and build |
| 1807 | options and have a complete section dedicated to them. Please |
| 1808 | refer to section 5 to for more details. |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 1809 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1810 | It is possible to specify a list of address:port combinations delimited by |
| 1811 | commas. The frontend will then listen on all of these addresses. There is no |
| 1812 | fixed limit to the number of addresses and ports which can be listened on in |
| 1813 | a frontend, as well as there is no limit to the number of "bind" statements |
| 1814 | in a frontend. |
| 1815 | |
| 1816 | Example : |
| 1817 | listen http_proxy |
| 1818 | bind :80,:443 |
| 1819 | bind 10.0.0.1:10080,10.0.0.1:10443 |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 1820 | bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1821 | |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 1822 | listen http_https_proxy |
| 1823 | bind :80 |
Cyril Bonté | 0d44fc6 | 2012-10-09 22:45:33 +0200 | [diff] [blame] | 1824 | bind :443 ssl crt /etc/haproxy/site.pem |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 1825 | |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 1826 | listen http_https_proxy_explicit |
| 1827 | bind ipv6@:80 |
| 1828 | bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem |
| 1829 | bind unix@ssl-frontend.sock user root mode 600 accept-proxy |
| 1830 | |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 1831 | listen external_bind_app1 |
| 1832 | bind fd@${FD_APP1} |
| 1833 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 1834 | See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 1835 | documentation, and section 5 about bind options. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1836 | |
| 1837 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 1838 | bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ... |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1839 | Limit visibility of an instance to a certain set of processes numbers. |
| 1840 | May be used in sections : defaults | frontend | listen | backend |
| 1841 | yes | yes | yes | yes |
| 1842 | Arguments : |
| 1843 | all All process will see this instance. This is the default. It |
| 1844 | may be used to override a default value. |
| 1845 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 1846 | odd This instance will be enabled on processes 1,3,5,...63. This |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1847 | option may be combined with other numbers. |
| 1848 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 1849 | even This instance will be enabled on processes 2,4,6,...64. This |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1850 | option may be combined with other numbers. Do not use it |
| 1851 | with less than 2 processes otherwise some instances might be |
| 1852 | missing from all processes. |
| 1853 | |
Willy Tarreau | 110ecc1 | 2012-11-15 17:50:01 +0100 | [diff] [blame] | 1854 | number The instance will be enabled on this process number or range, |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 1855 | whose values must all be between 1 and 32 or 64 depending on |
Willy Tarreau | 102df61 | 2014-05-07 23:56:38 +0200 | [diff] [blame] | 1856 | the machine's word size. If a proxy is bound to process |
| 1857 | numbers greater than the configured global.nbproc, it will |
| 1858 | either be forced to process #1 if a single process was |
| 1859 | specified, or to all processes otherwise. |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1860 | |
| 1861 | This keyword limits binding of certain instances to certain processes. This |
| 1862 | is useful in order not to have too many processes listening to the same |
| 1863 | ports. For instance, on a dual-core machine, it might make sense to set |
| 1864 | 'nbproc 2' in the global section, then distributes the listeners among 'odd' |
| 1865 | and 'even' instances. |
| 1866 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 1867 | At the moment, it is not possible to reference more than 32 or 64 processes |
| 1868 | using this keyword, but this should be more than enough for most setups. |
| 1869 | Please note that 'all' really means all processes regardless of the machine's |
| 1870 | word size, and is not limited to the first 32 or 64. |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1871 | |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 1872 | Each "bind" line may further be limited to a subset of the proxy's processes, |
| 1873 | please consult the "process" bind keyword in section 5.1. |
| 1874 | |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1875 | If some backends are referenced by frontends bound to other processes, the |
| 1876 | backend automatically inherits the frontend's processes. |
| 1877 | |
| 1878 | Example : |
| 1879 | listen app_ip1 |
| 1880 | bind 10.0.0.1:80 |
Willy Tarreau | bfcd311 | 2010-10-23 11:22:08 +0200 | [diff] [blame] | 1881 | bind-process odd |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1882 | |
| 1883 | listen app_ip2 |
| 1884 | bind 10.0.0.2:80 |
Willy Tarreau | bfcd311 | 2010-10-23 11:22:08 +0200 | [diff] [blame] | 1885 | bind-process even |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1886 | |
| 1887 | listen management |
| 1888 | bind 10.0.0.3:80 |
Willy Tarreau | bfcd311 | 2010-10-23 11:22:08 +0200 | [diff] [blame] | 1889 | bind-process 1 2 3 4 |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1890 | |
Willy Tarreau | 110ecc1 | 2012-11-15 17:50:01 +0100 | [diff] [blame] | 1891 | listen management |
| 1892 | bind 10.0.0.4:80 |
| 1893 | bind-process 1-4 |
| 1894 | |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 1895 | See also : "nbproc" in global section, and "process" in section 5.1. |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 1896 | |
| 1897 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1898 | block { if | unless } <condition> |
| 1899 | Block a layer 7 request if/unless a condition is matched |
| 1900 | May be used in sections : defaults | frontend | listen | backend |
| 1901 | no | yes | yes | yes |
| 1902 | |
| 1903 | The HTTP request will be blocked very early in the layer 7 processing |
| 1904 | if/unless <condition> is matched. A 403 error will be returned if the request |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1905 | is blocked. The condition has to reference ACLs (see section 7). This is |
Willy Tarreau | 3c92c5f | 2011-08-28 09:45:47 +0200 | [diff] [blame] | 1906 | typically used to deny access to certain sensitive resources if some |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1907 | conditions are met or not met. There is no fixed limit to the number of |
| 1908 | "block" statements per instance. |
| 1909 | |
| 1910 | Example: |
| 1911 | acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| 1912 | acl invalid_src src_port 0:1023 |
| 1913 | acl local_dst hdr(host) -i localhost |
| 1914 | block if invalid_src || local_dst |
| 1915 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1916 | See section 7 about ACL usage. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1917 | |
| 1918 | |
| 1919 | capture cookie <name> len <length> |
| 1920 | Capture and log a cookie in the request and in the response. |
| 1921 | May be used in sections : defaults | frontend | listen | backend |
| 1922 | no | yes | yes | no |
| 1923 | Arguments : |
| 1924 | <name> is the beginning of the name of the cookie to capture. In order |
| 1925 | to match the exact name, simply suffix the name with an equal |
| 1926 | sign ('='). The full name will appear in the logs, which is |
| 1927 | useful with application servers which adjust both the cookie name |
| 1928 | and value (eg: ASPSESSIONXXXXX). |
| 1929 | |
| 1930 | <length> is the maximum number of characters to report in the logs, which |
| 1931 | include the cookie name, the equal sign and the value, all in the |
| 1932 | standard "name=value" form. The string will be truncated on the |
| 1933 | right if it exceeds <length>. |
| 1934 | |
| 1935 | Only the first cookie is captured. Both the "cookie" request headers and the |
| 1936 | "set-cookie" response headers are monitored. This is particularly useful to |
| 1937 | check for application bugs causing session crossing or stealing between |
| 1938 | users, because generally the user's cookies can only change on a login page. |
| 1939 | |
| 1940 | When the cookie was not presented by the client, the associated log column |
| 1941 | will report "-". When a request does not cause a cookie to be assigned by the |
| 1942 | server, a "-" is reported in the response column. |
| 1943 | |
| 1944 | The capture is performed in the frontend only because it is necessary that |
| 1945 | the log format does not change for a given frontend depending on the |
| 1946 | backends. This may change in the future. Note that there can be only one |
Willy Tarreau | 193b8c6 | 2012-11-22 00:17:38 +0100 | [diff] [blame] | 1947 | "capture cookie" statement in a frontend. The maximum capture length is set |
| 1948 | by the global "tune.http.cookielen" setting and defaults to 63 characters. It |
| 1949 | is not possible to specify a capture in a "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1950 | |
| 1951 | Example: |
| 1952 | capture cookie ASPSESSION len 32 |
| 1953 | |
| 1954 | See also : "capture request header", "capture response header" as well as |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1955 | section 8 about logging. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1956 | |
| 1957 | |
| 1958 | capture request header <name> len <length> |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 1959 | Capture and log the last occurrence of the specified request header. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1960 | May be used in sections : defaults | frontend | listen | backend |
| 1961 | no | yes | yes | no |
| 1962 | Arguments : |
| 1963 | <name> is the name of the header to capture. The header names are not |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 1964 | case-sensitive, but it is a common practice to write them as they |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1965 | appear in the requests, with the first letter of each word in |
| 1966 | upper case. The header name will not appear in the logs, only the |
| 1967 | value is reported, but the position in the logs is respected. |
| 1968 | |
| 1969 | <length> is the maximum number of characters to extract from the value and |
| 1970 | report in the logs. The string will be truncated on the right if |
| 1971 | it exceeds <length>. |
| 1972 | |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 1973 | The complete value of the last occurrence of the header is captured. The |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1974 | value will be added to the logs between braces ('{}'). If multiple headers |
| 1975 | are captured, they will be delimited by a vertical bar ('|') and will appear |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 1976 | in the same order they were declared in the configuration. Non-existent |
| 1977 | headers will be logged just as an empty string. Common uses for request |
| 1978 | header captures include the "Host" field in virtual hosting environments, the |
| 1979 | "Content-length" when uploads are supported, "User-agent" to quickly |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 1980 | differentiate between real users and robots, and "X-Forwarded-For" in proxied |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 1981 | environments to find where the request came from. |
| 1982 | |
| 1983 | Note that when capturing headers such as "User-agent", some spaces may be |
| 1984 | logged, making the log analysis more difficult. Thus be careful about what |
| 1985 | you log if you know your log parser is not smart enough to rely on the |
| 1986 | braces. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1987 | |
Willy Tarreau | 0900abb | 2012-11-22 00:21:46 +0100 | [diff] [blame] | 1988 | There is no limit to the number of captured request headers nor to their |
| 1989 | length, though it is wise to keep them low to limit memory usage per session. |
| 1990 | In order to keep log format consistent for a same frontend, header captures |
| 1991 | can only be declared in a frontend. It is not possible to specify a capture |
| 1992 | in a "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1993 | |
| 1994 | Example: |
| 1995 | capture request header Host len 15 |
| 1996 | capture request header X-Forwarded-For len 15 |
| 1997 | capture request header Referrer len 15 |
| 1998 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1999 | See also : "capture cookie", "capture response header" as well as section 8 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2000 | about logging. |
| 2001 | |
| 2002 | |
| 2003 | capture response header <name> len <length> |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 2004 | Capture and log the last occurrence of the specified response header. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2005 | May be used in sections : defaults | frontend | listen | backend |
| 2006 | no | yes | yes | no |
| 2007 | Arguments : |
| 2008 | <name> is the name of the header to capture. The header names are not |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2009 | case-sensitive, but it is a common practice to write them as they |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2010 | appear in the response, with the first letter of each word in |
| 2011 | upper case. The header name will not appear in the logs, only the |
| 2012 | value is reported, but the position in the logs is respected. |
| 2013 | |
| 2014 | <length> is the maximum number of characters to extract from the value and |
| 2015 | report in the logs. The string will be truncated on the right if |
| 2016 | it exceeds <length>. |
| 2017 | |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 2018 | The complete value of the last occurrence of the header is captured. The |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2019 | result will be added to the logs between braces ('{}') after the captured |
| 2020 | request headers. If multiple headers are captured, they will be delimited by |
| 2021 | a vertical bar ('|') and will appear in the same order they were declared in |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 2022 | the configuration. Non-existent headers will be logged just as an empty |
| 2023 | string. Common uses for response header captures include the "Content-length" |
| 2024 | header which indicates how many bytes are expected to be returned, the |
| 2025 | "Location" header to track redirections. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2026 | |
Willy Tarreau | 0900abb | 2012-11-22 00:21:46 +0100 | [diff] [blame] | 2027 | There is no limit to the number of captured response headers nor to their |
| 2028 | length, though it is wise to keep them low to limit memory usage per session. |
| 2029 | In order to keep log format consistent for a same frontend, header captures |
| 2030 | can only be declared in a frontend. It is not possible to specify a capture |
| 2031 | in a "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2032 | |
| 2033 | Example: |
| 2034 | capture response header Content-length len 9 |
| 2035 | capture response header Location len 15 |
| 2036 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 2037 | See also : "capture cookie", "capture request header" as well as section 8 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2038 | about logging. |
| 2039 | |
| 2040 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2041 | clitimeout <timeout> (deprecated) |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2042 | Set the maximum inactivity time on the client side. |
| 2043 | May be used in sections : defaults | frontend | listen | backend |
| 2044 | yes | yes | yes | no |
| 2045 | Arguments : |
| 2046 | <timeout> is the timeout value is specified in milliseconds by default, but |
| 2047 | can be in any other unit if the number is suffixed by the unit, |
| 2048 | as explained at the top of this document. |
| 2049 | |
| 2050 | The inactivity timeout applies when the client is expected to acknowledge or |
| 2051 | send data. In HTTP mode, this timeout is particularly important to consider |
| 2052 | during the first phase, when the client sends the request, and during the |
| 2053 | response while it is reading data sent by the server. The value is specified |
| 2054 | in milliseconds by default, but can be in any other unit if the number is |
| 2055 | suffixed by the unit, as specified at the top of this document. In TCP mode |
| 2056 | (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| 2057 | client timeout remains equal to the server timeout in order to avoid complex |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2058 | situations to debug. It is a good practice to cover one or several TCP packet |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2059 | losses by specifying timeouts that are slightly above multiples of 3 seconds |
| 2060 | (eg: 4 or 5 seconds). |
| 2061 | |
| 2062 | This parameter is specific to frontends, but can be specified once for all in |
| 2063 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 2064 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 2065 | is not recommended. Such a usage is accepted and works but reports a warning |
| 2066 | during startup because it may results in accumulation of expired sessions in |
| 2067 | the system if the system's timeouts are not configured either. |
| 2068 | |
| 2069 | This parameter is provided for compatibility but is currently deprecated. |
| 2070 | Please use "timeout client" instead. |
| 2071 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 2072 | See also : "timeout client", "timeout http-request", "timeout server", and |
| 2073 | "srvtimeout". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2074 | |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 2075 | compression algo <algorithm> ... |
| 2076 | compression type <mime type> ... |
Willy Tarreau | 70737d1 | 2012-10-27 00:34:28 +0200 | [diff] [blame] | 2077 | compression offload |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 2078 | Enable HTTP compression. |
| 2079 | May be used in sections : defaults | frontend | listen | backend |
| 2080 | yes | yes | yes | yes |
| 2081 | Arguments : |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 2082 | algo is followed by the list of supported compression algorithms. |
| 2083 | type is followed by the list of MIME types that will be compressed. |
| 2084 | offload makes haproxy work as a compression offloader only (see notes). |
| 2085 | |
| 2086 | The currently supported algorithms are : |
Dmitry Sivachenko | 87c208b | 2012-11-22 20:03:26 +0400 | [diff] [blame] | 2087 | identity this is mostly for debugging, and it was useful for developing |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 2088 | the compression feature. Identity does not apply any change on |
| 2089 | data. |
| 2090 | |
| 2091 | gzip applies gzip compression. This setting is only available when |
| 2092 | support for zlib was built in. |
| 2093 | |
| 2094 | deflate same as gzip, but with deflate algorithm and zlib format. |
| 2095 | Note that this algorithm has ambiguous support on many browsers |
| 2096 | and no support at all from recent ones. It is strongly |
| 2097 | recommended not to use it for anything else than experimentation. |
| 2098 | This setting is only available when support for zlib was built |
| 2099 | in. |
| 2100 | |
Dmitry Sivachenko | 87c208b | 2012-11-22 20:03:26 +0400 | [diff] [blame] | 2101 | Compression will be activated depending on the Accept-Encoding request |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 2102 | header. With identity, it does not take care of that header. |
Dmitry Sivachenko | c9f3b45 | 2012-11-28 17:47:11 +0400 | [diff] [blame] | 2103 | If backend servers support HTTP compression, these directives |
| 2104 | will be no-op: haproxy will see the compressed response and will not |
| 2105 | compress again. If backend servers do not support HTTP compression and |
| 2106 | there is Accept-Encoding header in request, haproxy will compress the |
| 2107 | matching response. |
Willy Tarreau | 70737d1 | 2012-10-27 00:34:28 +0200 | [diff] [blame] | 2108 | |
| 2109 | The "offload" setting makes haproxy remove the Accept-Encoding header to |
| 2110 | prevent backend servers from compressing responses. It is strongly |
| 2111 | recommended not to do this because this means that all the compression work |
| 2112 | will be done on the single point where haproxy is located. However in some |
| 2113 | deployment scenarios, haproxy may be installed in front of a buggy gateway |
Dmitry Sivachenko | c9f3b45 | 2012-11-28 17:47:11 +0400 | [diff] [blame] | 2114 | with broken HTTP compression implementation which can't be turned off. |
| 2115 | In that case haproxy can be used to prevent that gateway from emitting |
| 2116 | invalid payloads. In this case, simply removing the header in the |
| 2117 | configuration does not work because it applies before the header is parsed, |
| 2118 | so that prevents haproxy from compressing. The "offload" setting should |
| 2119 | then be used for such scenarios. |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 2120 | |
William Lallemand | 0509744 | 2012-11-20 12:14:28 +0100 | [diff] [blame] | 2121 | Compression is disabled when: |
Baptiste Assmann | 650d53d | 2013-01-05 15:44:44 +0100 | [diff] [blame] | 2122 | * the request does not advertise a supported compression algorithm in the |
| 2123 | "Accept-Encoding" header |
| 2124 | * the response message is not HTTP/1.1 |
William Lallemand | d300261 | 2012-11-26 14:34:47 +0100 | [diff] [blame] | 2125 | * HTTP status code is not 200 |
William Lallemand | 8bb4e34 | 2013-12-10 17:28:48 +0100 | [diff] [blame] | 2126 | * response header "Transfer-Encoding" contains "chunked" (Temporary |
| 2127 | Workaround) |
Baptiste Assmann | 650d53d | 2013-01-05 15:44:44 +0100 | [diff] [blame] | 2128 | * response contain neither a "Content-Length" header nor a |
| 2129 | "Transfer-Encoding" whose last value is "chunked" |
| 2130 | * response contains a "Content-Type" header whose first value starts with |
| 2131 | "multipart" |
| 2132 | * the response contains the "no-transform" value in the "Cache-control" |
| 2133 | header |
| 2134 | * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7 |
| 2135 | and later |
| 2136 | * The response contains a "Content-Encoding" header, indicating that the |
| 2137 | response is already compressed (see compression offload) |
William Lallemand | 0509744 | 2012-11-20 12:14:28 +0100 | [diff] [blame] | 2138 | |
Baptiste Assmann | 650d53d | 2013-01-05 15:44:44 +0100 | [diff] [blame] | 2139 | Note: The compression does not rewrite Etag headers, and does not emit the |
| 2140 | Warning header. |
William Lallemand | 0509744 | 2012-11-20 12:14:28 +0100 | [diff] [blame] | 2141 | |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 2142 | Examples : |
| 2143 | compression algo gzip |
| 2144 | compression type text/html text/plain |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2145 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2146 | contimeout <timeout> (deprecated) |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2147 | Set the maximum time to wait for a connection attempt to a server to succeed. |
| 2148 | May be used in sections : defaults | frontend | listen | backend |
| 2149 | yes | no | yes | yes |
| 2150 | Arguments : |
| 2151 | <timeout> is the timeout value is specified in milliseconds by default, but |
| 2152 | can be in any other unit if the number is suffixed by the unit, |
| 2153 | as explained at the top of this document. |
| 2154 | |
| 2155 | If the server is located on the same LAN as haproxy, the connection should be |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2156 | immediate (less than a few milliseconds). Anyway, it is a good practice to |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 2157 | cover one or several TCP packet losses by specifying timeouts that are |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2158 | slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the |
| 2159 | connect timeout also presets the queue timeout to the same value if this one |
| 2160 | has not been specified. Historically, the contimeout was also used to set the |
| 2161 | tarpit timeout in a listen section, which is not possible in a pure frontend. |
| 2162 | |
| 2163 | This parameter is specific to backends, but can be specified once for all in |
| 2164 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 2165 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 2166 | is not recommended. Such a usage is accepted and works but reports a warning |
| 2167 | during startup because it may results in accumulation of failed sessions in |
| 2168 | the system if the system's timeouts are not configured either. |
| 2169 | |
| 2170 | This parameter is provided for backwards compatibility but is currently |
| 2171 | deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit" |
| 2172 | instead. |
| 2173 | |
| 2174 | See also : "timeout connect", "timeout queue", "timeout tarpit", |
| 2175 | "timeout server", "contimeout". |
| 2176 | |
| 2177 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 2178 | cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ] |
Willy Tarreau | 4992dd2 | 2012-05-31 21:02:17 +0200 | [diff] [blame] | 2179 | [ postonly ] [ preserve ] [ httponly ] [ secure ] |
| 2180 | [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2181 | Enable cookie-based persistence in a backend. |
| 2182 | May be used in sections : defaults | frontend | listen | backend |
| 2183 | yes | no | yes | yes |
| 2184 | Arguments : |
| 2185 | <name> is the name of the cookie which will be monitored, modified or |
| 2186 | inserted in order to bring persistence. This cookie is sent to |
| 2187 | the client via a "Set-Cookie" header in the response, and is |
| 2188 | brought back by the client in a "Cookie" header in all requests. |
| 2189 | Special care should be taken to choose a name which does not |
| 2190 | conflict with any likely application cookie. Also, if the same |
| 2191 | backends are subject to be used by the same clients (eg: |
| 2192 | HTTP/HTTPS), care should be taken to use different cookie names |
| 2193 | between all backends if persistence between them is not desired. |
| 2194 | |
| 2195 | rewrite This keyword indicates that the cookie will be provided by the |
| 2196 | server and that haproxy will have to modify its value to set the |
| 2197 | server's identifier in it. This mode is handy when the management |
| 2198 | of complex combinations of "Set-cookie" and "Cache-control" |
| 2199 | headers is left to the application. The application can then |
| 2200 | decide whether or not it is appropriate to emit a persistence |
| 2201 | cookie. Since all responses should be monitored, this mode only |
| 2202 | works in HTTP close mode. Unless the application behaviour is |
| 2203 | very complex and/or broken, it is advised not to start with this |
| 2204 | mode for new deployments. This keyword is incompatible with |
| 2205 | "insert" and "prefix". |
| 2206 | |
| 2207 | insert This keyword indicates that the persistence cookie will have to |
Willy Tarreau | a79094d | 2010-08-31 22:54:15 +0200 | [diff] [blame] | 2208 | be inserted by haproxy in server responses if the client did not |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 2209 | |
Willy Tarreau | a79094d | 2010-08-31 22:54:15 +0200 | [diff] [blame] | 2210 | already have a cookie that would have permitted it to access this |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 2211 | server. When used without the "preserve" option, if the server |
| 2212 | emits a cookie with the same name, it will be remove before |
| 2213 | processing. For this reason, this mode can be used to upgrade |
| 2214 | existing configurations running in the "rewrite" mode. The cookie |
| 2215 | will only be a session cookie and will not be stored on the |
| 2216 | client's disk. By default, unless the "indirect" option is added, |
| 2217 | the server will see the cookies emitted by the client. Due to |
| 2218 | caching effects, it is generally wise to add the "nocache" or |
| 2219 | "postonly" keywords (see below). The "insert" keyword is not |
| 2220 | compatible with "rewrite" and "prefix". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2221 | |
| 2222 | prefix This keyword indicates that instead of relying on a dedicated |
| 2223 | cookie for the persistence, an existing one will be completed. |
| 2224 | This may be needed in some specific environments where the client |
| 2225 | does not support more than one single cookie and the application |
| 2226 | already needs it. In this case, whenever the server sets a cookie |
| 2227 | named <name>, it will be prefixed with the server's identifier |
| 2228 | and a delimiter. The prefix will be removed from all client |
| 2229 | requests so that the server still finds the cookie it emitted. |
| 2230 | Since all requests and responses are subject to being modified, |
| 2231 | this mode requires the HTTP close mode. The "prefix" keyword is |
Willy Tarreau | 37229df | 2011-10-17 12:24:55 +0200 | [diff] [blame] | 2232 | not compatible with "rewrite" and "insert". Note: it is highly |
| 2233 | recommended not to use "indirect" with "prefix", otherwise server |
| 2234 | cookie updates would not be sent to clients. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2235 | |
Willy Tarreau | a79094d | 2010-08-31 22:54:15 +0200 | [diff] [blame] | 2236 | indirect When this option is specified, no cookie will be emitted to a |
| 2237 | client which already has a valid one for the server which has |
| 2238 | processed the request. If the server sets such a cookie itself, |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 2239 | it will be removed, unless the "preserve" option is also set. In |
| 2240 | "insert" mode, this will additionally remove cookies from the |
| 2241 | requests transmitted to the server, making the persistence |
| 2242 | mechanism totally transparent from an application point of view. |
Willy Tarreau | 37229df | 2011-10-17 12:24:55 +0200 | [diff] [blame] | 2243 | Note: it is highly recommended not to use "indirect" with |
| 2244 | "prefix", otherwise server cookie updates would not be sent to |
| 2245 | clients. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2246 | |
| 2247 | nocache This option is recommended in conjunction with the insert mode |
| 2248 | when there is a cache between the client and HAProxy, as it |
| 2249 | ensures that a cacheable response will be tagged non-cacheable if |
| 2250 | a cookie needs to be inserted. This is important because if all |
| 2251 | persistence cookies are added on a cacheable home page for |
| 2252 | instance, then all customers will then fetch the page from an |
| 2253 | outer cache and will all share the same persistence cookie, |
| 2254 | leading to one server receiving much more traffic than others. |
| 2255 | See also the "insert" and "postonly" options. |
| 2256 | |
| 2257 | postonly This option ensures that cookie insertion will only be performed |
| 2258 | on responses to POST requests. It is an alternative to the |
| 2259 | "nocache" option, because POST responses are not cacheable, so |
| 2260 | this ensures that the persistence cookie will never get cached. |
| 2261 | Since most sites do not need any sort of persistence before the |
| 2262 | first POST which generally is a login request, this is a very |
| 2263 | efficient method to optimize caching without risking to find a |
| 2264 | persistence cookie in the cache. |
| 2265 | See also the "insert" and "nocache" options. |
| 2266 | |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 2267 | preserve This option may only be used with "insert" and/or "indirect". It |
| 2268 | allows the server to emit the persistence cookie itself. In this |
| 2269 | case, if a cookie is found in the response, haproxy will leave it |
| 2270 | untouched. This is useful in order to end persistence after a |
| 2271 | logout request for instance. For this, the server just has to |
| 2272 | emit a cookie with an invalid value (eg: empty) or with a date in |
| 2273 | the past. By combining this mechanism with the "disable-on-404" |
| 2274 | check option, it is possible to perform a completely graceful |
| 2275 | shutdown because users will definitely leave the server after |
| 2276 | they logout. |
| 2277 | |
Willy Tarreau | 4992dd2 | 2012-05-31 21:02:17 +0200 | [diff] [blame] | 2278 | httponly This option tells haproxy to add an "HttpOnly" cookie attribute |
| 2279 | when a cookie is inserted. This attribute is used so that a |
| 2280 | user agent doesn't share the cookie with non-HTTP components. |
| 2281 | Please check RFC6265 for more information on this attribute. |
| 2282 | |
| 2283 | secure This option tells haproxy to add a "Secure" cookie attribute when |
| 2284 | a cookie is inserted. This attribute is used so that a user agent |
| 2285 | never emits this cookie over non-secure channels, which means |
| 2286 | that a cookie learned with this flag will be presented only over |
| 2287 | SSL/TLS connections. Please check RFC6265 for more information on |
| 2288 | this attribute. |
| 2289 | |
Krzysztof Piotr Oledzki | efe3b6f | 2008-05-23 23:49:32 +0200 | [diff] [blame] | 2290 | domain This option allows to specify the domain at which a cookie is |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 2291 | inserted. It requires exactly one parameter: a valid domain |
Willy Tarreau | 68a897b | 2009-12-03 23:28:34 +0100 | [diff] [blame] | 2292 | name. If the domain begins with a dot, the browser is allowed to |
| 2293 | use it for any host ending with that name. It is also possible to |
| 2294 | specify several domain names by invoking this option multiple |
| 2295 | times. Some browsers might have small limits on the number of |
| 2296 | domains, so be careful when doing that. For the record, sending |
| 2297 | 10 domains to MSIE 6 or Firefox 2 works as expected. |
Krzysztof Piotr Oledzki | efe3b6f | 2008-05-23 23:49:32 +0200 | [diff] [blame] | 2298 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 2299 | maxidle This option allows inserted cookies to be ignored after some idle |
| 2300 | time. It only works with insert-mode cookies. When a cookie is |
| 2301 | sent to the client, the date this cookie was emitted is sent too. |
| 2302 | Upon further presentations of this cookie, if the date is older |
| 2303 | than the delay indicated by the parameter (in seconds), it will |
| 2304 | be ignored. Otherwise, it will be refreshed if needed when the |
| 2305 | response is sent to the client. This is particularly useful to |
| 2306 | prevent users who never close their browsers from remaining for |
| 2307 | too long on the same server (eg: after a farm size change). When |
| 2308 | this option is set and a cookie has no date, it is always |
| 2309 | accepted, but gets refreshed in the response. This maintains the |
| 2310 | ability for admins to access their sites. Cookies that have a |
| 2311 | date in the future further than 24 hours are ignored. Doing so |
| 2312 | lets admins fix timezone issues without risking kicking users off |
| 2313 | the site. |
| 2314 | |
| 2315 | maxlife This option allows inserted cookies to be ignored after some life |
| 2316 | time, whether they're in use or not. It only works with insert |
| 2317 | mode cookies. When a cookie is first sent to the client, the date |
| 2318 | this cookie was emitted is sent too. Upon further presentations |
| 2319 | of this cookie, if the date is older than the delay indicated by |
| 2320 | the parameter (in seconds), it will be ignored. If the cookie in |
| 2321 | the request has no date, it is accepted and a date will be set. |
| 2322 | Cookies that have a date in the future further than 24 hours are |
| 2323 | ignored. Doing so lets admins fix timezone issues without risking |
| 2324 | kicking users off the site. Contrary to maxidle, this value is |
| 2325 | not refreshed, only the first visit date counts. Both maxidle and |
| 2326 | maxlife may be used at the time. This is particularly useful to |
| 2327 | prevent users who never close their browsers from remaining for |
| 2328 | too long on the same server (eg: after a farm size change). This |
| 2329 | is stronger than the maxidle method in that it forces a |
| 2330 | redispatch after some absolute delay. |
| 2331 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2332 | There can be only one persistence cookie per HTTP backend, and it can be |
| 2333 | declared in a defaults section. The value of the cookie will be the value |
| 2334 | indicated after the "cookie" keyword in a "server" statement. If no cookie |
| 2335 | is declared for a given server, the cookie is not set. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2336 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2337 | Examples : |
| 2338 | cookie JSESSIONID prefix |
| 2339 | cookie SRV insert indirect nocache |
| 2340 | cookie SRV insert postonly indirect |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 2341 | cookie SRV insert indirect nocache maxidle 30m maxlife 8h |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2342 | |
Cyril Bonté | a8e7bbc | 2010-04-25 22:29:29 +0200 | [diff] [blame] | 2343 | See also : "appsession", "balance source", "capture cookie", "server" |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 2344 | and "ignore-persist". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2345 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 2346 | |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 2347 | default-server [param*] |
| 2348 | Change default options for a server in a backend |
| 2349 | May be used in sections : defaults | frontend | listen | backend |
| 2350 | yes | no | yes | yes |
| 2351 | Arguments: |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 2352 | <param*> is a list of parameters for this server. The "default-server" |
| 2353 | keyword accepts an important number of options and has a complete |
| 2354 | section dedicated to it. Please refer to section 5 for more |
| 2355 | details. |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 2356 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 2357 | Example : |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 2358 | default-server inter 1000 weight 13 |
| 2359 | |
| 2360 | See also: "server" and section 5 about server options |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2361 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 2362 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2363 | default_backend <backend> |
| 2364 | Specify the backend to use when no "use_backend" rule has been matched. |
| 2365 | May be used in sections : defaults | frontend | listen | backend |
| 2366 | yes | yes | yes | no |
| 2367 | Arguments : |
| 2368 | <backend> is the name of the backend to use. |
| 2369 | |
| 2370 | When doing content-switching between frontend and backends using the |
| 2371 | "use_backend" keyword, it is often useful to indicate which backend will be |
| 2372 | used when no rule has matched. It generally is the dynamic backend which |
| 2373 | will catch all undetermined requests. |
| 2374 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2375 | Example : |
| 2376 | |
| 2377 | use_backend dynamic if url_dyn |
| 2378 | use_backend static if url_css url_img extension_img |
| 2379 | default_backend dynamic |
| 2380 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2381 | See also : "use_backend", "reqsetbe", "reqisetbe" |
| 2382 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2383 | |
Baptiste Assmann | 27f5134 | 2013-10-09 06:51:49 +0200 | [diff] [blame] | 2384 | description <string> |
| 2385 | Describe a listen, frontend or backend. |
| 2386 | May be used in sections : defaults | frontend | listen | backend |
| 2387 | no | yes | yes | yes |
| 2388 | Arguments : string |
| 2389 | |
| 2390 | Allows to add a sentence to describe the related object in the HAProxy HTML |
| 2391 | stats page. The description will be printed on the right of the object name |
| 2392 | it describes. |
| 2393 | No need to backslash spaces in the <string> arguments. |
| 2394 | |
| 2395 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2396 | disabled |
| 2397 | Disable a proxy, frontend or backend. |
| 2398 | May be used in sections : defaults | frontend | listen | backend |
| 2399 | yes | yes | yes | yes |
| 2400 | Arguments : none |
| 2401 | |
| 2402 | The "disabled" keyword is used to disable an instance, mainly in order to |
| 2403 | liberate a listening port or to temporarily disable a service. The instance |
| 2404 | will still be created and its configuration will be checked, but it will be |
| 2405 | created in the "stopped" state and will appear as such in the statistics. It |
| 2406 | will not receive any traffic nor will it send any health-checks or logs. It |
| 2407 | is possible to disable many instances at once by adding the "disabled" |
| 2408 | keyword in a "defaults" section. |
| 2409 | |
| 2410 | See also : "enabled" |
| 2411 | |
| 2412 | |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 2413 | dispatch <address>:<port> |
| 2414 | Set a default server address |
| 2415 | May be used in sections : defaults | frontend | listen | backend |
| 2416 | no | no | yes | yes |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 2417 | Arguments : |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 2418 | |
| 2419 | <address> is the IPv4 address of the default server. Alternatively, a |
| 2420 | resolvable hostname is supported, but this name will be resolved |
| 2421 | during start-up. |
| 2422 | |
| 2423 | <ports> is a mandatory port specification. All connections will be sent |
| 2424 | to this port, and it is not permitted to use port offsets as is |
| 2425 | possible with normal servers. |
| 2426 | |
Willy Tarreau | 787aed5 | 2011-04-15 06:45:37 +0200 | [diff] [blame] | 2427 | The "dispatch" keyword designates a default server for use when no other |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 2428 | server can take the connection. In the past it was used to forward non |
| 2429 | persistent connections to an auxiliary load balancer. Due to its simple |
| 2430 | syntax, it has also been used for simple TCP relays. It is recommended not to |
| 2431 | use it for more clarity, and to use the "server" directive instead. |
| 2432 | |
| 2433 | See also : "server" |
| 2434 | |
| 2435 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2436 | enabled |
| 2437 | Enable a proxy, frontend or backend. |
| 2438 | May be used in sections : defaults | frontend | listen | backend |
| 2439 | yes | yes | yes | yes |
| 2440 | Arguments : none |
| 2441 | |
| 2442 | The "enabled" keyword is used to explicitly enable an instance, when the |
| 2443 | defaults has been set to "disabled". This is very rarely used. |
| 2444 | |
| 2445 | See also : "disabled" |
| 2446 | |
| 2447 | |
| 2448 | errorfile <code> <file> |
| 2449 | Return a file contents instead of errors generated by HAProxy |
| 2450 | May be used in sections : defaults | frontend | listen | backend |
| 2451 | yes | yes | yes | yes |
| 2452 | Arguments : |
| 2453 | <code> is the HTTP status code. Currently, HAProxy is capable of |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 2454 | generating codes 200, 400, 403, 408, 500, 502, 503, and 504. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2455 | |
| 2456 | <file> designates a file containing the full HTTP response. It is |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2457 | recommended to follow the common practice of appending ".http" to |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2458 | the filename so that people do not confuse the response with HTML |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 2459 | error pages, and to use absolute paths, since files are read |
| 2460 | before any chroot is performed. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2461 | |
| 2462 | It is important to understand that this keyword is not meant to rewrite |
| 2463 | errors returned by the server, but errors detected and returned by HAProxy. |
| 2464 | This is why the list of supported errors is limited to a small set. |
| 2465 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 2466 | Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| 2467 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2468 | The files are returned verbatim on the TCP socket. This allows any trick such |
| 2469 | as redirections to another URL or site, as well as tricks to clean cookies, |
| 2470 | force enable or disable caching, etc... The package provides default error |
| 2471 | files returning the same contents as default errors. |
| 2472 | |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 2473 | The files should not exceed the configured buffer size (BUFSIZE), which |
| 2474 | generally is 8 or 16 kB, otherwise they will be truncated. It is also wise |
| 2475 | not to put any reference to local contents (eg: images) in order to avoid |
| 2476 | loops between the client and HAProxy when all servers are down, causing an |
| 2477 | error to be returned instead of an image. For better HTTP compliance, it is |
| 2478 | recommended that all header lines end with CR-LF and not LF alone. |
| 2479 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2480 | The files are read at the same time as the configuration and kept in memory. |
| 2481 | For this reason, the errors continue to be returned even when the process is |
| 2482 | chrooted, and no file change is considered while the process is running. A |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 2483 | simple method for developing those files consists in associating them to the |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2484 | 403 status code and interrogating a blocked URL. |
| 2485 | |
| 2486 | See also : "errorloc", "errorloc302", "errorloc303" |
| 2487 | |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 2488 | Example : |
| 2489 | errorfile 400 /etc/haproxy/errorfiles/400badreq.http |
| 2490 | errorfile 403 /etc/haproxy/errorfiles/403forbid.http |
| 2491 | errorfile 503 /etc/haproxy/errorfiles/503sorry.http |
| 2492 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2493 | |
| 2494 | errorloc <code> <url> |
| 2495 | errorloc302 <code> <url> |
| 2496 | Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| 2497 | May be used in sections : defaults | frontend | listen | backend |
| 2498 | yes | yes | yes | yes |
| 2499 | Arguments : |
| 2500 | <code> is the HTTP status code. Currently, HAProxy is capable of |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 2501 | generating codes 200, 400, 403, 408, 500, 502, 503, and 504. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2502 | |
| 2503 | <url> it is the exact contents of the "Location" header. It may contain |
| 2504 | either a relative URI to an error page hosted on the same site, |
| 2505 | or an absolute URI designating an error page on another site. |
| 2506 | Special care should be given to relative URIs to avoid redirect |
| 2507 | loops if the URI itself may generate the same error (eg: 500). |
| 2508 | |
| 2509 | It is important to understand that this keyword is not meant to rewrite |
| 2510 | errors returned by the server, but errors detected and returned by HAProxy. |
| 2511 | This is why the list of supported errors is limited to a small set. |
| 2512 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 2513 | Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| 2514 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2515 | Note that both keyword return the HTTP 302 status code, which tells the |
| 2516 | client to fetch the designated URL using the same HTTP method. This can be |
| 2517 | quite problematic in case of non-GET methods such as POST, because the URL |
| 2518 | sent to the client might not be allowed for something other than GET. To |
| 2519 | workaround this problem, please use "errorloc303" which send the HTTP 303 |
| 2520 | status code, indicating to the client that the URL must be fetched with a GET |
| 2521 | request. |
| 2522 | |
| 2523 | See also : "errorfile", "errorloc303" |
| 2524 | |
| 2525 | |
| 2526 | errorloc303 <code> <url> |
| 2527 | Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| 2528 | May be used in sections : defaults | frontend | listen | backend |
| 2529 | yes | yes | yes | yes |
| 2530 | Arguments : |
| 2531 | <code> is the HTTP status code. Currently, HAProxy is capable of |
| 2532 | generating codes 400, 403, 408, 500, 502, 503, and 504. |
| 2533 | |
| 2534 | <url> it is the exact contents of the "Location" header. It may contain |
| 2535 | either a relative URI to an error page hosted on the same site, |
| 2536 | or an absolute URI designating an error page on another site. |
| 2537 | Special care should be given to relative URIs to avoid redirect |
| 2538 | loops if the URI itself may generate the same error (eg: 500). |
| 2539 | |
| 2540 | It is important to understand that this keyword is not meant to rewrite |
| 2541 | errors returned by the server, but errors detected and returned by HAProxy. |
| 2542 | This is why the list of supported errors is limited to a small set. |
| 2543 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 2544 | Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| 2545 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2546 | Note that both keyword return the HTTP 303 status code, which tells the |
| 2547 | client to fetch the designated URL using the same HTTP GET method. This |
| 2548 | solves the usual problems associated with "errorloc" and the 302 code. It is |
| 2549 | possible that some very old browsers designed before HTTP/1.1 do not support |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2550 | it, but no such problem has been reported till now. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2551 | |
| 2552 | See also : "errorfile", "errorloc", "errorloc302" |
| 2553 | |
| 2554 | |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 2555 | force-persist { if | unless } <condition> |
| 2556 | Declare a condition to force persistence on down servers |
| 2557 | May be used in sections: defaults | frontend | listen | backend |
| 2558 | no | yes | yes | yes |
| 2559 | |
| 2560 | By default, requests are not dispatched to down servers. It is possible to |
| 2561 | force this using "option persist", but it is unconditional and redispatches |
| 2562 | to a valid server if "option redispatch" is set. That leaves with very little |
| 2563 | possibilities to force some requests to reach a server which is artificially |
| 2564 | marked down for maintenance operations. |
| 2565 | |
| 2566 | The "force-persist" statement allows one to declare various ACL-based |
| 2567 | conditions which, when met, will cause a request to ignore the down status of |
| 2568 | a server and still try to connect to it. That makes it possible to start a |
| 2569 | server, still replying an error to the health checks, and run a specially |
| 2570 | configured browser to test the service. Among the handy methods, one could |
| 2571 | use a specific source IP address, or a specific cookie. The cookie also has |
| 2572 | the advantage that it can easily be added/removed on the browser from a test |
| 2573 | page. Once the service is validated, it is then possible to open the service |
| 2574 | to the world by returning a valid response to health checks. |
| 2575 | |
| 2576 | The forced persistence is enabled when an "if" condition is met, or unless an |
| 2577 | "unless" condition is met. The final redispatch is always disabled when this |
| 2578 | is used. |
| 2579 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 2580 | See also : "option redispatch", "ignore-persist", "persist", |
Cyril Bonté | a8e7bbc | 2010-04-25 22:29:29 +0200 | [diff] [blame] | 2581 | and section 7 about ACL usage. |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 2582 | |
| 2583 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2584 | fullconn <conns> |
| 2585 | Specify at what backend load the servers will reach their maxconn |
| 2586 | May be used in sections : defaults | frontend | listen | backend |
| 2587 | yes | no | yes | yes |
| 2588 | Arguments : |
| 2589 | <conns> is the number of connections on the backend which will make the |
| 2590 | servers use the maximal number of connections. |
| 2591 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 2592 | When a server has a "maxconn" parameter specified, it means that its number |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2593 | of concurrent connections will never go higher. Additionally, if it has a |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 2594 | "minconn" parameter, it indicates a dynamic limit following the backend's |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2595 | load. The server will then always accept at least <minconn> connections, |
| 2596 | never more than <maxconn>, and the limit will be on the ramp between both |
| 2597 | values when the backend has less than <conns> concurrent connections. This |
| 2598 | makes it possible to limit the load on the servers during normal loads, but |
| 2599 | push it further for important loads without overloading the servers during |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 2600 | exceptional loads. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2601 | |
Willy Tarreau | fbb7842 | 2011-06-05 15:38:35 +0200 | [diff] [blame] | 2602 | Since it's hard to get this value right, haproxy automatically sets it to |
| 2603 | 10% of the sum of the maxconns of all frontends that may branch to this |
Bertrand Jacquin | 702d44f | 2013-11-19 11:43:06 +0100 | [diff] [blame] | 2604 | backend (based on "use_backend" and "default_backend" rules). That way it's |
| 2605 | safe to leave it unset. However, "use_backend" involving dynamic names are |
| 2606 | not counted since there is no way to know if they could match or not. |
Willy Tarreau | fbb7842 | 2011-06-05 15:38:35 +0200 | [diff] [blame] | 2607 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2608 | Example : |
| 2609 | # The servers will accept between 100 and 1000 concurrent connections each |
| 2610 | # and the maximum of 1000 will be reached when the backend reaches 10000 |
| 2611 | # connections. |
| 2612 | backend dynamic |
| 2613 | fullconn 10000 |
| 2614 | server srv1 dyn1:80 minconn 100 maxconn 1000 |
| 2615 | server srv2 dyn2:80 minconn 100 maxconn 1000 |
| 2616 | |
| 2617 | See also : "maxconn", "server" |
| 2618 | |
| 2619 | |
| 2620 | grace <time> |
| 2621 | Maintain a proxy operational for some time after a soft stop |
| 2622 | May be used in sections : defaults | frontend | listen | backend |
Cyril Bonté | 99ed327 | 2010-01-24 23:29:44 +0100 | [diff] [blame] | 2623 | yes | yes | yes | yes |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2624 | Arguments : |
| 2625 | <time> is the time (by default in milliseconds) for which the instance |
| 2626 | will remain operational with the frontend sockets still listening |
| 2627 | when a soft-stop is received via the SIGUSR1 signal. |
| 2628 | |
| 2629 | This may be used to ensure that the services disappear in a certain order. |
| 2630 | This was designed so that frontends which are dedicated to monitoring by an |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 2631 | external equipment fail immediately while other ones remain up for the time |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2632 | needed by the equipment to detect the failure. |
| 2633 | |
| 2634 | Note that currently, there is very little benefit in using this parameter, |
| 2635 | and it may in fact complicate the soft-reconfiguration process more than |
| 2636 | simplify it. |
| 2637 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2638 | |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 2639 | hash-type <method> <function> <modifier> |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 2640 | Specify a method to use for mapping hashes to servers |
| 2641 | May be used in sections : defaults | frontend | listen | backend |
| 2642 | yes | no | yes | yes |
| 2643 | Arguments : |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2644 | <method> is the method used to select a server from the hash computed by |
| 2645 | the <function> : |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 2646 | |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2647 | map-based the hash table is a static array containing all alive servers. |
| 2648 | The hashes will be very smooth, will consider weights, but |
| 2649 | will be static in that weight changes while a server is up |
| 2650 | will be ignored. This means that there will be no slow start. |
| 2651 | Also, since a server is selected by its position in the array, |
| 2652 | most mappings are changed when the server count changes. This |
| 2653 | means that when a server goes up or down, or when a server is |
| 2654 | added to a farm, most connections will be redistributed to |
| 2655 | different servers. This can be inconvenient with caches for |
| 2656 | instance. |
Willy Tarreau | 798a39c | 2010-11-24 15:04:29 +0100 | [diff] [blame] | 2657 | |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2658 | consistent the hash table is a tree filled with many occurrences of each |
| 2659 | server. The hash key is looked up in the tree and the closest |
| 2660 | server is chosen. This hash is dynamic, it supports changing |
| 2661 | weights while the servers are up, so it is compatible with the |
| 2662 | slow start feature. It has the advantage that when a server |
| 2663 | goes up or down, only its associations are moved. When a |
| 2664 | server is added to the farm, only a few part of the mappings |
| 2665 | are redistributed, making it an ideal method for caches. |
| 2666 | However, due to its principle, the distribution will never be |
| 2667 | very smooth and it may sometimes be necessary to adjust a |
| 2668 | server's weight or its ID to get a more balanced distribution. |
| 2669 | In order to get the same distribution on multiple load |
| 2670 | balancers, it is important that all servers have the exact |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 2671 | same IDs. Note: consistent hash uses sdbm and avalanche if no |
| 2672 | hash function is specified. |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2673 | |
| 2674 | <function> is the hash function to be used : |
| 2675 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 2676 | sdbm this function was created initially for sdbm (a public-domain |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2677 | reimplementation of ndbm) database library. It was found to do |
| 2678 | well in scrambling bits, causing better distribution of the keys |
| 2679 | and fewer splits. It also happens to be a good general hashing |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 2680 | function with good distribution, unless the total server weight |
| 2681 | is a multiple of 64, in which case applying the avalanche |
| 2682 | modifier may help. |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2683 | |
| 2684 | djb2 this function was first proposed by Dan Bernstein many years ago |
| 2685 | on comp.lang.c. Studies have shown that for certain workload this |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 2686 | function provides a better distribution than sdbm. It generally |
| 2687 | works well with text-based inputs though it can perform extremely |
| 2688 | poorly with numeric-only input or when the total server weight is |
| 2689 | a multiple of 33, unless the avalanche modifier is also used. |
| 2690 | |
Willy Tarreau | a0f4271 | 2013-11-14 14:30:35 +0100 | [diff] [blame] | 2691 | wt6 this function was designed for haproxy while testing other |
| 2692 | functions in the past. It is not as smooth as the other ones, but |
| 2693 | is much less sensible to the input data set or to the number of |
| 2694 | servers. It can make sense as an alternative to sdbm+avalanche or |
| 2695 | djb2+avalanche for consistent hashing or when hashing on numeric |
| 2696 | data such as a source IP address or a visitor identifier in a URL |
| 2697 | parameter. |
| 2698 | |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 2699 | <modifier> indicates an optional method applied after hashing the key : |
| 2700 | |
| 2701 | avalanche This directive indicates that the result from the hash |
| 2702 | function above should not be used in its raw form but that |
| 2703 | a 4-byte full avalanche hash must be applied first. The |
| 2704 | purpose of this step is to mix the resulting bits from the |
| 2705 | previous hash in order to avoid any undesired effect when |
| 2706 | the input contains some limited values or when the number of |
| 2707 | servers is a multiple of one of the hash's components (64 |
| 2708 | for SDBM, 33 for DJB2). Enabling avalanche tends to make the |
| 2709 | result less predictable, but it's also not as smooth as when |
| 2710 | using the original function. Some testing might be needed |
| 2711 | with some workloads. This hash is one of the many proposed |
| 2712 | by Bob Jenkins. |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 2713 | |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 2714 | The default hash type is "map-based" and is recommended for most usages. The |
| 2715 | default function is "sdbm", the selection of a function should be based on |
| 2716 | the range of the values being hashed. |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 2717 | |
| 2718 | See also : "balance", "server" |
| 2719 | |
| 2720 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2721 | http-check disable-on-404 |
| 2722 | Enable a maintenance mode upon HTTP/404 response to health-checks |
| 2723 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2724 | yes | no | yes | yes |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2725 | Arguments : none |
| 2726 | |
| 2727 | When this option is set, a server which returns an HTTP code 404 will be |
| 2728 | excluded from further load-balancing, but will still receive persistent |
| 2729 | connections. This provides a very convenient method for Web administrators |
| 2730 | to perform a graceful shutdown of their servers. It is also important to note |
| 2731 | that a server which is detected as failed while it was in this mode will not |
| 2732 | generate an alert, just a notice. If the server responds 2xx or 3xx again, it |
| 2733 | will immediately be reinserted into the farm. The status on the stats page |
| 2734 | reports "NOLB" for a server in this mode. It is important to note that this |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2735 | option only works in conjunction with the "httpchk" option. If this option |
| 2736 | is used with "http-check expect", then it has precedence over it so that 404 |
| 2737 | responses will still be considered as soft-stop. |
| 2738 | |
| 2739 | See also : "option httpchk", "http-check expect" |
| 2740 | |
| 2741 | |
| 2742 | http-check expect [!] <match> <pattern> |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2743 | Make HTTP health checks consider response contents or specific status codes |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2744 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 1ee51a6 | 2011-08-19 20:04:17 +0200 | [diff] [blame] | 2745 | yes | no | yes | yes |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2746 | Arguments : |
| 2747 | <match> is a keyword indicating how to look for a specific pattern in the |
| 2748 | response. The keyword may be one of "status", "rstatus", |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2749 | "string", or "rstring". The keyword may be preceded by an |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2750 | exclamation mark ("!") to negate the match. Spaces are allowed |
| 2751 | between the exclamation mark and the keyword. See below for more |
| 2752 | details on the supported keywords. |
| 2753 | |
| 2754 | <pattern> is the pattern to look for. It may be a string or a regular |
| 2755 | expression. If the pattern contains spaces, they must be escaped |
| 2756 | with the usual backslash ('\'). |
| 2757 | |
| 2758 | By default, "option httpchk" considers that response statuses 2xx and 3xx |
| 2759 | are valid, and that others are invalid. When "http-check expect" is used, |
| 2760 | it defines what is considered valid or invalid. Only one "http-check" |
| 2761 | statement is supported in a backend. If a server fails to respond or times |
| 2762 | out, the check obviously fails. The available matches are : |
| 2763 | |
| 2764 | status <string> : test the exact string match for the HTTP status code. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2765 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2766 | response's status code is exactly this string. If the |
| 2767 | "status" keyword is prefixed with "!", then the response |
| 2768 | will be considered invalid if the status code matches. |
| 2769 | |
| 2770 | rstatus <regex> : test a regular expression for the HTTP status code. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2771 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2772 | response's status code matches the expression. If the |
| 2773 | "rstatus" keyword is prefixed with "!", then the response |
| 2774 | will be considered invalid if the status code matches. |
| 2775 | This is mostly used to check for multiple codes. |
| 2776 | |
| 2777 | string <string> : test the exact string match in the HTTP response body. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2778 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2779 | response's body contains this exact string. If the |
| 2780 | "string" keyword is prefixed with "!", then the response |
| 2781 | will be considered invalid if the body contains this |
| 2782 | string. This can be used to look for a mandatory word at |
| 2783 | the end of a dynamic page, or to detect a failure when a |
| 2784 | specific error appears on the check page (eg: a stack |
| 2785 | trace). |
| 2786 | |
| 2787 | rstring <regex> : test a regular expression on the HTTP response body. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2788 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2789 | response's body matches this expression. If the "rstring" |
| 2790 | keyword is prefixed with "!", then the response will be |
| 2791 | considered invalid if the body matches the expression. |
| 2792 | This can be used to look for a mandatory word at the end |
| 2793 | of a dynamic page, or to detect a failure when a specific |
| 2794 | error appears on the check page (eg: a stack trace). |
| 2795 | |
| 2796 | It is important to note that the responses will be limited to a certain size |
| 2797 | defined by the global "tune.chksize" option, which defaults to 16384 bytes. |
| 2798 | Thus, too large responses may not contain the mandatory pattern when using |
| 2799 | "string" or "rstring". If a large response is absolutely required, it is |
| 2800 | possible to change the default max size by setting the global variable. |
| 2801 | However, it is worth keeping in mind that parsing very large responses can |
| 2802 | waste some CPU cycles, especially when regular expressions are used, and that |
| 2803 | it is always better to focus the checks on smaller resources. |
| 2804 | |
| 2805 | Last, if "http-check expect" is combined with "http-check disable-on-404", |
| 2806 | then this last one has precedence when the server responds with 404. |
| 2807 | |
| 2808 | Examples : |
| 2809 | # only accept status 200 as valid |
Willy Tarreau | 8f2a1e7 | 2011-01-06 16:36:10 +0100 | [diff] [blame] | 2810 | http-check expect status 200 |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2811 | |
| 2812 | # consider SQL errors as errors |
Willy Tarreau | 8f2a1e7 | 2011-01-06 16:36:10 +0100 | [diff] [blame] | 2813 | http-check expect ! string SQL\ Error |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2814 | |
| 2815 | # consider status 5xx only as errors |
Willy Tarreau | 8f2a1e7 | 2011-01-06 16:36:10 +0100 | [diff] [blame] | 2816 | http-check expect ! rstatus ^5 |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2817 | |
| 2818 | # check that we have a correct hexadecimal tag before /html |
Willy Tarreau | 8f2a1e7 | 2011-01-06 16:36:10 +0100 | [diff] [blame] | 2819 | http-check expect rstring <!--tag:[0-9a-f]*</html> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2820 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 2821 | See also : "option httpchk", "http-check disable-on-404" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 2822 | |
| 2823 | |
Willy Tarreau | ef78104 | 2010-01-27 11:53:01 +0100 | [diff] [blame] | 2824 | http-check send-state |
| 2825 | Enable emission of a state header with HTTP health checks |
| 2826 | May be used in sections : defaults | frontend | listen | backend |
| 2827 | yes | no | yes | yes |
| 2828 | Arguments : none |
| 2829 | |
| 2830 | When this option is set, haproxy will systematically send a special header |
| 2831 | "X-Haproxy-Server-State" with a list of parameters indicating to each server |
| 2832 | how they are seen by haproxy. This can be used for instance when a server is |
| 2833 | manipulated without access to haproxy and the operator needs to know whether |
| 2834 | haproxy still sees it up or not, or if the server is the last one in a farm. |
| 2835 | |
| 2836 | The header is composed of fields delimited by semi-colons, the first of which |
| 2837 | is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid |
| 2838 | checks on the total number before transition, just as appears in the stats |
| 2839 | interface. Next headers are in the form "<variable>=<value>", indicating in |
| 2840 | no specific order some values available in the stats interface : |
| 2841 | - a variable "name", containing the name of the backend followed by a slash |
| 2842 | ("/") then the name of the server. This can be used when a server is |
| 2843 | checked in multiple backends. |
| 2844 | |
| 2845 | - a variable "node" containing the name of the haproxy node, as set in the |
| 2846 | global "node" variable, otherwise the system's hostname if unspecified. |
| 2847 | |
| 2848 | - a variable "weight" indicating the weight of the server, a slash ("/") |
| 2849 | and the total weight of the farm (just counting usable servers). This |
| 2850 | helps to know if other servers are available to handle the load when this |
| 2851 | one fails. |
| 2852 | |
| 2853 | - a variable "scur" indicating the current number of concurrent connections |
| 2854 | on the server, followed by a slash ("/") then the total number of |
| 2855 | connections on all servers of the same backend. |
| 2856 | |
| 2857 | - a variable "qcur" indicating the current number of requests in the |
| 2858 | server's queue. |
| 2859 | |
| 2860 | Example of a header received by the application server : |
| 2861 | >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \ |
| 2862 | scur=13/22; qcur=0 |
| 2863 | |
| 2864 | See also : "option httpchk", "http-check disable-on-404" |
| 2865 | |
Willy Tarreau | ccbcc37 | 2012-12-27 12:37:57 +0100 | [diff] [blame] | 2866 | http-request { allow | deny | tarpit | auth [realm <realm>] | redirect <rule> | |
Willy Tarreau | f4c43c1 | 2013-06-11 17:01:13 +0200 | [diff] [blame] | 2867 | add-header <name> <fmt> | set-header <name> <fmt> | |
Thierry FOURNIER | dad3d1d | 2014-04-22 18:07:25 +0200 | [diff] [blame] | 2868 | del-header <name> | set-nice <nice> | set-log-level <level> | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 2869 | set-tos <tos> | set-mark <mark> | |
| 2870 | add-acl(<file name>) <key fmt> | |
| 2871 | del-acl(<file name>) <key fmt> | |
| 2872 | del-map(<file name>) <key fmt> | |
| 2873 | set-map(<file name>) <key fmt> <value fmt> |
| 2874 | } |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2875 | [ { if | unless } <condition> ] |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2876 | Access control for Layer 7 requests |
| 2877 | |
| 2878 | May be used in sections: defaults | frontend | listen | backend |
| 2879 | no | yes | yes | yes |
| 2880 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 2881 | The http-request statement defines a set of rules which apply to layer 7 |
| 2882 | processing. The rules are evaluated in their declaration order when they are |
| 2883 | met in a frontend, listen or backend section. Any rule may optionally be |
| 2884 | followed by an ACL-based condition, in which case it will only be evaluated |
| 2885 | if the condition is true. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2886 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 2887 | The first keyword is the rule's action. Currently supported actions include : |
| 2888 | - "allow" : this stops the evaluation of the rules and lets the request |
| 2889 | pass the check. No further "http-request" rules are evaluated. |
| 2890 | |
| 2891 | - "deny" : this stops the evaluation of the rules and immediately rejects |
| 2892 | the request and emits an HTTP 403 error. No further "http-request" rules |
| 2893 | are evaluated. |
| 2894 | |
Willy Tarreau | ccbcc37 | 2012-12-27 12:37:57 +0100 | [diff] [blame] | 2895 | - "tarpit" : this stops the evaluation of the rules and immediately blocks |
| 2896 | the request without responding for a delay specified by "timeout tarpit" |
| 2897 | or "timeout connect" if the former is not set. After that delay, if the |
| 2898 | client is still connected, an HTTP error 500 is returned so that the |
| 2899 | client does not suspect it has been tarpitted. Logs will report the flags |
| 2900 | "PT". The goal of the tarpit rule is to slow down robots during an attack |
| 2901 | when they're limited on the number of concurrent requests. It can be very |
| 2902 | efficient against very dumb robots, and will significantly reduce the |
| 2903 | load on firewalls compared to a "deny" rule. But when facing "correctly" |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 2904 | developed robots, it can make things worse by forcing haproxy and the |
Willy Tarreau | ccbcc37 | 2012-12-27 12:37:57 +0100 | [diff] [blame] | 2905 | front firewall to support insane number of concurrent connections. |
| 2906 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 2907 | - "auth" : this stops the evaluation of the rules and immediately responds |
| 2908 | with an HTTP 401 or 407 error code to invite the user to present a valid |
| 2909 | user name and password. No further "http-request" rules are evaluated. An |
| 2910 | optional "realm" parameter is supported, it sets the authentication realm |
| 2911 | that is returned with the response (typically the application's name). |
| 2912 | |
Willy Tarreau | 81499eb | 2012-12-27 12:19:02 +0100 | [diff] [blame] | 2913 | - "redirect" : this performs an HTTP redirection based on a redirect rule. |
| 2914 | This is exactly the same as the "redirect" statement except that it |
| 2915 | inserts a redirect rule which can be processed in the middle of other |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 2916 | "http-request" rules and that these rules use the "log-format" strings. |
| 2917 | See the "redirect" keyword for the rule's syntax. |
Willy Tarreau | 81499eb | 2012-12-27 12:19:02 +0100 | [diff] [blame] | 2918 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 2919 | - "add-header" appends an HTTP header field whose name is specified in |
| 2920 | <name> and whose value is defined by <fmt> which follows the log-format |
| 2921 | rules (see Custom Log Format in section 8.2.4). This is particularly |
| 2922 | useful to pass connection-specific information to the server (eg: the |
| 2923 | client's SSL certificate), or to combine several headers into one. This |
| 2924 | rule is not final, so it is possible to add other similar rules. Note |
| 2925 | that header addition is performed immediately, so one rule might reuse |
| 2926 | the resulting header from a previous rule. |
| 2927 | |
| 2928 | - "set-header" does the same as "add-header" except that the header name |
| 2929 | is first removed if it existed. This is useful when passing security |
| 2930 | information to the server, where the header must not be manipulated by |
| 2931 | external users. |
| 2932 | |
Thierry FOURNIER | dad3d1d | 2014-04-22 18:07:25 +0200 | [diff] [blame] | 2933 | - "del-header" removes all HTTP header fields whose name is specified in |
| 2934 | <name>. |
| 2935 | |
Willy Tarreau | f4c43c1 | 2013-06-11 17:01:13 +0200 | [diff] [blame] | 2936 | - "set-nice" sets the "nice" factor of the current request being processed. |
| 2937 | It only has effect against the other requests being processed at the same |
| 2938 | time. The default value is 0, unless altered by the "nice" setting on the |
| 2939 | "bind" line. The accepted range is -1024..1024. The higher the value, the |
| 2940 | nicest the request will be. Lower values will make the request more |
| 2941 | important than other ones. This can be useful to improve the speed of |
| 2942 | some requests, or lower the priority of non-important requests. Using |
| 2943 | this setting without prior experimentation can cause some major slowdown. |
| 2944 | |
Willy Tarreau | 9a355ec | 2013-06-11 17:45:46 +0200 | [diff] [blame] | 2945 | - "set-log-level" is used to change the log level of the current request |
| 2946 | when a certain condition is met. Valid levels are the 8 syslog levels |
| 2947 | (see the "log" keyword) plus the special level "silent" which disables |
| 2948 | logging for this request. This rule is not final so the last matching |
| 2949 | rule wins. This rule can be useful to disable health checks coming from |
| 2950 | another equipment. |
| 2951 | |
Willy Tarreau | 42cf39e | 2013-06-11 18:51:32 +0200 | [diff] [blame] | 2952 | - "set-tos" is used to set the TOS or DSCP field value of packets sent to |
| 2953 | the client to the value passed in <tos> on platforms which support this. |
| 2954 | This value represents the whole 8 bits of the IP TOS field, and can be |
| 2955 | expressed both in decimal or hexadecimal format (prefixed by "0x"). Note |
| 2956 | that only the 6 higher bits are used in DSCP or TOS, and the two lower |
| 2957 | bits are always 0. This can be used to adjust some routing behaviour on |
| 2958 | border routers based on some information from the request. See RFC 2474, |
| 2959 | 2597, 3260 and 4594 for more information. |
| 2960 | |
Willy Tarreau | 51347ed | 2013-06-11 19:34:13 +0200 | [diff] [blame] | 2961 | - "set-mark" is used to set the Netfilter MARK on all packets sent to the |
| 2962 | client to the value passed in <mark> on platforms which support it. This |
| 2963 | value is an unsigned 32 bit value which can be matched by netfilter and |
| 2964 | by the routing table. It can be expressed both in decimal or hexadecimal |
| 2965 | format (prefixed by "0x"). This can be useful to force certain packets to |
| 2966 | take a different route (for example a cheaper network path for bulk |
| 2967 | downloads). This works on Linux kernels 2.6.32 and above and requires |
| 2968 | admin privileges. |
| 2969 | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 2970 | - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded |
| 2971 | from a file (even a dummy empty file). The file name of the ACL to be |
| 2972 | updated is passed between parentheses. It takes one argument: <key fmt>, |
| 2973 | which follows log-format rules, to collect content of the new entry. It |
| 2974 | performs a lookup in the ACL before insertion, to avoid duplicated (or |
| 2975 | more) values. This lookup is done by a linear search and can be expensive |
| 2976 | with large lists! It is the equivalent of the "add acl" command from the |
| 2977 | stats socket, but can be triggered by an HTTP request. |
| 2978 | |
| 2979 | - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded |
| 2980 | from a file (even a dummy empty file). The file name of the ACL to be |
| 2981 | updated is passed between parentheses. It takes one argument: <key fmt>, |
| 2982 | which follows log-format rules, to collect content of the entry to delete. |
| 2983 | It is the equivalent of the "del acl" command from the stats socket, but |
| 2984 | can be triggered by an HTTP request. |
| 2985 | |
| 2986 | - "del-map" is used to delete an entry from a MAP. The MAP must be loaded |
| 2987 | from a file (even a dummy empty file). The file name of the MAP to be |
| 2988 | updated is passed between parentheses. It takes one argument: <key fmt>, |
| 2989 | which follows log-format rules, to collect content of the entry to delete. |
| 2990 | It takes one argument: "file name" It is the equivalent of the "del map" |
| 2991 | command from the stats socket, but can be triggered by an HTTP request. |
| 2992 | |
| 2993 | - "set-map" is used to add a new entry into a MAP. The MAP must be loaded |
| 2994 | from a file (even a dummy empty file). The file name of the MAP to be |
| 2995 | updated is passed between parentheses. It takes 2 arguments: <key fmt>, |
| 2996 | which follows log-format rules, used to collect MAP key, and <value fmt>, |
| 2997 | which follows log-format rules, used to collect content for the new entry. |
| 2998 | It performs a lookup in the MAP before insertion, to avoid duplicated (or |
| 2999 | more) values. This lookup is done by a linear search and can be expensive |
| 3000 | with large lists! It is the equivalent of the "set map" command from the |
| 3001 | stats socket, but can be triggered by an HTTP request. |
| 3002 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 3003 | There is no limit to the number of http-request statements per instance. |
| 3004 | |
| 3005 | It is important to know that http-request rules are processed very early in |
| 3006 | the HTTP processing, just after "block" rules and before "reqdel" or "reqrep" |
| 3007 | rules. That way, headers added by "add-header"/"set-header" are visible by |
| 3008 | almost all further ACL rules. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 3009 | |
| 3010 | Example: |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 3011 | acl nagios src 192.168.129.3 |
| 3012 | acl local_net src 192.168.0.0/16 |
| 3013 | acl auth_ok http_auth(L1) |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 3014 | |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 3015 | http-request allow if nagios |
| 3016 | http-request allow if local_net auth_ok |
| 3017 | http-request auth realm Gimme if local_net auth_ok |
| 3018 | http-request deny |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 3019 | |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 3020 | Example: |
| 3021 | acl auth_ok http_auth_group(L1) G1 |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 3022 | http-request auth unless auth_ok |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 3023 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 3024 | Example: |
| 3025 | http-request set-header X-Haproxy-Current-Date %T |
| 3026 | http-request set-header X-SSL %[ssl_fc] |
| 3027 | http-request set-header X-SSL-Session_ID %[ssl_fc_session_id] |
| 3028 | http-request set-header X-SSL-Client-Verify %[ssl_c_verify] |
| 3029 | http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn] |
| 3030 | http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)] |
| 3031 | http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn] |
| 3032 | http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore] |
| 3033 | http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter] |
| 3034 | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 3035 | Example: |
| 3036 | acl key req.hdr(X-Add-Acl-Key) -m found |
| 3037 | acl add path /addacl |
| 3038 | acl del path /delacl |
| 3039 | |
| 3040 | acl myhost hdr(Host) -f myhost.lst |
| 3041 | |
| 3042 | http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add |
| 3043 | http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del |
| 3044 | |
| 3045 | Example: |
| 3046 | acl value req.hdr(X-Value) -m found |
| 3047 | acl setmap path /setmap |
| 3048 | acl delmap path /delmap |
| 3049 | |
| 3050 | use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } |
| 3051 | |
| 3052 | http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value |
| 3053 | http-request del-map(map.lst) %[src] if delmap |
| 3054 | |
Cyril Bonté | 2be1b3f | 2010-09-30 23:46:30 +0200 | [diff] [blame] | 3055 | See also : "stats http-request", section 3.4 about userlists and section 7 |
| 3056 | about ACL usage. |
Willy Tarreau | ef78104 | 2010-01-27 11:53:01 +0100 | [diff] [blame] | 3057 | |
Willy Tarreau | f4c43c1 | 2013-06-11 17:01:13 +0200 | [diff] [blame] | 3058 | http-response { allow | deny | add-header <name> <fmt> | set-nice <nice> | |
Thierry FOURNIER | dad3d1d | 2014-04-22 18:07:25 +0200 | [diff] [blame] | 3059 | set-header <name> <fmt> | del-header <name> | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 3060 | set-log-level <level> | set-mark <mark> | set-tos <tos> | |
| 3061 | add-acl(<file name>) <key fmt> | |
| 3062 | del-acl(<file name>) <key fmt> | |
| 3063 | del-map(<file name>) <key fmt> | |
| 3064 | set-map(<file name>) <key fmt> <value fmt> |
| 3065 | } |
Lukas Tribus | 2dd1d1a | 2013-06-19 23:34:41 +0200 | [diff] [blame] | 3066 | [ { if | unless } <condition> ] |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 3067 | Access control for Layer 7 responses |
| 3068 | |
| 3069 | May be used in sections: defaults | frontend | listen | backend |
| 3070 | no | yes | yes | yes |
| 3071 | |
| 3072 | The http-response statement defines a set of rules which apply to layer 7 |
| 3073 | processing. The rules are evaluated in their declaration order when they are |
| 3074 | met in a frontend, listen or backend section. Any rule may optionally be |
| 3075 | followed by an ACL-based condition, in which case it will only be evaluated |
| 3076 | if the condition is true. Since these rules apply on responses, the backend |
| 3077 | rules are applied first, followed by the frontend's rules. |
| 3078 | |
| 3079 | The first keyword is the rule's action. Currently supported actions include : |
| 3080 | - "allow" : this stops the evaluation of the rules and lets the response |
| 3081 | pass the check. No further "http-response" rules are evaluated for the |
| 3082 | current section. |
| 3083 | |
| 3084 | - "deny" : this stops the evaluation of the rules and immediately rejects |
| 3085 | the response and emits an HTTP 502 error. No further "http-response" |
| 3086 | rules are evaluated. |
| 3087 | |
| 3088 | - "add-header" appends an HTTP header field whose name is specified in |
| 3089 | <name> and whose value is defined by <fmt> which follows the log-format |
| 3090 | rules (see Custom Log Format in section 8.2.4). This may be used to send |
| 3091 | a cookie to a client for example, or to pass some internal information. |
| 3092 | This rule is not final, so it is possible to add other similar rules. |
| 3093 | Note that header addition is performed immediately, so one rule might |
| 3094 | reuse the resulting header from a previous rule. |
| 3095 | |
| 3096 | - "set-header" does the same as "add-header" except that the header name |
| 3097 | is first removed if it existed. This is useful when passing security |
| 3098 | information to the server, where the header must not be manipulated by |
| 3099 | external users. |
| 3100 | |
Thierry FOURNIER | dad3d1d | 2014-04-22 18:07:25 +0200 | [diff] [blame] | 3101 | - "del-header" removes all HTTP header fields whose name is specified in |
| 3102 | <name>. |
| 3103 | |
Willy Tarreau | f4c43c1 | 2013-06-11 17:01:13 +0200 | [diff] [blame] | 3104 | - "set-nice" sets the "nice" factor of the current request being processed. |
| 3105 | It only has effect against the other requests being processed at the same |
| 3106 | time. The default value is 0, unless altered by the "nice" setting on the |
| 3107 | "bind" line. The accepted range is -1024..1024. The higher the value, the |
| 3108 | nicest the request will be. Lower values will make the request more |
| 3109 | important than other ones. This can be useful to improve the speed of |
| 3110 | some requests, or lower the priority of non-important requests. Using |
| 3111 | this setting without prior experimentation can cause some major slowdown. |
| 3112 | |
Willy Tarreau | 9a355ec | 2013-06-11 17:45:46 +0200 | [diff] [blame] | 3113 | - "set-log-level" is used to change the log level of the current request |
| 3114 | when a certain condition is met. Valid levels are the 8 syslog levels |
| 3115 | (see the "log" keyword) plus the special level "silent" which disables |
| 3116 | logging for this request. This rule is not final so the last matching |
| 3117 | rule wins. This rule can be useful to disable health checks coming from |
| 3118 | another equipment. |
| 3119 | |
Willy Tarreau | 42cf39e | 2013-06-11 18:51:32 +0200 | [diff] [blame] | 3120 | - "set-tos" is used to set the TOS or DSCP field value of packets sent to |
| 3121 | the client to the value passed in <tos> on platforms which support this. |
| 3122 | This value represents the whole 8 bits of the IP TOS field, and can be |
| 3123 | expressed both in decimal or hexadecimal format (prefixed by "0x"). Note |
| 3124 | that only the 6 higher bits are used in DSCP or TOS, and the two lower |
| 3125 | bits are always 0. This can be used to adjust some routing behaviour on |
| 3126 | border routers based on some information from the request. See RFC 2474, |
| 3127 | 2597, 3260 and 4594 for more information. |
| 3128 | |
Willy Tarreau | 51347ed | 2013-06-11 19:34:13 +0200 | [diff] [blame] | 3129 | - "set-mark" is used to set the Netfilter MARK on all packets sent to the |
| 3130 | client to the value passed in <mark> on platforms which support it. This |
| 3131 | value is an unsigned 32 bit value which can be matched by netfilter and |
| 3132 | by the routing table. It can be expressed both in decimal or hexadecimal |
| 3133 | format (prefixed by "0x"). This can be useful to force certain packets to |
| 3134 | take a different route (for example a cheaper network path for bulk |
| 3135 | downloads). This works on Linux kernels 2.6.32 and above and requires |
| 3136 | admin privileges. |
| 3137 | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 3138 | - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded |
| 3139 | from a file (even a dummy empty file). The file name of the ACL to be |
| 3140 | updated is passed between parentheses. It takes one argument: <key fmt>, |
| 3141 | which follows log-format rules, to collect content of the new entry. It |
| 3142 | performs a lookup in the ACL before insertion, to avoid duplicated (or |
| 3143 | more) values. This lookup is done by a linear search and can be expensive |
| 3144 | with large lists! It is the equivalent of the "add acl" command from the |
| 3145 | stats socket, but can be triggered by an HTTP response. |
| 3146 | |
| 3147 | - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded |
| 3148 | from a file (even a dummy empty file). The file name of the ACL to be |
| 3149 | updated is passed between parentheses. It takes one argument: <key fmt>, |
| 3150 | which follows log-format rules, to collect content of the entry to delete. |
| 3151 | It is the equivalent of the "del acl" command from the stats socket, but |
| 3152 | can be triggered by an HTTP response. |
| 3153 | |
| 3154 | - "del-map" is used to delete an entry from a MAP. The MAP must be loaded |
| 3155 | from a file (even a dummy empty file). The file name of the MAP to be |
| 3156 | updated is passed between parentheses. It takes one argument: <key fmt>, |
| 3157 | which follows log-format rules, to collect content of the entry to delete. |
| 3158 | It takes one argument: "file name" It is the equivalent of the "del map" |
| 3159 | command from the stats socket, but can be triggered by an HTTP response. |
| 3160 | |
| 3161 | - "set-map" is used to add a new entry into a MAP. The MAP must be loaded |
| 3162 | from a file (even a dummy empty file). The file name of the MAP to be |
| 3163 | updated is passed between parentheses. It takes 2 arguments: <key fmt>, |
| 3164 | which follows log-format rules, used to collect MAP key, and <value fmt>, |
| 3165 | which follows log-format rules, used to collect content for the new entry. |
| 3166 | It performs a lookup in the MAP before insertion, to avoid duplicated (or |
| 3167 | more) values. This lookup is done by a linear search and can be expensive |
| 3168 | with large lists! It is the equivalent of the "set map" command from the |
| 3169 | stats socket, but can be triggered by an HTTP response. |
| 3170 | |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 3171 | There is no limit to the number of http-response statements per instance. |
| 3172 | |
Godbach | 0925026 | 2013-07-02 01:19:15 +0800 | [diff] [blame] | 3173 | It is important to know that http-response rules are processed very early in |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 3174 | the HTTP processing, before "reqdel" or "reqrep" rules. That way, headers |
| 3175 | added by "add-header"/"set-header" are visible by almost all further ACL |
| 3176 | rules. |
| 3177 | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 3178 | Example: |
| 3179 | acl key_acl res.hdr(X-Acl-Key) -m found |
| 3180 | |
| 3181 | acl myhost hdr(Host) -f myhost.lst |
| 3182 | |
| 3183 | http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl |
| 3184 | http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl |
| 3185 | |
| 3186 | Example: |
| 3187 | acl value res.hdr(X-Value) -m found |
| 3188 | |
| 3189 | use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } |
| 3190 | |
| 3191 | http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value |
| 3192 | http-response del-map(map.lst) %[src] if ! value |
| 3193 | |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 3194 | See also : "http-request", section 3.4 about userlists and section 7 about |
| 3195 | ACL usage. |
| 3196 | |
Baptiste Assmann | 5ecb77f | 2013-10-06 23:24:13 +0200 | [diff] [blame] | 3197 | |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 3198 | http-send-name-header [<header>] |
| 3199 | Add the server name to a request. Use the header string given by <header> |
| 3200 | |
| 3201 | May be used in sections: defaults | frontend | listen | backend |
| 3202 | yes | no | yes | yes |
| 3203 | |
| 3204 | Arguments : |
| 3205 | |
| 3206 | <header> The header string to use to send the server name |
| 3207 | |
| 3208 | The "http-send-name-header" statement causes the name of the target |
| 3209 | server to be added to the headers of an HTTP request. The name |
| 3210 | is added with the header string proved. |
| 3211 | |
| 3212 | See also : "server" |
| 3213 | |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 3214 | id <value> |
Willy Tarreau | 53fb4ae | 2009-10-04 23:04:08 +0200 | [diff] [blame] | 3215 | Set a persistent ID to a proxy. |
| 3216 | May be used in sections : defaults | frontend | listen | backend |
| 3217 | no | yes | yes | yes |
| 3218 | Arguments : none |
| 3219 | |
| 3220 | Set a persistent ID for the proxy. This ID must be unique and positive. |
| 3221 | An unused ID will automatically be assigned if unset. The first assigned |
| 3222 | value will be 1. This ID is currently only returned in statistics. |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 3223 | |
| 3224 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 3225 | ignore-persist { if | unless } <condition> |
| 3226 | Declare a condition to ignore persistence |
| 3227 | May be used in sections: defaults | frontend | listen | backend |
| 3228 | no | yes | yes | yes |
| 3229 | |
| 3230 | By default, when cookie persistence is enabled, every requests containing |
| 3231 | the cookie are unconditionally persistent (assuming the target server is up |
| 3232 | and running). |
| 3233 | |
| 3234 | The "ignore-persist" statement allows one to declare various ACL-based |
| 3235 | conditions which, when met, will cause a request to ignore persistence. |
| 3236 | This is sometimes useful to load balance requests for static files, which |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 3237 | often don't require persistence. This can also be used to fully disable |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 3238 | persistence for a specific User-Agent (for example, some web crawler bots). |
| 3239 | |
| 3240 | Combined with "appsession", it can also help reduce HAProxy memory usage, as |
| 3241 | the appsession table won't grow if persistence is ignored. |
| 3242 | |
| 3243 | The persistence is ignored when an "if" condition is met, or unless an |
| 3244 | "unless" condition is met. |
| 3245 | |
| 3246 | See also : "force-persist", "cookie", and section 7 about ACL usage. |
| 3247 | |
| 3248 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3249 | log global |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 3250 | log <address> <facility> [<level> [<minlevel>]] |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 3251 | no log |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3252 | Enable per-instance logging of events and traffic. |
| 3253 | May be used in sections : defaults | frontend | listen | backend |
| 3254 | yes | yes | yes | yes |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 3255 | |
| 3256 | Prefix : |
| 3257 | no should be used when the logger list must be flushed. For example, |
| 3258 | if you don't want to inherit from the default logger list. This |
| 3259 | prefix does not allow arguments. |
| 3260 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3261 | Arguments : |
| 3262 | global should be used when the instance's logging parameters are the |
| 3263 | same as the global ones. This is the most common usage. "global" |
| 3264 | replaces <address>, <facility> and <level> with those of the log |
| 3265 | entries found in the "global" section. Only one "log global" |
| 3266 | statement may be used per instance, and this form takes no other |
| 3267 | parameter. |
| 3268 | |
| 3269 | <address> indicates where to send the logs. It takes the same format as |
| 3270 | for the "global" section's logs, and can be one of : |
| 3271 | |
| 3272 | - An IPv4 address optionally followed by a colon (':') and a UDP |
| 3273 | port. If no port is specified, 514 is used by default (the |
| 3274 | standard syslog port). |
| 3275 | |
David du Colombier | 24bb5f5 | 2011-03-17 10:40:23 +0100 | [diff] [blame] | 3276 | - An IPv6 address followed by a colon (':') and optionally a UDP |
| 3277 | port. If no port is specified, 514 is used by default (the |
| 3278 | standard syslog port). |
| 3279 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3280 | - A filesystem path to a UNIX domain socket, keeping in mind |
| 3281 | considerations for chroot (be sure the path is accessible |
| 3282 | inside the chroot) and uid/gid (be sure the path is |
| 3283 | appropriately writeable). |
| 3284 | |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 3285 | Any part of the address string may reference any number of |
| 3286 | environment variables by preceding their name with a dollar |
| 3287 | sign ('$') and optionally enclosing them with braces ('{}'), |
| 3288 | similarly to what is done in Bourne shell. |
| 3289 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3290 | <facility> must be one of the 24 standard syslog facilities : |
| 3291 | |
| 3292 | kern user mail daemon auth syslog lpr news |
| 3293 | uucp cron auth2 ftp ntp audit alert cron2 |
| 3294 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 3295 | |
| 3296 | <level> is optional and can be specified to filter outgoing messages. By |
| 3297 | default, all messages are sent. If a level is specified, only |
| 3298 | messages with a severity at least as important as this level |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 3299 | will be sent. An optional minimum level can be specified. If it |
| 3300 | is set, logs emitted with a more severe level than this one will |
| 3301 | be capped to this level. This is used to avoid sending "emerg" |
| 3302 | messages on all terminals on some default syslog configurations. |
| 3303 | Eight levels are known : |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3304 | |
| 3305 | emerg alert crit err warning notice info debug |
| 3306 | |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 3307 | It is important to keep in mind that it is the frontend which decides what to |
| 3308 | log from a connection, and that in case of content switching, the log entries |
| 3309 | from the backend will be ignored. Connections are logged at level "info". |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 3310 | |
| 3311 | However, backend log declaration define how and where servers status changes |
| 3312 | will be logged. Level "notice" will be used to indicate a server going up, |
| 3313 | "warning" will be used for termination signals and definitive service |
| 3314 | termination, and "alert" will be used for when a server goes down. |
| 3315 | |
| 3316 | Note : According to RFC3164, messages are truncated to 1024 bytes before |
| 3317 | being emitted. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3318 | |
| 3319 | Example : |
| 3320 | log global |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 3321 | log 127.0.0.1:514 local0 notice # only send important events |
| 3322 | log 127.0.0.1:514 local0 notice notice # same but limit output level |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 3323 | log ${LOCAL_SYSLOG}:514 local0 notice # send to local server |
| 3324 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3325 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 3326 | log-format <string> |
| 3327 | Allows you to custom a log line. |
| 3328 | |
| 3329 | See also : Custom Log Format (8.2.4) |
| 3330 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3331 | |
Willy Tarreau | c35362a | 2014-04-25 13:58:37 +0200 | [diff] [blame] | 3332 | max-keep-alive-queue <value> |
| 3333 | Set the maximum server queue size for maintaining keep-alive connections |
| 3334 | May be used in sections: defaults | frontend | listen | backend |
| 3335 | yes | no | yes | yes |
| 3336 | |
| 3337 | HTTP keep-alive tries to reuse the same server connection whenever possible, |
| 3338 | but sometimes it can be counter-productive, for example if a server has a lot |
| 3339 | of connections while other ones are idle. This is especially true for static |
| 3340 | servers. |
| 3341 | |
| 3342 | The purpose of this setting is to set a threshold on the number of queued |
| 3343 | connections at which haproxy stops trying to reuse the same server and prefers |
| 3344 | to find another one. The default value, -1, means there is no limit. A value |
| 3345 | of zero means that keep-alive requests will never be queued. For very close |
| 3346 | servers which can be reached with a low latency and which are not sensible to |
| 3347 | breaking keep-alive, a low value is recommended (eg: local static server can |
| 3348 | use a value of 10 or less). For remote servers suffering from a high latency, |
| 3349 | higher values might be needed to cover for the latency and/or the cost of |
| 3350 | picking a different server. |
| 3351 | |
| 3352 | Note that this has no impact on responses which are maintained to the same |
| 3353 | server consecutively to a 401 response. They will still go to the same server |
| 3354 | even if they have to be queued. |
| 3355 | |
| 3356 | See also : "option http-server-close", "option prefer-last-server", server |
| 3357 | "maxconn" and cookie persistence. |
| 3358 | |
| 3359 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3360 | maxconn <conns> |
| 3361 | Fix the maximum number of concurrent connections on a frontend |
| 3362 | May be used in sections : defaults | frontend | listen | backend |
| 3363 | yes | yes | yes | no |
| 3364 | Arguments : |
| 3365 | <conns> is the maximum number of concurrent connections the frontend will |
| 3366 | accept to serve. Excess connections will be queued by the system |
| 3367 | in the socket's listen queue and will be served once a connection |
| 3368 | closes. |
| 3369 | |
| 3370 | If the system supports it, it can be useful on big sites to raise this limit |
| 3371 | very high so that haproxy manages connection queues, instead of leaving the |
| 3372 | clients with unanswered connection attempts. This value should not exceed the |
| 3373 | global maxconn. Also, keep in mind that a connection contains two buffers |
| 3374 | of 8kB each, as well as some other data resulting in about 17 kB of RAM being |
| 3375 | consumed per established connection. That means that a medium system equipped |
| 3376 | with 1GB of RAM can withstand around 40000-50000 concurrent connections if |
| 3377 | properly tuned. |
| 3378 | |
| 3379 | Also, when <conns> is set to large values, it is possible that the servers |
| 3380 | are not sized to accept such loads, and for this reason it is generally wise |
| 3381 | to assign them some reasonable connection limits. |
| 3382 | |
Vincent Bernat | 6341be5 | 2012-06-27 17:18:30 +0200 | [diff] [blame] | 3383 | By default, this value is set to 2000. |
| 3384 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3385 | See also : "server", global section's "maxconn", "fullconn" |
| 3386 | |
| 3387 | |
| 3388 | mode { tcp|http|health } |
| 3389 | Set the running mode or protocol of the instance |
| 3390 | May be used in sections : defaults | frontend | listen | backend |
| 3391 | yes | yes | yes | yes |
| 3392 | Arguments : |
| 3393 | tcp The instance will work in pure TCP mode. A full-duplex connection |
| 3394 | will be established between clients and servers, and no layer 7 |
| 3395 | examination will be performed. This is the default mode. It |
| 3396 | should be used for SSL, SSH, SMTP, ... |
| 3397 | |
| 3398 | http The instance will work in HTTP mode. The client request will be |
| 3399 | analyzed in depth before connecting to any server. Any request |
| 3400 | which is not RFC-compliant will be rejected. Layer 7 filtering, |
| 3401 | processing and switching will be possible. This is the mode which |
| 3402 | brings HAProxy most of its value. |
| 3403 | |
| 3404 | health The instance will work in "health" mode. It will just reply "OK" |
Willy Tarreau | 82569f9 | 2012-09-27 23:48:56 +0200 | [diff] [blame] | 3405 | to incoming connections and close the connection. Alternatively, |
| 3406 | If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent |
| 3407 | instead. Nothing will be logged in either case. This mode is used |
| 3408 | to reply to external components health checks. This mode is |
| 3409 | deprecated and should not be used anymore as it is possible to do |
| 3410 | the same and even better by combining TCP or HTTP modes with the |
| 3411 | "monitor" keyword. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3412 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 3413 | When doing content switching, it is mandatory that the frontend and the |
| 3414 | backend are in the same mode (generally HTTP), otherwise the configuration |
| 3415 | will be refused. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3416 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 3417 | Example : |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3418 | defaults http_instances |
| 3419 | mode http |
| 3420 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 3421 | See also : "monitor", "monitor-net" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3422 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3423 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 3424 | monitor fail { if | unless } <condition> |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3425 | Add a condition to report a failure to a monitor HTTP request. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3426 | May be used in sections : defaults | frontend | listen | backend |
| 3427 | no | yes | yes | no |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3428 | Arguments : |
| 3429 | if <cond> the monitor request will fail if the condition is satisfied, |
| 3430 | and will succeed otherwise. The condition should describe a |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3431 | combined test which must induce a failure if all conditions |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3432 | are met, for instance a low number of servers both in a |
| 3433 | backend and its backup. |
| 3434 | |
| 3435 | unless <cond> the monitor request will succeed only if the condition is |
| 3436 | satisfied, and will fail otherwise. Such a condition may be |
| 3437 | based on a test on the presence of a minimum number of active |
| 3438 | servers in a list of backends. |
| 3439 | |
| 3440 | This statement adds a condition which can force the response to a monitor |
| 3441 | request to report a failure. By default, when an external component queries |
| 3442 | the URI dedicated to monitoring, a 200 response is returned. When one of the |
| 3443 | conditions above is met, haproxy will return 503 instead of 200. This is |
| 3444 | very useful to report a site failure to an external component which may base |
| 3445 | routing advertisements between multiple sites on the availability reported by |
| 3446 | haproxy. In this case, one would rely on an ACL involving the "nbsrv" |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 3447 | criterion. Note that "monitor fail" only works in HTTP mode. Both status |
| 3448 | messages may be tweaked using "errorfile" or "errorloc" if needed. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3449 | |
| 3450 | Example: |
| 3451 | frontend www |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3452 | mode http |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3453 | acl site_dead nbsrv(dynamic) lt 2 |
| 3454 | acl site_dead nbsrv(static) lt 2 |
| 3455 | monitor-uri /site_alive |
| 3456 | monitor fail if site_dead |
| 3457 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 3458 | See also : "monitor-net", "monitor-uri", "errorfile", "errorloc" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3459 | |
| 3460 | |
| 3461 | monitor-net <source> |
| 3462 | Declare a source network which is limited to monitor requests |
| 3463 | May be used in sections : defaults | frontend | listen | backend |
| 3464 | yes | yes | yes | no |
| 3465 | Arguments : |
| 3466 | <source> is the source IPv4 address or network which will only be able to |
| 3467 | get monitor responses to any request. It can be either an IPv4 |
| 3468 | address, a host name, or an address followed by a slash ('/') |
| 3469 | followed by a mask. |
| 3470 | |
| 3471 | In TCP mode, any connection coming from a source matching <source> will cause |
| 3472 | the connection to be immediately closed without any log. This allows another |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3473 | equipment to probe the port and verify that it is still listening, without |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3474 | forwarding the connection to a remote server. |
| 3475 | |
| 3476 | In HTTP mode, a connection coming from a source matching <source> will be |
| 3477 | accepted, the following response will be sent without waiting for a request, |
| 3478 | then the connection will be closed : "HTTP/1.0 200 OK". This is normally |
| 3479 | enough for any front-end HTTP probe to detect that the service is UP and |
Willy Tarreau | 82569f9 | 2012-09-27 23:48:56 +0200 | [diff] [blame] | 3480 | running without forwarding the request to a backend server. Note that this |
| 3481 | response is sent in raw format, without any transformation. This is important |
| 3482 | as it means that it will not be SSL-encrypted on SSL listeners. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3483 | |
Willy Tarreau | 82569f9 | 2012-09-27 23:48:56 +0200 | [diff] [blame] | 3484 | Monitor requests are processed very early, just after tcp-request connection |
| 3485 | ACLs which are the only ones able to block them. These connections are short |
| 3486 | lived and never wait for any data from the client. They cannot be logged, and |
| 3487 | it is the intended purpose. They are only used to report HAProxy's health to |
| 3488 | an upper component, nothing more. Please note that "monitor fail" rules do |
| 3489 | not apply to connections intercepted by "monitor-net". |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3490 | |
Willy Tarreau | 95cd283 | 2010-03-04 23:36:33 +0100 | [diff] [blame] | 3491 | Last, please note that only one "monitor-net" statement can be specified in |
| 3492 | a frontend. If more than one is found, only the last one will be considered. |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 3493 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 3494 | Example : |
| 3495 | # addresses .252 and .253 are just probing us. |
| 3496 | frontend www |
| 3497 | monitor-net 192.168.0.252/31 |
| 3498 | |
| 3499 | See also : "monitor fail", "monitor-uri" |
| 3500 | |
| 3501 | |
| 3502 | monitor-uri <uri> |
| 3503 | Intercept a URI used by external components' monitor requests |
| 3504 | May be used in sections : defaults | frontend | listen | backend |
| 3505 | yes | yes | yes | no |
| 3506 | Arguments : |
| 3507 | <uri> is the exact URI which we want to intercept to return HAProxy's |
| 3508 | health status instead of forwarding the request. |
| 3509 | |
| 3510 | When an HTTP request referencing <uri> will be received on a frontend, |
| 3511 | HAProxy will not forward it nor log it, but instead will return either |
| 3512 | "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure |
| 3513 | conditions defined with "monitor fail". This is normally enough for any |
| 3514 | front-end HTTP probe to detect that the service is UP and running without |
| 3515 | forwarding the request to a backend server. Note that the HTTP method, the |
| 3516 | version and all headers are ignored, but the request must at least be valid |
| 3517 | at the HTTP level. This keyword may only be used with an HTTP-mode frontend. |
| 3518 | |
| 3519 | Monitor requests are processed very early. It is not possible to block nor |
| 3520 | divert them using ACLs. They cannot be logged either, and it is the intended |
| 3521 | purpose. They are only used to report HAProxy's health to an upper component, |
| 3522 | nothing more. However, it is possible to add any number of conditions using |
| 3523 | "monitor fail" and ACLs so that the result can be adjusted to whatever check |
| 3524 | can be imagined (most often the number of available servers in a backend). |
| 3525 | |
| 3526 | Example : |
| 3527 | # Use /haproxy_test to report haproxy's status |
| 3528 | frontend www |
| 3529 | mode http |
| 3530 | monitor-uri /haproxy_test |
| 3531 | |
| 3532 | See also : "monitor fail", "monitor-net" |
| 3533 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3534 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3535 | option abortonclose |
| 3536 | no option abortonclose |
| 3537 | Enable or disable early dropping of aborted requests pending in queues. |
| 3538 | May be used in sections : defaults | frontend | listen | backend |
| 3539 | yes | no | yes | yes |
| 3540 | Arguments : none |
| 3541 | |
| 3542 | In presence of very high loads, the servers will take some time to respond. |
| 3543 | The per-instance connection queue will inflate, and the response time will |
| 3544 | increase respective to the size of the queue times the average per-session |
| 3545 | response time. When clients will wait for more than a few seconds, they will |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3546 | often hit the "STOP" button on their browser, leaving a useless request in |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3547 | the queue, and slowing down other users, and the servers as well, because the |
| 3548 | request will eventually be served, then aborted at the first error |
| 3549 | encountered while delivering the response. |
| 3550 | |
| 3551 | As there is no way to distinguish between a full STOP and a simple output |
| 3552 | close on the client side, HTTP agents should be conservative and consider |
| 3553 | that the client might only have closed its output channel while waiting for |
| 3554 | the response. However, this introduces risks of congestion when lots of users |
| 3555 | do the same, and is completely useless nowadays because probably no client at |
| 3556 | all will close the session while waiting for the response. Some HTTP agents |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 3557 | support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3558 | hardware-based load balancers). So the probability for a closed input channel |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3559 | to represent a user hitting the "STOP" button is close to 100%, and the risk |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3560 | of being the single component to break rare but valid traffic is extremely |
| 3561 | low, which adds to the temptation to be able to abort a session early while |
| 3562 | still not served and not pollute the servers. |
| 3563 | |
| 3564 | In HAProxy, the user can choose the desired behaviour using the option |
| 3565 | "abortonclose". By default (without the option) the behaviour is HTTP |
| 3566 | compliant and aborted requests will be served. But when the option is |
| 3567 | specified, a session with an incoming channel closed will be aborted while |
| 3568 | it is still possible, either pending in the queue for a connection slot, or |
| 3569 | during the connection establishment if the server has not yet acknowledged |
| 3570 | the connection request. This considerably reduces the queue size and the load |
| 3571 | on saturated servers when users are tempted to click on STOP, which in turn |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 3572 | reduces the response time for other users. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3573 | |
| 3574 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3575 | in a specific instance by prepending the "no" keyword before it. |
| 3576 | |
| 3577 | See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters |
| 3578 | |
| 3579 | |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 3580 | option accept-invalid-http-request |
| 3581 | no option accept-invalid-http-request |
| 3582 | Enable or disable relaxing of HTTP request parsing |
| 3583 | May be used in sections : defaults | frontend | listen | backend |
| 3584 | yes | yes | yes | no |
| 3585 | Arguments : none |
| 3586 | |
| 3587 | By default, HAProxy complies with RFC2616 in terms of message parsing. This |
| 3588 | means that invalid characters in header names are not permitted and cause an |
| 3589 | error to be returned to the client. This is the desired behaviour as such |
| 3590 | forbidden characters are essentially used to build attacks exploiting server |
| 3591 | weaknesses, and bypass security filtering. Sometimes, a buggy browser or |
| 3592 | server will emit invalid header names for whatever reason (configuration, |
| 3593 | implementation) and the issue will not be immediately fixed. In such a case, |
| 3594 | it is possible to relax HAProxy's header name parser to accept any character |
Willy Tarreau | 422246e | 2012-01-07 23:54:13 +0100 | [diff] [blame] | 3595 | even if that does not make sense, by specifying this option. Similarly, the |
| 3596 | list of characters allowed to appear in a URI is well defined by RFC3986, and |
| 3597 | chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96 |
| 3598 | ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are |
| 3599 | not allowed at all. Haproxy always blocks a number of them (0..32, 127). The |
| 3600 | remaining ones are blocked by default unless this option is enabled. |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 3601 | |
| 3602 | This option should never be enabled by default as it hides application bugs |
| 3603 | and open security breaches. It should only be deployed after a problem has |
| 3604 | been confirmed. |
| 3605 | |
| 3606 | When this option is enabled, erroneous header names will still be accepted in |
| 3607 | requests, but the complete request will be captured in order to permit later |
Willy Tarreau | 422246e | 2012-01-07 23:54:13 +0100 | [diff] [blame] | 3608 | analysis using the "show errors" request on the UNIX stats socket. Similarly, |
| 3609 | requests containing invalid chars in the URI part will be logged. Doing this |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 3610 | also helps confirming that the issue has been solved. |
| 3611 | |
| 3612 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3613 | in a specific instance by prepending the "no" keyword before it. |
| 3614 | |
| 3615 | See also : "option accept-invalid-http-response" and "show errors" on the |
| 3616 | stats socket. |
| 3617 | |
| 3618 | |
| 3619 | option accept-invalid-http-response |
| 3620 | no option accept-invalid-http-response |
| 3621 | Enable or disable relaxing of HTTP response parsing |
| 3622 | May be used in sections : defaults | frontend | listen | backend |
| 3623 | yes | no | yes | yes |
| 3624 | Arguments : none |
| 3625 | |
| 3626 | By default, HAProxy complies with RFC2616 in terms of message parsing. This |
| 3627 | means that invalid characters in header names are not permitted and cause an |
| 3628 | error to be returned to the client. This is the desired behaviour as such |
| 3629 | forbidden characters are essentially used to build attacks exploiting server |
| 3630 | weaknesses, and bypass security filtering. Sometimes, a buggy browser or |
| 3631 | server will emit invalid header names for whatever reason (configuration, |
| 3632 | implementation) and the issue will not be immediately fixed. In such a case, |
| 3633 | it is possible to relax HAProxy's header name parser to accept any character |
| 3634 | even if that does not make sense, by specifying this option. |
| 3635 | |
| 3636 | This option should never be enabled by default as it hides application bugs |
| 3637 | and open security breaches. It should only be deployed after a problem has |
| 3638 | been confirmed. |
| 3639 | |
| 3640 | When this option is enabled, erroneous header names will still be accepted in |
| 3641 | responses, but the complete response will be captured in order to permit |
| 3642 | later analysis using the "show errors" request on the UNIX stats socket. |
| 3643 | Doing this also helps confirming that the issue has been solved. |
| 3644 | |
| 3645 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3646 | in a specific instance by prepending the "no" keyword before it. |
| 3647 | |
| 3648 | See also : "option accept-invalid-http-request" and "show errors" on the |
| 3649 | stats socket. |
| 3650 | |
| 3651 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3652 | option allbackups |
| 3653 | no option allbackups |
| 3654 | Use either all backup servers at a time or only the first one |
| 3655 | May be used in sections : defaults | frontend | listen | backend |
| 3656 | yes | no | yes | yes |
| 3657 | Arguments : none |
| 3658 | |
| 3659 | By default, the first operational backup server gets all traffic when normal |
| 3660 | servers are all down. Sometimes, it may be preferred to use multiple backups |
| 3661 | at once, because one will not be enough. When "option allbackups" is enabled, |
| 3662 | the load balancing will be performed among all backup servers when all normal |
| 3663 | ones are unavailable. The same load balancing algorithm will be used and the |
| 3664 | servers' weights will be respected. Thus, there will not be any priority |
| 3665 | order between the backup servers anymore. |
| 3666 | |
| 3667 | This option is mostly used with static server farms dedicated to return a |
| 3668 | "sorry" page when an application is completely offline. |
| 3669 | |
| 3670 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3671 | in a specific instance by prepending the "no" keyword before it. |
| 3672 | |
| 3673 | |
| 3674 | option checkcache |
| 3675 | no option checkcache |
Godbach | 7056a35 | 2013-12-11 20:01:07 +0800 | [diff] [blame] | 3676 | Analyze all server responses and block responses with cacheable cookies |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3677 | May be used in sections : defaults | frontend | listen | backend |
| 3678 | yes | no | yes | yes |
| 3679 | Arguments : none |
| 3680 | |
| 3681 | Some high-level frameworks set application cookies everywhere and do not |
| 3682 | always let enough control to the developer to manage how the responses should |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3683 | be cached. When a session cookie is returned on a cacheable object, there is a |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3684 | high risk of session crossing or stealing between users traversing the same |
| 3685 | caches. In some situations, it is better to block the response than to let |
Willy Tarreau | 3c92c5f | 2011-08-28 09:45:47 +0200 | [diff] [blame] | 3686 | some sensitive session information go in the wild. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3687 | |
| 3688 | The option "checkcache" enables deep inspection of all server responses for |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3689 | strict compliance with HTTP specification in terms of cacheability. It |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3690 | carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3691 | response to check if there's a risk of caching a cookie on a client-side |
| 3692 | proxy. When this option is enabled, the only responses which can be delivered |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3693 | to the client are : |
| 3694 | - all those without "Set-Cookie" header ; |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3695 | - all those with a return code other than 200, 203, 206, 300, 301, 410, |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3696 | provided that the server has not set a "Cache-control: public" header ; |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3697 | - all those that come from a POST request, provided that the server has not |
| 3698 | set a 'Cache-Control: public' header ; |
| 3699 | - those with a 'Pragma: no-cache' header |
| 3700 | - those with a 'Cache-control: private' header |
| 3701 | - those with a 'Cache-control: no-store' header |
| 3702 | - those with a 'Cache-control: max-age=0' header |
| 3703 | - those with a 'Cache-control: s-maxage=0' header |
| 3704 | - those with a 'Cache-control: no-cache' header |
| 3705 | - those with a 'Cache-control: no-cache="set-cookie"' header |
| 3706 | - those with a 'Cache-control: no-cache="set-cookie,' header |
| 3707 | (allowing other fields after set-cookie) |
| 3708 | |
| 3709 | If a response doesn't respect these requirements, then it will be blocked |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3710 | just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway". |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3711 | The session state shows "PH--" meaning that the proxy blocked the response |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3712 | during headers processing. Additionally, an alert will be sent in the logs so |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3713 | that admins are informed that there's something to be fixed. |
| 3714 | |
| 3715 | Due to the high impact on the application, the application should be tested |
| 3716 | in depth with the option enabled before going to production. It is also a |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 3717 | good practice to always activate it during tests, even if it is not used in |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3718 | production, as it will report potentially dangerous application behaviours. |
| 3719 | |
| 3720 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3721 | in a specific instance by prepending the "no" keyword before it. |
| 3722 | |
| 3723 | |
| 3724 | option clitcpka |
| 3725 | no option clitcpka |
| 3726 | Enable or disable the sending of TCP keepalive packets on the client side |
| 3727 | May be used in sections : defaults | frontend | listen | backend |
| 3728 | yes | yes | yes | no |
| 3729 | Arguments : none |
| 3730 | |
| 3731 | When there is a firewall or any session-aware component between a client and |
| 3732 | a server, and when the protocol involves very long sessions with long idle |
| 3733 | periods (eg: remote desktops), there is a risk that one of the intermediate |
| 3734 | components decides to expire a session which has remained idle for too long. |
| 3735 | |
| 3736 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 3737 | to the other end of the connection, leaving it active. The delay between |
| 3738 | keep-alive probes is controlled by the system only and depends both on the |
| 3739 | operating system and its tuning parameters. |
| 3740 | |
| 3741 | It is important to understand that keep-alive packets are neither emitted nor |
| 3742 | received at the application level. It is only the network stacks which sees |
| 3743 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 3744 | to maintain its connection alive, those keep-alive packets will not be |
| 3745 | forwarded to the other side of the proxy. |
| 3746 | |
| 3747 | Please note that this has nothing to do with HTTP keep-alive. |
| 3748 | |
| 3749 | Using option "clitcpka" enables the emission of TCP keep-alive probes on the |
| 3750 | client side of a connection, which should help when session expirations are |
| 3751 | noticed between HAProxy and a client. |
| 3752 | |
| 3753 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3754 | in a specific instance by prepending the "no" keyword before it. |
| 3755 | |
| 3756 | See also : "option srvtcpka", "option tcpka" |
| 3757 | |
| 3758 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3759 | option contstats |
| 3760 | Enable continuous traffic statistics updates |
| 3761 | May be used in sections : defaults | frontend | listen | backend |
| 3762 | yes | yes | yes | no |
| 3763 | Arguments : none |
| 3764 | |
| 3765 | By default, counters used for statistics calculation are incremented |
| 3766 | only when a session finishes. It works quite well when serving small |
| 3767 | objects, but with big ones (for example large images or archives) or |
| 3768 | with A/V streaming, a graph generated from haproxy counters looks like |
| 3769 | a hedgehog. With this option enabled counters get incremented continuously, |
| 3770 | during a whole session. Recounting touches a hotpath directly so |
| 3771 | it is not enabled by default, as it has small performance impact (~0.5%). |
| 3772 | |
| 3773 | |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 3774 | option dontlog-normal |
| 3775 | no option dontlog-normal |
| 3776 | Enable or disable logging of normal, successful connections |
| 3777 | May be used in sections : defaults | frontend | listen | backend |
| 3778 | yes | yes | yes | no |
| 3779 | Arguments : none |
| 3780 | |
| 3781 | There are large sites dealing with several thousand connections per second |
| 3782 | and for which logging is a major pain. Some of them are even forced to turn |
| 3783 | logs off and cannot debug production issues. Setting this option ensures that |
| 3784 | normal connections, those which experience no error, no timeout, no retry nor |
| 3785 | redispatch, will not be logged. This leaves disk space for anomalies. In HTTP |
| 3786 | mode, the response status code is checked and return codes 5xx will still be |
| 3787 | logged. |
| 3788 | |
| 3789 | It is strongly discouraged to use this option as most of the time, the key to |
| 3790 | complex issues is in the normal logs which will not be logged here. If you |
| 3791 | need to separate logs, see the "log-separate-errors" option instead. |
| 3792 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3793 | See also : "log", "dontlognull", "log-separate-errors" and section 8 about |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 3794 | logging. |
| 3795 | |
| 3796 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3797 | option dontlognull |
| 3798 | no option dontlognull |
| 3799 | Enable or disable logging of null connections |
| 3800 | May be used in sections : defaults | frontend | listen | backend |
| 3801 | yes | yes | yes | no |
| 3802 | Arguments : none |
| 3803 | |
| 3804 | In certain environments, there are components which will regularly connect to |
| 3805 | various systems to ensure that they are still alive. It can be the case from |
| 3806 | another load balancer as well as from monitoring systems. By default, even a |
| 3807 | simple port probe or scan will produce a log. If those connections pollute |
| 3808 | the logs too much, it is possible to enable option "dontlognull" to indicate |
| 3809 | that a connection on which no data has been transferred will not be logged, |
| 3810 | which typically corresponds to those probes. |
| 3811 | |
| 3812 | It is generally recommended not to use this option in uncontrolled |
| 3813 | environments (eg: internet), otherwise scans and other malicious activities |
| 3814 | would not be logged. |
| 3815 | |
| 3816 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3817 | in a specific instance by prepending the "no" keyword before it. |
| 3818 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3819 | See also : "log", "monitor-net", "monitor-uri" and section 8 about logging. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3820 | |
| 3821 | |
| 3822 | option forceclose |
| 3823 | no option forceclose |
| 3824 | Enable or disable active connection closing after response is transferred. |
| 3825 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | a31e5df | 2009-12-30 01:10:35 +0100 | [diff] [blame] | 3826 | yes | yes | yes | yes |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3827 | Arguments : none |
| 3828 | |
| 3829 | Some HTTP servers do not necessarily close the connections when they receive |
| 3830 | the "Connection: close" set by "option httpclose", and if the client does not |
| 3831 | close either, then the connection remains open till the timeout expires. This |
| 3832 | causes high number of simultaneous connections on the servers and shows high |
| 3833 | global session times in the logs. |
| 3834 | |
| 3835 | When this happens, it is possible to use "option forceclose". It will |
Willy Tarreau | 82eeaf2 | 2009-12-29 12:09:05 +0100 | [diff] [blame] | 3836 | actively close the outgoing server channel as soon as the server has finished |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 3837 | to respond and release some resources earlier than with "option httpclose". |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3838 | |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 3839 | This option may also be combined with "option http-pretend-keepalive", which |
| 3840 | will disable sending of the "Connection: close" header, but will still cause |
| 3841 | the connection to be closed once the whole response is received. |
| 3842 | |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 3843 | This option disables and replaces any previous "option httpclose", "option |
| 3844 | http-server-close", "option http-keep-alive", or "option http-tunnel". |
Willy Tarreau | 02bce8b | 2014-01-30 00:15:28 +0100 | [diff] [blame] | 3845 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3846 | If this option has been enabled in a "defaults" section, it can be disabled |
| 3847 | in a specific instance by prepending the "no" keyword before it. |
| 3848 | |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 3849 | See also : "option httpclose" and "option http-pretend-keepalive" |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 3850 | |
| 3851 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 3852 | option forwardfor [ except <network> ] [ header <name> ] [ if-none ] |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3853 | Enable insertion of the X-Forwarded-For header to requests sent to servers |
| 3854 | May be used in sections : defaults | frontend | listen | backend |
| 3855 | yes | yes | yes | yes |
| 3856 | Arguments : |
| 3857 | <network> is an optional argument used to disable this option for sources |
| 3858 | matching <network> |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3859 | <name> an optional argument to specify a different "X-Forwarded-For" |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 3860 | header name. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3861 | |
| 3862 | Since HAProxy works in reverse-proxy mode, the servers see its IP address as |
| 3863 | their client address. This is sometimes annoying when the client's IP address |
| 3864 | is expected in server logs. To solve this problem, the well-known HTTP header |
| 3865 | "X-Forwarded-For" may be added by HAProxy to all requests sent to the server. |
| 3866 | This header contains a value representing the client's IP address. Since this |
| 3867 | header is always appended at the end of the existing header list, the server |
| 3868 | must be configured to always use the last occurrence of this header only. See |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3869 | the server's manual to find how to enable use of this standard header. Note |
| 3870 | that only the last occurrence of the header must be used, since it is really |
| 3871 | possible that the client has already brought one. |
| 3872 | |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 3873 | The keyword "header" may be used to supply a different header name to replace |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3874 | the default "X-Forwarded-For". This can be useful where you might already |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 3875 | have a "X-Forwarded-For" header from a different application (eg: stunnel), |
| 3876 | and you need preserve it. Also if your backend server doesn't use the |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3877 | "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers |
| 3878 | require "X-Cluster-Client-IP"). |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3879 | |
| 3880 | Sometimes, a same HAProxy instance may be shared between a direct client |
| 3881 | access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| 3882 | used to decrypt HTTPS traffic). It is possible to disable the addition of the |
| 3883 | header for a known source address or network by adding the "except" keyword |
| 3884 | followed by the network address. In this case, any source IP matching the |
| 3885 | network will not cause an addition of this header. Most common uses are with |
| 3886 | private networks or 127.0.0.1. |
| 3887 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 3888 | Alternatively, the keyword "if-none" states that the header will only be |
| 3889 | added if it is not present. This should only be used in perfectly trusted |
| 3890 | environment, as this might cause a security issue if headers reaching haproxy |
| 3891 | are under the control of the end-user. |
| 3892 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3893 | This option may be specified either in the frontend or in the backend. If at |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3894 | least one of them uses it, the header will be added. Note that the backend's |
| 3895 | setting of the header subargument takes precedence over the frontend's if |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 3896 | both are defined. In the case of the "if-none" argument, if at least one of |
| 3897 | the frontend or the backend does not specify it, it wants the addition to be |
| 3898 | mandatory, so it wins. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3899 | |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3900 | Examples : |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3901 | # Public HTTP address also used by stunnel on the same machine |
| 3902 | frontend www |
| 3903 | mode http |
| 3904 | option forwardfor except 127.0.0.1 # stunnel already adds the header |
| 3905 | |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 3906 | # Those servers want the IP Address in X-Client |
| 3907 | backend www |
| 3908 | mode http |
| 3909 | option forwardfor header X-Client |
| 3910 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 3911 | See also : "option httpclose", "option http-server-close", |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3912 | "option forceclose", "option http-keep-alive" |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 3913 | |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 3914 | |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 3915 | option http-keep-alive |
| 3916 | no option http-keep-alive |
| 3917 | Enable or disable HTTP keep-alive from client to server |
| 3918 | May be used in sections : defaults | frontend | listen | backend |
| 3919 | yes | yes | yes | yes |
| 3920 | Arguments : none |
| 3921 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3922 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 3923 | connections: for each connection it processes each request and response, and |
| 3924 | leaves the connection idle on both sides between the end of a response and the |
| 3925 | start of a new request. This mode may be changed by several options such as |
| 3926 | "option http-server-close", "option forceclose", "option httpclose" or |
| 3927 | "option http-tunnel". This option allows to set back the keep-alive mode, |
| 3928 | which can be useful when another mode was used in a defaults section. |
| 3929 | |
| 3930 | Setting "option http-keep-alive" enables HTTP keep-alive mode on the client- |
| 3931 | and server- sides. This provides the lowest latency on the client side (slow |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 3932 | network) and the fastest session reuse on the server side at the expense |
| 3933 | of maintaining idle connections to the servers. In general, it is possible |
| 3934 | with this option to achieve approximately twice the request rate that the |
| 3935 | "http-server-close" option achieves on small objects. There are mainly two |
| 3936 | situations where this option may be useful : |
| 3937 | |
| 3938 | - when the server is non-HTTP compliant and authenticates the connection |
| 3939 | instead of requests (eg: NTLM authentication) |
| 3940 | |
| 3941 | - when the cost of establishing the connection to the server is significant |
| 3942 | compared to the cost of retrieving the associated object from the server. |
| 3943 | |
| 3944 | This last case can happen when the server is a fast static server of cache. |
| 3945 | In this case, the server will need to be properly tuned to support high enough |
| 3946 | connection counts because connections will last until the client sends another |
| 3947 | request. |
| 3948 | |
| 3949 | If the client request has to go to another backend or another server due to |
| 3950 | content switching or the load balancing algorithm, the idle connection will |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 3951 | immediately be closed and a new one re-opened. Option "prefer-last-server" is |
| 3952 | available to try optimize server selection so that if the server currently |
| 3953 | attached to an idle connection is usable, it will be used. |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 3954 | |
| 3955 | In general it is preferred to use "option http-server-close" with application |
| 3956 | servers, and some static servers might benefit from "option http-keep-alive". |
| 3957 | |
| 3958 | At the moment, logs will not indicate whether requests came from the same |
| 3959 | session or not. The accept date reported in the logs corresponds to the end |
| 3960 | of the previous request, and the request time corresponds to the time spent |
| 3961 | waiting for a new request. The keep-alive request time is still bound to the |
| 3962 | timeout defined by "timeout http-keep-alive" or "timeout http-request" if |
| 3963 | not set. |
| 3964 | |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 3965 | This option disables and replaces any previous "option httpclose", "option |
| 3966 | http-server-close", "option forceclose" or "option http-tunnel". When backend |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3967 | and frontend options differ, all of these 4 options have precedence over |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 3968 | "option http-keep-alive". |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 3969 | |
| 3970 | See also : "option forceclose", "option http-server-close", |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 3971 | "option prefer-last-server", "option http-pretend-keepalive", |
| 3972 | "option httpclose", and "1.1. The HTTP transaction model". |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 3973 | |
| 3974 | |
Willy Tarreau | 96e3121 | 2011-05-30 18:10:30 +0200 | [diff] [blame] | 3975 | option http-no-delay |
| 3976 | no option http-no-delay |
| 3977 | Instruct the system to favor low interactive delays over performance in HTTP |
| 3978 | May be used in sections : defaults | frontend | listen | backend |
| 3979 | yes | yes | yes | yes |
| 3980 | Arguments : none |
| 3981 | |
| 3982 | In HTTP, each payload is unidirectional and has no notion of interactivity. |
| 3983 | Any agent is expected to queue data somewhat for a reasonably low delay. |
| 3984 | There are some very rare server-to-server applications that abuse the HTTP |
| 3985 | protocol and expect the payload phase to be highly interactive, with many |
| 3986 | interleaved data chunks in both directions within a single request. This is |
| 3987 | absolutely not supported by the HTTP specification and will not work across |
| 3988 | most proxies or servers. When such applications attempt to do this through |
| 3989 | haproxy, it works but they will experience high delays due to the network |
| 3990 | optimizations which favor performance by instructing the system to wait for |
| 3991 | enough data to be available in order to only send full packets. Typical |
| 3992 | delays are around 200 ms per round trip. Note that this only happens with |
| 3993 | abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not |
| 3994 | affected. |
| 3995 | |
| 3996 | When "option http-no-delay" is present in either the frontend or the backend |
| 3997 | used by a connection, all such optimizations will be disabled in order to |
| 3998 | make the exchanges as fast as possible. Of course this offers no guarantee on |
| 3999 | the functionality, as it may break at any other place. But if it works via |
| 4000 | HAProxy, it will work as fast as possible. This option should never be used |
| 4001 | by default, and should never be used at all unless such a buggy application |
| 4002 | is discovered. The impact of using this option is an increase of bandwidth |
| 4003 | usage and CPU usage, which may significantly lower performance in high |
| 4004 | latency environments. |
| 4005 | |
| 4006 | |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 4007 | option http-pretend-keepalive |
| 4008 | no option http-pretend-keepalive |
| 4009 | Define whether haproxy will announce keepalive to the server or not |
| 4010 | May be used in sections : defaults | frontend | listen | backend |
| 4011 | yes | yes | yes | yes |
| 4012 | Arguments : none |
| 4013 | |
| 4014 | When running with "option http-server-close" or "option forceclose", haproxy |
| 4015 | adds a "Connection: close" header to the request forwarded to the server. |
| 4016 | Unfortunately, when some servers see this header, they automatically refrain |
| 4017 | from using the chunked encoding for responses of unknown length, while this |
| 4018 | is totally unrelated. The immediate effect is that this prevents haproxy from |
| 4019 | maintaining the client connection alive. A second effect is that a client or |
| 4020 | a cache could receive an incomplete response without being aware of it, and |
| 4021 | consider the response complete. |
| 4022 | |
| 4023 | By setting "option http-pretend-keepalive", haproxy will make the server |
| 4024 | believe it will keep the connection alive. The server will then not fall back |
| 4025 | to the abnormal undesired above. When haproxy gets the whole response, it |
| 4026 | will close the connection with the server just as it would do with the |
| 4027 | "forceclose" option. That way the client gets a normal response and the |
| 4028 | connection is correctly closed on the server side. |
| 4029 | |
| 4030 | It is recommended not to enable this option by default, because most servers |
| 4031 | will more efficiently close the connection themselves after the last packet, |
| 4032 | and release its buffers slightly earlier. Also, the added packet on the |
| 4033 | network could slightly reduce the overall peak performance. However it is |
| 4034 | worth noting that when this option is enabled, haproxy will have slightly |
| 4035 | less work to do. So if haproxy is the bottleneck on the whole architecture, |
| 4036 | enabling this option might save a few CPU cycles. |
| 4037 | |
| 4038 | This option may be set both in a frontend and in a backend. It is enabled if |
| 4039 | at least one of the frontend or backend holding a connection has it enabled. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 4040 | This option may be combined with "option httpclose", which will cause |
Willy Tarreau | 22a9534 | 2010-09-29 14:31:41 +0200 | [diff] [blame] | 4041 | keepalive to be announced to the server and close to be announced to the |
| 4042 | client. This practice is discouraged though. |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 4043 | |
| 4044 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4045 | in a specific instance by prepending the "no" keyword before it. |
| 4046 | |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 4047 | See also : "option forceclose", "option http-server-close", and |
| 4048 | "option http-keep-alive" |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 4049 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4050 | |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 4051 | option http-server-close |
| 4052 | no option http-server-close |
| 4053 | Enable or disable HTTP connection closing on the server side |
| 4054 | May be used in sections : defaults | frontend | listen | backend |
| 4055 | yes | yes | yes | yes |
| 4056 | Arguments : none |
| 4057 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4058 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 4059 | connections: for each connection it processes each request and response, and |
| 4060 | leaves the connection idle on both sides between the end of a response and |
| 4061 | the start of a new request. This mode may be changed by several options such |
| 4062 | as "option http-server-close", "option forceclose", "option httpclose" or |
| 4063 | "option http-tunnel". Setting "option http-server-close" enables HTTP |
| 4064 | connection-close mode on the server side while keeping the ability to support |
| 4065 | HTTP keep-alive and pipelining on the client side. This provides the lowest |
| 4066 | latency on the client side (slow network) and the fastest session reuse on |
| 4067 | the server side to save server resources, similarly to "option forceclose". |
| 4068 | It also permits non-keepalive capable servers to be served in keep-alive mode |
| 4069 | to the clients if they conform to the requirements of RFC2616. Please note |
| 4070 | that some servers do not always conform to those requirements when they see |
| 4071 | "Connection: close" in the request. The effect will be that keep-alive will |
| 4072 | never be used. A workaround consists in enabling "option |
| 4073 | http-pretend-keepalive". |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 4074 | |
| 4075 | At the moment, logs will not indicate whether requests came from the same |
| 4076 | session or not. The accept date reported in the logs corresponds to the end |
| 4077 | of the previous request, and the request time corresponds to the time spent |
| 4078 | waiting for a new request. The keep-alive request time is still bound to the |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 4079 | timeout defined by "timeout http-keep-alive" or "timeout http-request" if |
| 4080 | not set. |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 4081 | |
| 4082 | This option may be set both in a frontend and in a backend. It is enabled if |
| 4083 | at least one of the frontend or backend holding a connection has it enabled. |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 4084 | It disables and replaces any previous "option httpclose", "option forceclose", |
| 4085 | "option http-tunnel" or "option http-keep-alive". Please check section 4 |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4086 | ("Proxies") to see how this option combines with others when frontend and |
| 4087 | backend options differ. |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 4088 | |
| 4089 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4090 | in a specific instance by prepending the "no" keyword before it. |
| 4091 | |
Patrick Mezard | 9ec2ec4 | 2010-06-12 17:02:45 +0200 | [diff] [blame] | 4092 | See also : "option forceclose", "option http-pretend-keepalive", |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 4093 | "option httpclose", "option http-keep-alive", and |
| 4094 | "1.1. The HTTP transaction model". |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 4095 | |
| 4096 | |
Willy Tarreau | 02bce8b | 2014-01-30 00:15:28 +0100 | [diff] [blame] | 4097 | option http-tunnel |
| 4098 | no option http-tunnel |
| 4099 | Disable or enable HTTP connection processing after first transaction |
| 4100 | May be used in sections : defaults | frontend | listen | backend |
| 4101 | yes | yes | yes | yes |
| 4102 | Arguments : none |
| 4103 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4104 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 4105 | connections: for each connection it processes each request and response, and |
| 4106 | leaves the connection idle on both sides between the end of a response and |
| 4107 | the start of a new request. This mode may be changed by several options such |
| 4108 | as "option http-server-close", "option forceclose", "option httpclose" or |
| 4109 | "option http-tunnel". |
| 4110 | |
| 4111 | Option "http-tunnel" disables any HTTP processing past the first request and |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4112 | the first response. This is the mode which was used by default in versions |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4113 | 1.0 to 1.5-dev21. It is the mode with the lowest processing overhead, which |
| 4114 | is normally not needed anymore unless in very specific cases such as when |
| 4115 | using an in-house protocol that looks like HTTP but is not compatible, or |
| 4116 | just to log one request per client in order to reduce log size. Note that |
| 4117 | everything which works at the HTTP level, including header parsing/addition, |
| 4118 | cookie processing or content switching will only work for the first request |
| 4119 | and will be ignored after the first response. |
Willy Tarreau | 02bce8b | 2014-01-30 00:15:28 +0100 | [diff] [blame] | 4120 | |
| 4121 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4122 | in a specific instance by prepending the "no" keyword before it. |
| 4123 | |
| 4124 | See also : "option forceclose", "option http-server-close", |
| 4125 | "option httpclose", "option http-keep-alive", and |
| 4126 | "1.1. The HTTP transaction model". |
| 4127 | |
| 4128 | |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 4129 | option http-use-proxy-header |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 4130 | no option http-use-proxy-header |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 4131 | Make use of non-standard Proxy-Connection header instead of Connection |
| 4132 | May be used in sections : defaults | frontend | listen | backend |
| 4133 | yes | yes | yes | no |
| 4134 | Arguments : none |
| 4135 | |
| 4136 | While RFC2616 explicitly states that HTTP/1.1 agents must use the |
| 4137 | Connection header to indicate their wish of persistent or non-persistent |
| 4138 | connections, both browsers and proxies ignore this header for proxied |
| 4139 | connections and make use of the undocumented, non-standard Proxy-Connection |
| 4140 | header instead. The issue begins when trying to put a load balancer between |
| 4141 | browsers and such proxies, because there will be a difference between what |
| 4142 | haproxy understands and what the client and the proxy agree on. |
| 4143 | |
| 4144 | By setting this option in a frontend, haproxy can automatically switch to use |
| 4145 | that non-standard header if it sees proxied requests. A proxied request is |
| 4146 | defined here as one where the URI begins with neither a '/' nor a '*'. The |
| 4147 | choice of header only affects requests passing through proxies making use of |
| 4148 | one of the "httpclose", "forceclose" and "http-server-close" options. Note |
| 4149 | that this option can only be specified in a frontend and will affect the |
| 4150 | request along its whole life. |
| 4151 | |
Willy Tarreau | 844a7e7 | 2010-01-31 21:46:18 +0100 | [diff] [blame] | 4152 | Also, when this option is set, a request which requires authentication will |
| 4153 | automatically switch to use proxy authentication headers if it is itself a |
| 4154 | proxied request. That makes it possible to check or enforce authentication in |
| 4155 | front of an existing proxy. |
| 4156 | |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 4157 | This option should normally never be used, except in front of a proxy. |
| 4158 | |
| 4159 | See also : "option httpclose", "option forceclose" and "option |
| 4160 | http-server-close". |
| 4161 | |
| 4162 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 4163 | option httpchk |
| 4164 | option httpchk <uri> |
| 4165 | option httpchk <method> <uri> |
| 4166 | option httpchk <method> <uri> <version> |
| 4167 | Enable HTTP protocol to check on the servers health |
| 4168 | May be used in sections : defaults | frontend | listen | backend |
| 4169 | yes | no | yes | yes |
| 4170 | Arguments : |
| 4171 | <method> is the optional HTTP method used with the requests. When not set, |
| 4172 | the "OPTIONS" method is used, as it generally requires low server |
| 4173 | processing and is easy to filter out from the logs. Any method |
| 4174 | may be used, though it is not recommended to invent non-standard |
| 4175 | ones. |
| 4176 | |
| 4177 | <uri> is the URI referenced in the HTTP requests. It defaults to " / " |
| 4178 | which is accessible by default on almost any server, but may be |
| 4179 | changed to any other URI. Query strings are permitted. |
| 4180 | |
| 4181 | <version> is the optional HTTP version string. It defaults to "HTTP/1.0" |
| 4182 | but some servers might behave incorrectly in HTTP 1.0, so turning |
| 4183 | it to HTTP/1.1 may sometimes help. Note that the Host field is |
| 4184 | mandatory in HTTP/1.1, and as a trick, it is possible to pass it |
| 4185 | after "\r\n" following the version string. |
| 4186 | |
| 4187 | By default, server health checks only consist in trying to establish a TCP |
| 4188 | connection. When "option httpchk" is specified, a complete HTTP request is |
| 4189 | sent once the TCP connection is established, and responses 2xx and 3xx are |
| 4190 | considered valid, while all other ones indicate a server failure, including |
| 4191 | the lack of any response. |
| 4192 | |
| 4193 | The port and interval are specified in the server configuration. |
| 4194 | |
| 4195 | This option does not necessarily require an HTTP backend, it also works with |
| 4196 | plain TCP backends. This is particularly useful to check simple scripts bound |
| 4197 | to some dedicated ports using the inetd daemon. |
| 4198 | |
| 4199 | Examples : |
| 4200 | # Relay HTTPS traffic to Apache instance and check service availability |
| 4201 | # using HTTP request "OPTIONS * HTTP/1.1" on port 80. |
| 4202 | backend https_relay |
| 4203 | mode tcp |
| 4204 | option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www |
| 4205 | server apache1 192.168.1.1:443 check port 80 |
| 4206 | |
Simon Horman | afc47ee | 2013-11-25 10:46:35 +0900 | [diff] [blame] | 4207 | See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check", |
| 4208 | "option pgsql-check", "http-check" and the "check", "port" and |
| 4209 | "inter" server options. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 4210 | |
| 4211 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4212 | option httpclose |
| 4213 | no option httpclose |
| 4214 | Enable or disable passive HTTP connection closing |
| 4215 | May be used in sections : defaults | frontend | listen | backend |
| 4216 | yes | yes | yes | yes |
| 4217 | Arguments : none |
| 4218 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4219 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 4220 | connections: for each connection it processes each request and response, and |
| 4221 | leaves the connection idle on both sides between the end of a response and |
| 4222 | the start of a new request. This mode may be changed by several options such |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 4223 | as "option http-server-close", "option forceclose", "option httpclose" or |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4224 | "option http-tunnel". |
| 4225 | |
| 4226 | If "option httpclose" is set, HAProxy will work in HTTP tunnel mode and check |
| 4227 | if a "Connection: close" header is already set in each direction, and will |
| 4228 | add one if missing. Each end should react to this by actively closing the TCP |
| 4229 | connection after each transfer, thus resulting in a switch to the HTTP close |
| 4230 | mode. Any "Connection" header different from "close" will also be removed. |
| 4231 | Note that this option is deprecated since what it does is very cheap but not |
| 4232 | reliable. Using "option http-server-close" or "option forceclose" is strongly |
| 4233 | recommended instead. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4234 | |
| 4235 | It seldom happens that some servers incorrectly ignore this header and do not |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 4236 | close the connection even though they reply "Connection: close". For this |
Willy Tarreau | 0dfdf19 | 2010-01-05 11:33:11 +0100 | [diff] [blame] | 4237 | reason, they are not compatible with older HTTP 1.0 browsers. If this happens |
| 4238 | it is possible to use the "option forceclose" which actively closes the |
| 4239 | request connection once the server responds. Option "forceclose" also |
| 4240 | releases the server connection earlier because it does not have to wait for |
| 4241 | the client to acknowledge it. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4242 | |
| 4243 | This option may be set both in a frontend and in a backend. It is enabled if |
| 4244 | at least one of the frontend or backend holding a connection has it enabled. |
Cyril Bonté | 653dcd6 | 2014-02-20 00:13:15 +0100 | [diff] [blame] | 4245 | It disables and replaces any previous "option http-server-close", |
| 4246 | "option forceclose", "option http-keep-alive" or "option http-tunnel". Please |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 4247 | check section 4 ("Proxies") to see how this option combines with others when |
| 4248 | frontend and backend options differ. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4249 | |
| 4250 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4251 | in a specific instance by prepending the "no" keyword before it. |
| 4252 | |
Patrick Mezard | 9ec2ec4 | 2010-06-12 17:02:45 +0200 | [diff] [blame] | 4253 | See also : "option forceclose", "option http-server-close" and |
| 4254 | "1.1. The HTTP transaction model". |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4255 | |
| 4256 | |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 4257 | option httplog [ clf ] |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4258 | Enable logging of HTTP request, session state and timers |
| 4259 | May be used in sections : defaults | frontend | listen | backend |
| 4260 | yes | yes | yes | yes |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 4261 | Arguments : |
| 4262 | clf if the "clf" argument is added, then the output format will be |
| 4263 | the CLF format instead of HAProxy's default HTTP format. You can |
| 4264 | use this when you need to feed HAProxy's logs through a specific |
| 4265 | log analyser which only support the CLF format and which is not |
| 4266 | extensible. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4267 | |
| 4268 | By default, the log output format is very poor, as it only contains the |
| 4269 | source and destination addresses, and the instance name. By specifying |
| 4270 | "option httplog", each log line turns into a much richer format including, |
| 4271 | but not limited to, the HTTP request, the connection timers, the session |
| 4272 | status, the connections numbers, the captured headers and cookies, the |
| 4273 | frontend, backend and server name, and of course the source address and |
| 4274 | ports. |
| 4275 | |
| 4276 | This option may be set either in the frontend or the backend. |
| 4277 | |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 4278 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4279 | in a specific instance by prepending the "no" keyword before it. Specifying |
| 4280 | only "option httplog" will automatically clear the 'clf' mode if it was set |
| 4281 | by default. |
| 4282 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 4283 | See also : section 8 about logging. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4284 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 4285 | |
| 4286 | option http_proxy |
| 4287 | no option http_proxy |
| 4288 | Enable or disable plain HTTP proxy mode |
| 4289 | May be used in sections : defaults | frontend | listen | backend |
| 4290 | yes | yes | yes | yes |
| 4291 | Arguments : none |
| 4292 | |
| 4293 | It sometimes happens that people need a pure HTTP proxy which understands |
| 4294 | basic proxy requests without caching nor any fancy feature. In this case, |
| 4295 | it may be worth setting up an HAProxy instance with the "option http_proxy" |
| 4296 | set. In this mode, no server is declared, and the connection is forwarded to |
| 4297 | the IP address and port found in the URL after the "http://" scheme. |
| 4298 | |
| 4299 | No host address resolution is performed, so this only works when pure IP |
| 4300 | addresses are passed. Since this option's usage perimeter is rather limited, |
| 4301 | it will probably be used only by experts who know they need exactly it. Last, |
| 4302 | if the clients are susceptible of sending keep-alive requests, it will be |
Cyril Bonté | 2409e68 | 2010-12-14 22:47:51 +0100 | [diff] [blame] | 4303 | needed to add "option httpclose" to ensure that all requests will correctly |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 4304 | be analyzed. |
| 4305 | |
| 4306 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4307 | in a specific instance by prepending the "no" keyword before it. |
| 4308 | |
| 4309 | Example : |
| 4310 | # this backend understands HTTP proxy requests and forwards them directly. |
| 4311 | backend direct_forward |
| 4312 | option httpclose |
| 4313 | option http_proxy |
| 4314 | |
| 4315 | See also : "option httpclose" |
| 4316 | |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 4317 | |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 4318 | option independent-streams |
| 4319 | no option independent-streams |
| 4320 | Enable or disable independent timeout processing for both directions |
Willy Tarreau | f27b5ea | 2009-10-03 22:01:18 +0200 | [diff] [blame] | 4321 | May be used in sections : defaults | frontend | listen | backend |
| 4322 | yes | yes | yes | yes |
| 4323 | Arguments : none |
| 4324 | |
| 4325 | By default, when data is sent over a socket, both the write timeout and the |
| 4326 | read timeout for that socket are refreshed, because we consider that there is |
| 4327 | activity on that socket, and we have no other means of guessing if we should |
| 4328 | receive data or not. |
| 4329 | |
| 4330 | While this default behaviour is desirable for almost all applications, there |
| 4331 | exists a situation where it is desirable to disable it, and only refresh the |
| 4332 | read timeout if there are incoming data. This happens on sessions with large |
| 4333 | timeouts and low amounts of exchanged data such as telnet session. If the |
| 4334 | server suddenly disappears, the output data accumulates in the system's |
| 4335 | socket buffers, both timeouts are correctly refreshed, and there is no way |
| 4336 | to know the server does not receive them, so we don't timeout. However, when |
| 4337 | the underlying protocol always echoes sent data, it would be enough by itself |
| 4338 | to detect the issue using the read timeout. Note that this problem does not |
| 4339 | happen with more verbose protocols because data won't accumulate long in the |
| 4340 | socket buffers. |
| 4341 | |
| 4342 | When this option is set on the frontend, it will disable read timeout updates |
| 4343 | on data sent to the client. There probably is little use of this case. When |
| 4344 | the option is set on the backend, it will disable read timeout updates on |
| 4345 | data sent to the server. Doing so will typically break large HTTP posts from |
| 4346 | slow lines, so use it with caution. |
| 4347 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4348 | Note: older versions used to call this setting "option independent-streams" |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 4349 | with a spelling mistake. This spelling is still supported but |
| 4350 | deprecated. |
| 4351 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 4352 | See also : "timeout client", "timeout server" and "timeout tunnel" |
Willy Tarreau | f27b5ea | 2009-10-03 22:01:18 +0200 | [diff] [blame] | 4353 | |
| 4354 | |
Gabor Lekeny | b4c81e4 | 2010-09-29 18:17:05 +0200 | [diff] [blame] | 4355 | option ldap-check |
| 4356 | Use LDAPv3 health checks for server testing |
| 4357 | May be used in sections : defaults | frontend | listen | backend |
| 4358 | yes | no | yes | yes |
| 4359 | Arguments : none |
| 4360 | |
| 4361 | It is possible to test that the server correctly talks LDAPv3 instead of just |
| 4362 | testing that it accepts the TCP connection. When this option is set, an |
| 4363 | LDAPv3 anonymous simple bind message is sent to the server, and the response |
| 4364 | is analyzed to find an LDAPv3 bind response message. |
| 4365 | |
| 4366 | The server is considered valid only when the LDAP response contains success |
| 4367 | resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9). |
| 4368 | |
| 4369 | Logging of bind requests is server dependent see your documentation how to |
| 4370 | configure it. |
| 4371 | |
| 4372 | Example : |
| 4373 | option ldap-check |
| 4374 | |
| 4375 | See also : "option httpchk" |
| 4376 | |
| 4377 | |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 4378 | option log-health-checks |
| 4379 | no option log-health-checks |
| 4380 | Enable or disable logging of health checks |
| 4381 | May be used in sections : defaults | frontend | listen | backend |
| 4382 | yes | no | yes | yes |
| 4383 | Arguments : none |
| 4384 | |
| 4385 | Enable health checks logging so it possible to check for example what |
| 4386 | was happening before a server crash. Failed health check are logged if |
| 4387 | server is UP and succeeded health checks if server is DOWN, so the amount |
| 4388 | of additional information is limited. |
| 4389 | |
| 4390 | If health check logging is enabled no health check status is printed |
| 4391 | when servers is set up UP/DOWN/ENABLED/DISABLED. |
| 4392 | |
| 4393 | See also: "log" and section 8 about logging. |
| 4394 | |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 4395 | |
| 4396 | option log-separate-errors |
| 4397 | no option log-separate-errors |
| 4398 | Change log level for non-completely successful connections |
| 4399 | May be used in sections : defaults | frontend | listen | backend |
| 4400 | yes | yes | yes | no |
| 4401 | Arguments : none |
| 4402 | |
| 4403 | Sometimes looking for errors in logs is not easy. This option makes haproxy |
| 4404 | raise the level of logs containing potentially interesting information such |
| 4405 | as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The |
| 4406 | level changes from "info" to "err". This makes it possible to log them |
| 4407 | separately to a different file with most syslog daemons. Be careful not to |
| 4408 | remove them from the original file, otherwise you would lose ordering which |
| 4409 | provides very important information. |
| 4410 | |
| 4411 | Using this option, large sites dealing with several thousand connections per |
| 4412 | second may log normal traffic to a rotating buffer and only archive smaller |
| 4413 | error logs. |
| 4414 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 4415 | See also : "log", "dontlognull", "dontlog-normal" and section 8 about |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 4416 | logging. |
| 4417 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4418 | |
| 4419 | option logasap |
| 4420 | no option logasap |
| 4421 | Enable or disable early logging of HTTP requests |
| 4422 | May be used in sections : defaults | frontend | listen | backend |
| 4423 | yes | yes | yes | no |
| 4424 | Arguments : none |
| 4425 | |
| 4426 | By default, HTTP requests are logged upon termination so that the total |
| 4427 | transfer time and the number of bytes appear in the logs. When large objects |
| 4428 | are being transferred, it may take a while before the request appears in the |
| 4429 | logs. Using "option logasap", the request gets logged as soon as the server |
| 4430 | sends the complete headers. The only missing information in the logs will be |
| 4431 | the total number of bytes which will indicate everything except the amount |
| 4432 | of data transferred, and the total time which will not take the transfer |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 4433 | time into account. In such a situation, it's a good practice to capture the |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4434 | "Content-Length" response header so that the logs at least indicate how many |
| 4435 | bytes are expected to be transferred. |
| 4436 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 4437 | Examples : |
| 4438 | listen http_proxy 0.0.0.0:80 |
| 4439 | mode http |
| 4440 | option httplog |
| 4441 | option logasap |
| 4442 | log 192.168.2.200 local3 |
| 4443 | |
| 4444 | >>> Feb 6 12:14:14 localhost \ |
| 4445 | haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ |
| 4446 | static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \ |
| 4447 | "GET /image.iso HTTP/1.0" |
| 4448 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 4449 | See also : "option httplog", "capture response header", and section 8 about |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 4450 | logging. |
| 4451 | |
| 4452 | |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 4453 | option mysql-check [ user <username> ] |
| 4454 | Use MySQL health checks for server testing |
Hervé COMMOWICK | 698ae00 | 2010-01-12 09:25:13 +0100 | [diff] [blame] | 4455 | May be used in sections : defaults | frontend | listen | backend |
| 4456 | yes | no | yes | yes |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 4457 | Arguments : |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 4458 | <username> This is the username which will be used when connecting to MySQL |
| 4459 | server. |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 4460 | |
| 4461 | If you specify a username, the check consists of sending two MySQL packet, |
| 4462 | one Client Authentication packet, and one QUIT packet, to correctly close |
| 4463 | MySQL session. We then parse the MySQL Handshake Initialisation packet and/or |
| 4464 | Error packet. It is a basic but useful test which does not produce error nor |
| 4465 | aborted connect on the server. However, it requires adding an authorization |
| 4466 | in the MySQL table, like this : |
| 4467 | |
| 4468 | USE mysql; |
| 4469 | INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>'); |
| 4470 | FLUSH PRIVILEGES; |
| 4471 | |
| 4472 | If you don't specify a username (it is deprecated and not recommended), the |
| 4473 | check only consists in parsing the Mysql Handshake Initialisation packet or |
| 4474 | Error packet, we don't send anything in this mode. It was reported that it |
| 4475 | can generate lockout if check is too frequent and/or if there is not enough |
| 4476 | traffic. In fact, you need in this case to check MySQL "max_connect_errors" |
| 4477 | value as if a connection is established successfully within fewer than MySQL |
| 4478 | "max_connect_errors" attempts after a previous connection was interrupted, |
| 4479 | the error count for the host is cleared to zero. If HAProxy's server get |
| 4480 | blocked, the "FLUSH HOSTS" statement is the only way to unblock it. |
| 4481 | |
| 4482 | Remember that this does not check database presence nor database consistency. |
| 4483 | To do this, you can use an external check with xinetd for example. |
Hervé COMMOWICK | 698ae00 | 2010-01-12 09:25:13 +0100 | [diff] [blame] | 4484 | |
Hervé COMMOWICK | 212f778 | 2011-06-10 14:05:59 +0200 | [diff] [blame] | 4485 | The check requires MySQL >=3.22, for older version, please use TCP check. |
Hervé COMMOWICK | 698ae00 | 2010-01-12 09:25:13 +0100 | [diff] [blame] | 4486 | |
| 4487 | Most often, an incoming MySQL server needs to see the client's IP address for |
| 4488 | various purposes, including IP privilege matching and connection logging. |
| 4489 | When possible, it is often wise to masquerade the client's IP address when |
| 4490 | connecting to the server using the "usesrc" argument of the "source" keyword, |
| 4491 | which requires the cttproxy feature to be compiled in, and the MySQL server |
| 4492 | to route the client via the machine hosting haproxy. |
| 4493 | |
| 4494 | See also: "option httpchk" |
| 4495 | |
| 4496 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4497 | option nolinger |
| 4498 | no option nolinger |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 4499 | Enable or disable immediate session resource cleaning after close |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4500 | May be used in sections: defaults | frontend | listen | backend |
| 4501 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 4502 | Arguments : none |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4503 | |
| 4504 | When clients or servers abort connections in a dirty way (eg: they are |
| 4505 | physically disconnected), the session timeouts triggers and the session is |
| 4506 | closed. But it will remain in FIN_WAIT1 state for some time in the system, |
| 4507 | using some resources and possibly limiting the ability to establish newer |
| 4508 | connections. |
| 4509 | |
| 4510 | When this happens, it is possible to activate "option nolinger" which forces |
| 4511 | the system to immediately remove any socket's pending data on close. Thus, |
| 4512 | the session is instantly purged from the system's tables. This usually has |
| 4513 | side effects such as increased number of TCP resets due to old retransmits |
| 4514 | getting immediately rejected. Some firewalls may sometimes complain about |
| 4515 | this too. |
| 4516 | |
| 4517 | For this reason, it is not recommended to use this option when not absolutely |
| 4518 | needed. You know that you need it when you have thousands of FIN_WAIT1 |
| 4519 | sessions on your system (TIME_WAIT ones do not count). |
| 4520 | |
| 4521 | This option may be used both on frontends and backends, depending on the side |
| 4522 | where it is required. Use it on the frontend for clients, and on the backend |
| 4523 | for servers. |
| 4524 | |
| 4525 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4526 | in a specific instance by prepending the "no" keyword before it. |
| 4527 | |
| 4528 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 4529 | option originalto [ except <network> ] [ header <name> ] |
| 4530 | Enable insertion of the X-Original-To header to requests sent to servers |
| 4531 | May be used in sections : defaults | frontend | listen | backend |
| 4532 | yes | yes | yes | yes |
| 4533 | Arguments : |
| 4534 | <network> is an optional argument used to disable this option for sources |
| 4535 | matching <network> |
| 4536 | <name> an optional argument to specify a different "X-Original-To" |
| 4537 | header name. |
| 4538 | |
| 4539 | Since HAProxy can work in transparent mode, every request from a client can |
| 4540 | be redirected to the proxy and HAProxy itself can proxy every request to a |
| 4541 | complex SQUID environment and the destination host from SO_ORIGINAL_DST will |
| 4542 | be lost. This is annoying when you want access rules based on destination ip |
| 4543 | addresses. To solve this problem, a new HTTP header "X-Original-To" may be |
| 4544 | added by HAProxy to all requests sent to the server. This header contains a |
| 4545 | value representing the original destination IP address. Since this must be |
| 4546 | configured to always use the last occurrence of this header only. Note that |
| 4547 | only the last occurrence of the header must be used, since it is really |
| 4548 | possible that the client has already brought one. |
| 4549 | |
| 4550 | The keyword "header" may be used to supply a different header name to replace |
| 4551 | the default "X-Original-To". This can be useful where you might already |
| 4552 | have a "X-Original-To" header from a different application, and you need |
| 4553 | preserve it. Also if your backend server doesn't use the "X-Original-To" |
| 4554 | header and requires different one. |
| 4555 | |
| 4556 | Sometimes, a same HAProxy instance may be shared between a direct client |
| 4557 | access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| 4558 | used to decrypt HTTPS traffic). It is possible to disable the addition of the |
| 4559 | header for a known source address or network by adding the "except" keyword |
| 4560 | followed by the network address. In this case, any source IP matching the |
| 4561 | network will not cause an addition of this header. Most common uses are with |
| 4562 | private networks or 127.0.0.1. |
| 4563 | |
| 4564 | This option may be specified either in the frontend or in the backend. If at |
| 4565 | least one of them uses it, the header will be added. Note that the backend's |
| 4566 | setting of the header subargument takes precedence over the frontend's if |
| 4567 | both are defined. |
| 4568 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 4569 | Examples : |
| 4570 | # Original Destination address |
| 4571 | frontend www |
| 4572 | mode http |
| 4573 | option originalto except 127.0.0.1 |
| 4574 | |
| 4575 | # Those servers want the IP Address in X-Client-Dst |
| 4576 | backend www |
| 4577 | mode http |
| 4578 | option originalto header X-Client-Dst |
| 4579 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 4580 | See also : "option httpclose", "option http-server-close", |
| 4581 | "option forceclose" |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 4582 | |
| 4583 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4584 | option persist |
| 4585 | no option persist |
| 4586 | Enable or disable forced persistence on down servers |
| 4587 | May be used in sections: defaults | frontend | listen | backend |
| 4588 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 4589 | Arguments : none |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4590 | |
| 4591 | When an HTTP request reaches a backend with a cookie which references a dead |
| 4592 | server, by default it is redispatched to another server. It is possible to |
| 4593 | force the request to be sent to the dead server first using "option persist" |
| 4594 | if absolutely needed. A common use case is when servers are under extreme |
| 4595 | load and spend their time flapping. In this case, the users would still be |
| 4596 | directed to the server they opened the session on, in the hope they would be |
| 4597 | correctly served. It is recommended to use "option redispatch" in conjunction |
| 4598 | with this option so that in the event it would not be possible to connect to |
| 4599 | the server at all (server definitely dead), the client would finally be |
| 4600 | redirected to another valid server. |
| 4601 | |
| 4602 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4603 | in a specific instance by prepending the "no" keyword before it. |
| 4604 | |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 4605 | See also : "option redispatch", "retries", "force-persist" |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4606 | |
| 4607 | |
Willy Tarreau | 0c12282 | 2013-12-15 18:49:01 +0100 | [diff] [blame] | 4608 | option pgsql-check [ user <username> ] |
| 4609 | Use PostgreSQL health checks for server testing |
| 4610 | May be used in sections : defaults | frontend | listen | backend |
| 4611 | yes | no | yes | yes |
| 4612 | Arguments : |
| 4613 | <username> This is the username which will be used when connecting to |
| 4614 | PostgreSQL server. |
| 4615 | |
| 4616 | The check sends a PostgreSQL StartupMessage and waits for either |
| 4617 | Authentication request or ErrorResponse message. It is a basic but useful |
| 4618 | test which does not produce error nor aborted connect on the server. |
| 4619 | This check is identical with the "mysql-check". |
| 4620 | |
| 4621 | See also: "option httpchk" |
| 4622 | |
| 4623 | |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 4624 | option prefer-last-server |
| 4625 | no option prefer-last-server |
| 4626 | Allow multiple load balanced requests to remain on the same server |
| 4627 | May be used in sections: defaults | frontend | listen | backend |
| 4628 | yes | no | yes | yes |
| 4629 | Arguments : none |
| 4630 | |
| 4631 | When the load balancing algorithm in use is not deterministic, and a previous |
| 4632 | request was sent to a server to which haproxy still holds a connection, it is |
| 4633 | sometimes desirable that subsequent requests on a same session go to the same |
| 4634 | server as much as possible. Note that this is different from persistence, as |
| 4635 | we only indicate a preference which haproxy tries to apply without any form |
| 4636 | of warranty. The real use is for keep-alive connections sent to servers. When |
| 4637 | this option is used, haproxy will try to reuse the same connection that is |
| 4638 | attached to the server instead of rebalancing to another server, causing a |
| 4639 | close of the connection. This can make sense for static file servers. It does |
Willy Tarreau | 068621e | 2013-12-23 15:11:25 +0100 | [diff] [blame] | 4640 | not make much sense to use this in combination with hashing algorithms. Note, |
| 4641 | haproxy already automatically tries to stick to a server which sends a 401 or |
| 4642 | to a proxy which sends a 407 (authentication required). This is mandatory for |
| 4643 | use with the broken NTLM authentication challenge, and significantly helps in |
| 4644 | troubleshooting some faulty applications. Option prefer-last-server might be |
| 4645 | desirable in these environments as well, to avoid redistributing the traffic |
| 4646 | after every other response. |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 4647 | |
| 4648 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4649 | in a specific instance by prepending the "no" keyword before it. |
| 4650 | |
| 4651 | See also: "option http-keep-alive" |
| 4652 | |
| 4653 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 4654 | option redispatch |
| 4655 | no option redispatch |
| 4656 | Enable or disable session redistribution in case of connection failure |
| 4657 | May be used in sections: defaults | frontend | listen | backend |
| 4658 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 4659 | Arguments : none |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 4660 | |
| 4661 | In HTTP mode, if a server designated by a cookie is down, clients may |
| 4662 | definitely stick to it because they cannot flush the cookie, so they will not |
| 4663 | be able to access the service anymore. |
| 4664 | |
| 4665 | Specifying "option redispatch" will allow the proxy to break their |
| 4666 | persistence and redistribute them to a working server. |
| 4667 | |
| 4668 | It also allows to retry last connection to another server in case of multiple |
| 4669 | connection failures. Of course, it requires having "retries" set to a nonzero |
| 4670 | value. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 4671 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 4672 | This form is the preferred form, which replaces both the "redispatch" and |
| 4673 | "redisp" keywords. |
| 4674 | |
| 4675 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4676 | in a specific instance by prepending the "no" keyword before it. |
| 4677 | |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 4678 | See also : "redispatch", "retries", "force-persist" |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 4679 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4680 | |
Hervé COMMOWICK | ec032d6 | 2011-08-05 16:23:48 +0200 | [diff] [blame] | 4681 | option redis-check |
| 4682 | Use redis health checks for server testing |
| 4683 | May be used in sections : defaults | frontend | listen | backend |
| 4684 | yes | no | yes | yes |
| 4685 | Arguments : none |
| 4686 | |
| 4687 | It is possible to test that the server correctly talks REDIS protocol instead |
| 4688 | of just testing that it accepts the TCP connection. When this option is set, |
| 4689 | a PING redis command is sent to the server, and the response is analyzed to |
| 4690 | find the "+PONG" response message. |
| 4691 | |
| 4692 | Example : |
| 4693 | option redis-check |
| 4694 | |
| 4695 | See also : "option httpchk" |
| 4696 | |
| 4697 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4698 | option smtpchk |
| 4699 | option smtpchk <hello> <domain> |
| 4700 | Use SMTP health checks for server testing |
| 4701 | May be used in sections : defaults | frontend | listen | backend |
| 4702 | yes | no | yes | yes |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 4703 | Arguments : |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4704 | <hello> is an optional argument. It is the "hello" command to use. It can |
| 4705 | be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other |
| 4706 | values will be turned into the default command ("HELO"). |
| 4707 | |
| 4708 | <domain> is the domain name to present to the server. It may only be |
| 4709 | specified (and is mandatory) if the hello command has been |
| 4710 | specified. By default, "localhost" is used. |
| 4711 | |
| 4712 | When "option smtpchk" is set, the health checks will consist in TCP |
| 4713 | connections followed by an SMTP command. By default, this command is |
| 4714 | "HELO localhost". The server's return code is analyzed and only return codes |
| 4715 | starting with a "2" will be considered as valid. All other responses, |
| 4716 | including a lack of response will constitute an error and will indicate a |
| 4717 | dead server. |
| 4718 | |
| 4719 | This test is meant to be used with SMTP servers or relays. Depending on the |
| 4720 | request, it is possible that some servers do not log each connection attempt, |
| 4721 | so you may want to experiment to improve the behaviour. Using telnet on port |
| 4722 | 25 is often easier than adjusting the configuration. |
| 4723 | |
| 4724 | Most often, an incoming SMTP server needs to see the client's IP address for |
| 4725 | various purposes, including spam filtering, anti-spoofing and logging. When |
| 4726 | possible, it is often wise to masquerade the client's IP address when |
| 4727 | connecting to the server using the "usesrc" argument of the "source" keyword, |
| 4728 | which requires the cttproxy feature to be compiled in. |
| 4729 | |
| 4730 | Example : |
| 4731 | option smtpchk HELO mydomain.org |
| 4732 | |
| 4733 | See also : "option httpchk", "source" |
| 4734 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 4735 | |
Krzysztof Piotr Oledzki | aeebf9b | 2009-10-04 15:43:17 +0200 | [diff] [blame] | 4736 | option socket-stats |
| 4737 | no option socket-stats |
| 4738 | |
| 4739 | Enable or disable collecting & providing separate statistics for each socket. |
| 4740 | May be used in sections : defaults | frontend | listen | backend |
| 4741 | yes | yes | yes | no |
| 4742 | |
| 4743 | Arguments : none |
| 4744 | |
| 4745 | |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 4746 | option splice-auto |
| 4747 | no option splice-auto |
| 4748 | Enable or disable automatic kernel acceleration on sockets in both directions |
| 4749 | May be used in sections : defaults | frontend | listen | backend |
| 4750 | yes | yes | yes | yes |
| 4751 | Arguments : none |
| 4752 | |
| 4753 | When this option is enabled either on a frontend or on a backend, haproxy |
| 4754 | will automatically evaluate the opportunity to use kernel tcp splicing to |
| 4755 | forward data between the client and the server, in either direction. Haproxy |
| 4756 | uses heuristics to estimate if kernel splicing might improve performance or |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 4757 | not. Both directions are handled independently. Note that the heuristics used |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 4758 | are not much aggressive in order to limit excessive use of splicing. This |
| 4759 | option requires splicing to be enabled at compile time, and may be globally |
| 4760 | disabled with the global option "nosplice". Since splice uses pipes, using it |
| 4761 | requires that there are enough spare pipes. |
| 4762 | |
| 4763 | Important note: kernel-based TCP splicing is a Linux-specific feature which |
| 4764 | first appeared in kernel 2.6.25. It offers kernel-based acceleration to |
| 4765 | transfer data between sockets without copying these data to user-space, thus |
| 4766 | providing noticeable performance gains and CPU cycles savings. Since many |
| 4767 | early implementations are buggy, corrupt data and/or are inefficient, this |
| 4768 | feature is not enabled by default, and it should be used with extreme care. |
| 4769 | While it is not possible to detect the correctness of an implementation, |
| 4770 | 2.6.29 is the first version offering a properly working implementation. In |
| 4771 | case of doubt, splicing may be globally disabled using the global "nosplice" |
| 4772 | keyword. |
| 4773 | |
| 4774 | Example : |
| 4775 | option splice-auto |
| 4776 | |
| 4777 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4778 | in a specific instance by prepending the "no" keyword before it. |
| 4779 | |
| 4780 | See also : "option splice-request", "option splice-response", and global |
| 4781 | options "nosplice" and "maxpipes" |
| 4782 | |
| 4783 | |
| 4784 | option splice-request |
| 4785 | no option splice-request |
| 4786 | Enable or disable automatic kernel acceleration on sockets for requests |
| 4787 | May be used in sections : defaults | frontend | listen | backend |
| 4788 | yes | yes | yes | yes |
| 4789 | Arguments : none |
| 4790 | |
| 4791 | When this option is enabled either on a frontend or on a backend, haproxy |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 4792 | will use kernel tcp splicing whenever possible to forward data going from |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 4793 | the client to the server. It might still use the recv/send scheme if there |
| 4794 | are no spare pipes left. This option requires splicing to be enabled at |
| 4795 | compile time, and may be globally disabled with the global option "nosplice". |
| 4796 | Since splice uses pipes, using it requires that there are enough spare pipes. |
| 4797 | |
| 4798 | Important note: see "option splice-auto" for usage limitations. |
| 4799 | |
| 4800 | Example : |
| 4801 | option splice-request |
| 4802 | |
| 4803 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4804 | in a specific instance by prepending the "no" keyword before it. |
| 4805 | |
| 4806 | See also : "option splice-auto", "option splice-response", and global options |
| 4807 | "nosplice" and "maxpipes" |
| 4808 | |
| 4809 | |
| 4810 | option splice-response |
| 4811 | no option splice-response |
| 4812 | Enable or disable automatic kernel acceleration on sockets for responses |
| 4813 | May be used in sections : defaults | frontend | listen | backend |
| 4814 | yes | yes | yes | yes |
| 4815 | Arguments : none |
| 4816 | |
| 4817 | When this option is enabled either on a frontend or on a backend, haproxy |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 4818 | will use kernel tcp splicing whenever possible to forward data going from |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 4819 | the server to the client. It might still use the recv/send scheme if there |
| 4820 | are no spare pipes left. This option requires splicing to be enabled at |
| 4821 | compile time, and may be globally disabled with the global option "nosplice". |
| 4822 | Since splice uses pipes, using it requires that there are enough spare pipes. |
| 4823 | |
| 4824 | Important note: see "option splice-auto" for usage limitations. |
| 4825 | |
| 4826 | Example : |
| 4827 | option splice-response |
| 4828 | |
| 4829 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4830 | in a specific instance by prepending the "no" keyword before it. |
| 4831 | |
| 4832 | See also : "option splice-auto", "option splice-request", and global options |
| 4833 | "nosplice" and "maxpipes" |
| 4834 | |
| 4835 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 4836 | option srvtcpka |
| 4837 | no option srvtcpka |
| 4838 | Enable or disable the sending of TCP keepalive packets on the server side |
| 4839 | May be used in sections : defaults | frontend | listen | backend |
| 4840 | yes | no | yes | yes |
| 4841 | Arguments : none |
| 4842 | |
| 4843 | When there is a firewall or any session-aware component between a client and |
| 4844 | a server, and when the protocol involves very long sessions with long idle |
| 4845 | periods (eg: remote desktops), there is a risk that one of the intermediate |
| 4846 | components decides to expire a session which has remained idle for too long. |
| 4847 | |
| 4848 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 4849 | to the other end of the connection, leaving it active. The delay between |
| 4850 | keep-alive probes is controlled by the system only and depends both on the |
| 4851 | operating system and its tuning parameters. |
| 4852 | |
| 4853 | It is important to understand that keep-alive packets are neither emitted nor |
| 4854 | received at the application level. It is only the network stacks which sees |
| 4855 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 4856 | to maintain its connection alive, those keep-alive packets will not be |
| 4857 | forwarded to the other side of the proxy. |
| 4858 | |
| 4859 | Please note that this has nothing to do with HTTP keep-alive. |
| 4860 | |
| 4861 | Using option "srvtcpka" enables the emission of TCP keep-alive probes on the |
| 4862 | server side of a connection, which should help when session expirations are |
| 4863 | noticed between HAProxy and a server. |
| 4864 | |
| 4865 | If this option has been enabled in a "defaults" section, it can be disabled |
| 4866 | in a specific instance by prepending the "no" keyword before it. |
| 4867 | |
| 4868 | See also : "option clitcpka", "option tcpka" |
| 4869 | |
| 4870 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4871 | option ssl-hello-chk |
| 4872 | Use SSLv3 client hello health checks for server testing |
| 4873 | May be used in sections : defaults | frontend | listen | backend |
| 4874 | yes | no | yes | yes |
| 4875 | Arguments : none |
| 4876 | |
| 4877 | When some SSL-based protocols are relayed in TCP mode through HAProxy, it is |
| 4878 | possible to test that the server correctly talks SSL instead of just testing |
| 4879 | that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure |
| 4880 | SSLv3 client hello messages are sent once the connection is established to |
| 4881 | the server, and the response is analyzed to find an SSL server hello message. |
| 4882 | The server is considered valid only when the response contains this server |
| 4883 | hello message. |
| 4884 | |
| 4885 | All servers tested till there correctly reply to SSLv3 client hello messages, |
| 4886 | and most servers tested do not even log the requests containing only hello |
| 4887 | messages, which is appreciable. |
| 4888 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 4889 | Note that this check works even when SSL support was not built into haproxy |
| 4890 | because it forges the SSL message. When SSL support is available, it is best |
| 4891 | to use native SSL health checks instead of this one. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4892 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 4893 | See also: "option httpchk", "check-ssl" |
| 4894 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 4895 | |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 4896 | option tcp-check |
| 4897 | Perform health checks using tcp-check send/expect sequences |
| 4898 | May be used in sections: defaults | frontend | listen | backend |
| 4899 | yes | no | yes | yes |
| 4900 | |
| 4901 | This health check method is intended to be combined with "tcp-check" command |
| 4902 | lists in order to support send/expect types of health check sequences. |
| 4903 | |
| 4904 | TCP checks currently support 4 modes of operations : |
| 4905 | - no "tcp-check" directive : the health check only consists in a connection |
| 4906 | attempt, which remains the default mode. |
| 4907 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4908 | - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 4909 | used to send a string along with a connection opening. With some |
| 4910 | protocols, it helps sending a "QUIT" message for example that prevents |
| 4911 | the server from logging a connection error for each health check. The |
| 4912 | check result will still be based on the ability to open the connection |
| 4913 | only. |
| 4914 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4915 | - "tcp-check expect" only is mentioned : this is used to test a banner. |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 4916 | The connection is opened and haproxy waits for the server to present some |
| 4917 | contents which must validate some rules. The check result will be based |
| 4918 | on the matching between the contents and the rules. This is suited for |
| 4919 | POP, IMAP, SMTP, FTP, SSH, TELNET. |
| 4920 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4921 | - both "tcp-check send" and "tcp-check expect" are mentioned : this is |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 4922 | used to test a hello-type protocol. Haproxy sends a message, the server |
| 4923 | responds and its response is analysed. the check result will be based on |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4924 | the matching between the response contents and the rules. This is often |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 4925 | suited for protocols which require a binding or a request/response model. |
| 4926 | LDAP, MySQL, Redis and SSL are example of such protocols, though they |
| 4927 | already all have their dedicated checks with a deeper understanding of |
| 4928 | the respective protocols. |
| 4929 | In this mode, many questions may be sent and many answers may be |
| 4930 | analysed. |
| 4931 | |
| 4932 | Examples : |
| 4933 | # perform a POP check (analyse only server's banner) |
| 4934 | option tcp-check |
| 4935 | tcp-check expect string +OK\ POP3\ ready |
| 4936 | |
| 4937 | # perform an IMAP check (analyse only server's banner) |
| 4938 | option tcp-check |
| 4939 | tcp-check expect string *\ OK\ IMAP4\ ready |
| 4940 | |
| 4941 | # look for the redis master server after ensuring it speaks well |
| 4942 | # redis protocol, then it exits properly. |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 4943 | # (send a command then analyse the response 3 times) |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 4944 | option tcp-check |
| 4945 | tcp-check send PING\r\n |
| 4946 | tcp-check expect +PONG |
| 4947 | tcp-check send info\ replication\r\n |
| 4948 | tcp-check expect string role:master |
| 4949 | tcp-check send QUIT\r\n |
| 4950 | tcp-check expect string +OK |
| 4951 | |
| 4952 | forge a HTTP request, then analyse the response |
| 4953 | (send many headers before analyzing) |
| 4954 | option tcp-check |
| 4955 | tcp-check send HEAD\ /\ HTTP/1.1\r\n |
| 4956 | tcp-check send Host:\ www.mydomain.com\r\n |
| 4957 | tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n |
| 4958 | tcp-check send \r\n |
| 4959 | tcp-check expect rstring HTTP/1\..\ (2..|3..) |
| 4960 | |
| 4961 | |
| 4962 | See also : "tcp-check expect", "tcp-check send" |
| 4963 | |
| 4964 | |
Willy Tarreau | 9ea05a7 | 2009-06-14 12:07:01 +0200 | [diff] [blame] | 4965 | option tcp-smart-accept |
| 4966 | no option tcp-smart-accept |
| 4967 | Enable or disable the saving of one ACK packet during the accept sequence |
| 4968 | May be used in sections : defaults | frontend | listen | backend |
| 4969 | yes | yes | yes | no |
| 4970 | Arguments : none |
| 4971 | |
| 4972 | When an HTTP connection request comes in, the system acknowledges it on |
| 4973 | behalf of HAProxy, then the client immediately sends its request, and the |
| 4974 | system acknowledges it too while it is notifying HAProxy about the new |
| 4975 | connection. HAProxy then reads the request and responds. This means that we |
| 4976 | have one TCP ACK sent by the system for nothing, because the request could |
| 4977 | very well be acknowledged by HAProxy when it sends its response. |
| 4978 | |
| 4979 | For this reason, in HTTP mode, HAProxy automatically asks the system to avoid |
| 4980 | sending this useless ACK on platforms which support it (currently at least |
| 4981 | Linux). It must not cause any problem, because the system will send it anyway |
| 4982 | after 40 ms if the response takes more time than expected to come. |
| 4983 | |
| 4984 | During complex network debugging sessions, it may be desirable to disable |
| 4985 | this optimization because delayed ACKs can make troubleshooting more complex |
| 4986 | when trying to identify where packets are delayed. It is then possible to |
| 4987 | fall back to normal behaviour by specifying "no option tcp-smart-accept". |
| 4988 | |
| 4989 | It is also possible to force it for non-HTTP proxies by simply specifying |
| 4990 | "option tcp-smart-accept". For instance, it can make sense with some services |
| 4991 | such as SMTP where the server speaks first. |
| 4992 | |
| 4993 | It is recommended to avoid forcing this option in a defaults section. In case |
| 4994 | of doubt, consider setting it back to automatic values by prepending the |
| 4995 | "default" keyword before it, or disabling it using the "no" keyword. |
| 4996 | |
Willy Tarreau | d88edf2 | 2009-06-14 15:48:17 +0200 | [diff] [blame] | 4997 | See also : "option tcp-smart-connect" |
| 4998 | |
| 4999 | |
| 5000 | option tcp-smart-connect |
| 5001 | no option tcp-smart-connect |
| 5002 | Enable or disable the saving of one ACK packet during the connect sequence |
| 5003 | May be used in sections : defaults | frontend | listen | backend |
| 5004 | yes | no | yes | yes |
| 5005 | Arguments : none |
| 5006 | |
| 5007 | On certain systems (at least Linux), HAProxy can ask the kernel not to |
| 5008 | immediately send an empty ACK upon a connection request, but to directly |
| 5009 | send the buffer request instead. This saves one packet on the network and |
| 5010 | thus boosts performance. It can also be useful for some servers, because they |
| 5011 | immediately get the request along with the incoming connection. |
| 5012 | |
| 5013 | This feature is enabled when "option tcp-smart-connect" is set in a backend. |
| 5014 | It is not enabled by default because it makes network troubleshooting more |
| 5015 | complex. |
| 5016 | |
| 5017 | It only makes sense to enable it with protocols where the client speaks first |
| 5018 | such as HTTP. In other situations, if there is no data to send in place of |
| 5019 | the ACK, a normal ACK is sent. |
| 5020 | |
| 5021 | If this option has been enabled in a "defaults" section, it can be disabled |
| 5022 | in a specific instance by prepending the "no" keyword before it. |
| 5023 | |
| 5024 | See also : "option tcp-smart-accept" |
| 5025 | |
Willy Tarreau | 9ea05a7 | 2009-06-14 12:07:01 +0200 | [diff] [blame] | 5026 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 5027 | option tcpka |
| 5028 | Enable or disable the sending of TCP keepalive packets on both sides |
| 5029 | May be used in sections : defaults | frontend | listen | backend |
| 5030 | yes | yes | yes | yes |
| 5031 | Arguments : none |
| 5032 | |
| 5033 | When there is a firewall or any session-aware component between a client and |
| 5034 | a server, and when the protocol involves very long sessions with long idle |
| 5035 | periods (eg: remote desktops), there is a risk that one of the intermediate |
| 5036 | components decides to expire a session which has remained idle for too long. |
| 5037 | |
| 5038 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 5039 | to the other end of the connection, leaving it active. The delay between |
| 5040 | keep-alive probes is controlled by the system only and depends both on the |
| 5041 | operating system and its tuning parameters. |
| 5042 | |
| 5043 | It is important to understand that keep-alive packets are neither emitted nor |
| 5044 | received at the application level. It is only the network stacks which sees |
| 5045 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 5046 | to maintain its connection alive, those keep-alive packets will not be |
| 5047 | forwarded to the other side of the proxy. |
| 5048 | |
| 5049 | Please note that this has nothing to do with HTTP keep-alive. |
| 5050 | |
| 5051 | Using option "tcpka" enables the emission of TCP keep-alive probes on both |
| 5052 | the client and server sides of a connection. Note that this is meaningful |
| 5053 | only in "defaults" or "listen" sections. If this option is used in a |
| 5054 | frontend, only the client side will get keep-alives, and if this option is |
| 5055 | used in a backend, only the server side will get keep-alives. For this |
| 5056 | reason, it is strongly recommended to explicitly use "option clitcpka" and |
| 5057 | "option srvtcpka" when the configuration is split between frontends and |
| 5058 | backends. |
| 5059 | |
| 5060 | See also : "option clitcpka", "option srvtcpka" |
| 5061 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5062 | |
| 5063 | option tcplog |
| 5064 | Enable advanced logging of TCP connections with session state and timers |
| 5065 | May be used in sections : defaults | frontend | listen | backend |
| 5066 | yes | yes | yes | yes |
| 5067 | Arguments : none |
| 5068 | |
| 5069 | By default, the log output format is very poor, as it only contains the |
| 5070 | source and destination addresses, and the instance name. By specifying |
| 5071 | "option tcplog", each log line turns into a much richer format including, but |
| 5072 | not limited to, the connection timers, the session status, the connections |
| 5073 | numbers, the frontend, backend and server name, and of course the source |
| 5074 | address and ports. This option is useful for pure TCP proxies in order to |
| 5075 | find which of the client or server disconnects or times out. For normal HTTP |
| 5076 | proxies, it's better to use "option httplog" which is even more complete. |
| 5077 | |
| 5078 | This option may be set either in the frontend or the backend. |
| 5079 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5080 | See also : "option httplog", and section 8 about logging. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5081 | |
| 5082 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5083 | option transparent |
| 5084 | no option transparent |
| 5085 | Enable client-side transparent proxying |
| 5086 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 4b1f859 | 2008-12-23 23:13:55 +0100 | [diff] [blame] | 5087 | yes | no | yes | yes |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5088 | Arguments : none |
| 5089 | |
| 5090 | This option was introduced in order to provide layer 7 persistence to layer 3 |
| 5091 | load balancers. The idea is to use the OS's ability to redirect an incoming |
| 5092 | connection for a remote address to a local process (here HAProxy), and let |
| 5093 | this process know what address was initially requested. When this option is |
| 5094 | used, sessions without cookies will be forwarded to the original destination |
| 5095 | IP address of the incoming request (which should match that of another |
| 5096 | equipment), while requests with cookies will still be forwarded to the |
| 5097 | appropriate server. |
| 5098 | |
| 5099 | Note that contrary to a common belief, this option does NOT make HAProxy |
| 5100 | present the client's IP to the server when establishing the connection. |
| 5101 | |
Willy Tarreau | a114605 | 2011-03-01 09:51:54 +0100 | [diff] [blame] | 5102 | See also: the "usesrc" argument of the "source" keyword, and the |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5103 | "transparent" option of the "bind" keyword. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5104 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 5105 | |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5106 | persist rdp-cookie |
Hervé COMMOWICK | a3eb39c | 2011-08-05 18:48:51 +0200 | [diff] [blame] | 5107 | persist rdp-cookie(<name>) |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5108 | Enable RDP cookie-based persistence |
| 5109 | May be used in sections : defaults | frontend | listen | backend |
| 5110 | yes | no | yes | yes |
| 5111 | Arguments : |
| 5112 | <name> is the optional name of the RDP cookie to check. If omitted, the |
Willy Tarreau | 61e28f2 | 2010-05-16 22:31:05 +0200 | [diff] [blame] | 5113 | default cookie name "msts" will be used. There currently is no |
| 5114 | valid reason to change this name. |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5115 | |
| 5116 | This statement enables persistence based on an RDP cookie. The RDP cookie |
| 5117 | contains all information required to find the server in the list of known |
| 5118 | servers. So when this option is set in the backend, the request is analysed |
| 5119 | and if an RDP cookie is found, it is decoded. If it matches a known server |
| 5120 | which is still UP (or if "option persist" is set), then the connection is |
| 5121 | forwarded to this server. |
| 5122 | |
| 5123 | Note that this only makes sense in a TCP backend, but for this to work, the |
| 5124 | frontend must have waited long enough to ensure that an RDP cookie is present |
| 5125 | in the request buffer. This is the same requirement as with the "rdp-cookie" |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 5126 | load-balancing method. Thus it is highly recommended to put all statements in |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5127 | a single "listen" section. |
| 5128 | |
Willy Tarreau | 61e28f2 | 2010-05-16 22:31:05 +0200 | [diff] [blame] | 5129 | Also, it is important to understand that the terminal server will emit this |
| 5130 | RDP cookie only if it is configured for "token redirection mode", which means |
| 5131 | that the "IP address redirection" option is disabled. |
| 5132 | |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5133 | Example : |
| 5134 | listen tse-farm |
| 5135 | bind :3389 |
| 5136 | # wait up to 5s for an RDP cookie in the request |
| 5137 | tcp-request inspect-delay 5s |
| 5138 | tcp-request content accept if RDP_COOKIE |
| 5139 | # apply RDP cookie persistence |
| 5140 | persist rdp-cookie |
| 5141 | # if server is unknown, let's balance on the same cookie. |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 5142 | # alternatively, "balance leastconn" may be useful too. |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5143 | balance rdp-cookie |
| 5144 | server srv1 1.1.1.1:3389 |
| 5145 | server srv2 1.1.1.2:3389 |
| 5146 | |
Simon Horman | ab814e0 | 2011-06-24 14:50:20 +0900 | [diff] [blame] | 5147 | See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and |
| 5148 | the rdp_cookie pattern fetch function. |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 5149 | |
| 5150 | |
Willy Tarreau | 3a7d207 | 2009-03-05 23:48:25 +0100 | [diff] [blame] | 5151 | rate-limit sessions <rate> |
| 5152 | Set a limit on the number of new sessions accepted per second on a frontend |
| 5153 | May be used in sections : defaults | frontend | listen | backend |
| 5154 | yes | yes | yes | no |
| 5155 | Arguments : |
| 5156 | <rate> The <rate> parameter is an integer designating the maximum number |
| 5157 | of new sessions per second to accept on the frontend. |
| 5158 | |
| 5159 | When the frontend reaches the specified number of new sessions per second, it |
| 5160 | stops accepting new connections until the rate drops below the limit again. |
| 5161 | During this time, the pending sessions will be kept in the socket's backlog |
| 5162 | (in system buffers) and haproxy will not even be aware that sessions are |
| 5163 | pending. When applying very low limit on a highly loaded service, it may make |
| 5164 | sense to increase the socket's backlog using the "backlog" keyword. |
| 5165 | |
| 5166 | This feature is particularly efficient at blocking connection-based attacks |
| 5167 | or service abuse on fragile servers. Since the session rate is measured every |
| 5168 | millisecond, it is extremely accurate. Also, the limit applies immediately, |
| 5169 | no delay is needed at all to detect the threshold. |
| 5170 | |
| 5171 | Example : limit the connection rate on SMTP to 10 per second max |
| 5172 | listen smtp |
| 5173 | mode tcp |
| 5174 | bind :25 |
| 5175 | rate-limit sessions 10 |
| 5176 | server 127.0.0.1:1025 |
| 5177 | |
Willy Tarreau | a17c2d9 | 2011-07-25 08:16:20 +0200 | [diff] [blame] | 5178 | Note : when the maximum rate is reached, the frontend's status is not changed |
| 5179 | but its sockets appear as "WAITING" in the statistics if the |
| 5180 | "socket-stats" option is enabled. |
Willy Tarreau | 3a7d207 | 2009-03-05 23:48:25 +0100 | [diff] [blame] | 5181 | |
| 5182 | See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion. |
| 5183 | |
| 5184 | |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5185 | redirect location <loc> [code <code>] <option> [{if | unless} <condition>] |
| 5186 | redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>] |
| 5187 | redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>] |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 5188 | Return an HTTP redirection if/unless a condition is matched |
| 5189 | May be used in sections : defaults | frontend | listen | backend |
| 5190 | no | yes | yes | yes |
| 5191 | |
| 5192 | If/unless the condition is matched, the HTTP request will lead to a redirect |
Willy Tarreau | f285f54 | 2010-01-03 20:03:03 +0100 | [diff] [blame] | 5193 | response. If no condition is specified, the redirect applies unconditionally. |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 5194 | |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5195 | Arguments : |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5196 | <loc> With "redirect location", the exact value in <loc> is placed into |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 5197 | the HTTP "Location" header. When used in an "http-request" rule, |
| 5198 | <loc> value follows the log-format rules and can include some |
| 5199 | dynamic values (see Custom Log Format in section 8.2.4). |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5200 | |
| 5201 | <pfx> With "redirect prefix", the "Location" header is built from the |
| 5202 | concatenation of <pfx> and the complete URI path, including the |
| 5203 | query string, unless the "drop-query" option is specified (see |
| 5204 | below). As a special case, if <pfx> equals exactly "/", then |
| 5205 | nothing is inserted before the original URI. It allows one to |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 5206 | redirect to the same URL (for instance, to insert a cookie). When |
| 5207 | used in an "http-request" rule, <pfx> value follows the log-format |
| 5208 | rules and can include some dynamic values (see Custom Log Format |
| 5209 | in section 8.2.4). |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5210 | |
| 5211 | <sch> With "redirect scheme", then the "Location" header is built by |
| 5212 | concatenating <sch> with "://" then the first occurrence of the |
| 5213 | "Host" header, and then the URI path, including the query string |
| 5214 | unless the "drop-query" option is specified (see below). If no |
| 5215 | path is found or if the path is "*", then "/" is used instead. If |
| 5216 | no "Host" header is found, then an empty host component will be |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 5217 | returned, which most recent browsers interpret as redirecting to |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5218 | the same host. This directive is mostly used to redirect HTTP to |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 5219 | HTTPS. When used in an "http-request" rule, <sch> value follows |
| 5220 | the log-format rules and can include some dynamic values (see |
| 5221 | Custom Log Format in section 8.2.4). |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5222 | |
| 5223 | <code> The code is optional. It indicates which type of HTTP redirection |
Willy Tarreau | b67fdc4 | 2013-03-29 19:28:11 +0100 | [diff] [blame] | 5224 | is desired. Only codes 301, 302, 303, 307 and 308 are supported, |
| 5225 | with 302 used by default if no code is specified. 301 means |
| 5226 | "Moved permanently", and a browser may cache the Location. 302 |
| 5227 | means "Moved permanently" and means that the browser should not |
| 5228 | cache the redirection. 303 is equivalent to 302 except that the |
| 5229 | browser will fetch the location with a GET method. 307 is just |
| 5230 | like 302 but makes it clear that the same method must be reused. |
| 5231 | Likewise, 308 replaces 301 if the same method must be used. |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5232 | |
| 5233 | <option> There are several options which can be specified to adjust the |
| 5234 | expected behaviour of a redirection : |
| 5235 | |
| 5236 | - "drop-query" |
| 5237 | When this keyword is used in a prefix-based redirection, then the |
| 5238 | location will be set without any possible query-string, which is useful |
| 5239 | for directing users to a non-secure page for instance. It has no effect |
| 5240 | with a location-type redirect. |
| 5241 | |
Willy Tarreau | 81e3b4f | 2010-01-10 00:42:19 +0100 | [diff] [blame] | 5242 | - "append-slash" |
| 5243 | This keyword may be used in conjunction with "drop-query" to redirect |
| 5244 | users who use a URL not ending with a '/' to the same one with the '/'. |
| 5245 | It can be useful to ensure that search engines will only see one URL. |
| 5246 | For this, a return code 301 is preferred. |
| 5247 | |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5248 | - "set-cookie NAME[=value]" |
| 5249 | A "Set-Cookie" header will be added with NAME (and optionally "=value") |
| 5250 | to the response. This is sometimes used to indicate that a user has |
| 5251 | been seen, for instance to protect against some types of DoS. No other |
| 5252 | cookie option is added, so the cookie will be a session cookie. Note |
| 5253 | that for a browser, a sole cookie name without an equal sign is |
| 5254 | different from a cookie with an equal sign. |
| 5255 | |
| 5256 | - "clear-cookie NAME[=]" |
| 5257 | A "Set-Cookie" header will be added with NAME (and optionally "="), but |
| 5258 | with the "Max-Age" attribute set to zero. This will tell the browser to |
| 5259 | delete this cookie. It is useful for instance on logout pages. It is |
| 5260 | important to note that clearing the cookie "NAME" will not remove a |
| 5261 | cookie set with "NAME=value". You have to clear the cookie "NAME=" for |
| 5262 | that, because the browser makes the difference. |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 5263 | |
| 5264 | Example: move the login URL only to HTTPS. |
| 5265 | acl clear dst_port 80 |
| 5266 | acl secure dst_port 8080 |
| 5267 | acl login_page url_beg /login |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5268 | acl logout url_beg /logout |
Willy Tarreau | 79da469 | 2008-11-19 20:03:04 +0100 | [diff] [blame] | 5269 | acl uid_given url_reg /login?userid=[^&]+ |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5270 | acl cookie_set hdr_sub(cookie) SEEN=1 |
| 5271 | |
| 5272 | redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set |
Willy Tarreau | 79da469 | 2008-11-19 20:03:04 +0100 | [diff] [blame] | 5273 | redirect prefix https://mysite.com if login_page !secure |
| 5274 | redirect prefix http://mysite.com drop-query if login_page !uid_given |
| 5275 | redirect location http://mysite.com/ if !login_page secure |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 5276 | redirect location / clear-cookie USERID= if logout |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 5277 | |
Willy Tarreau | 81e3b4f | 2010-01-10 00:42:19 +0100 | [diff] [blame] | 5278 | Example: send redirects for request for articles without a '/'. |
| 5279 | acl missing_slash path_reg ^/article/[^/]*$ |
| 5280 | redirect code 301 prefix / drop-query append-slash if missing_slash |
| 5281 | |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5282 | Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy. |
David BERARD | e715304 | 2012-11-03 00:11:31 +0100 | [diff] [blame] | 5283 | redirect scheme https if !{ ssl_fc } |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 5284 | |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 5285 | Example: append 'www.' prefix in front of all hosts not having it |
| 5286 | http-request redirect code 301 location www.%[hdr(host)]%[req.uri] \ |
| 5287 | unless { hdr_beg(host) -i www } |
| 5288 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5289 | See section 7 about ACL usage. |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 5290 | |
| 5291 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 5292 | redisp (deprecated) |
| 5293 | redispatch (deprecated) |
| 5294 | Enable or disable session redistribution in case of connection failure |
| 5295 | May be used in sections: defaults | frontend | listen | backend |
| 5296 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5297 | Arguments : none |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 5298 | |
| 5299 | In HTTP mode, if a server designated by a cookie is down, clients may |
| 5300 | definitely stick to it because they cannot flush the cookie, so they will not |
| 5301 | be able to access the service anymore. |
| 5302 | |
| 5303 | Specifying "redispatch" will allow the proxy to break their persistence and |
| 5304 | redistribute them to a working server. |
| 5305 | |
| 5306 | It also allows to retry last connection to another server in case of multiple |
| 5307 | connection failures. Of course, it requires having "retries" set to a nonzero |
| 5308 | value. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 5309 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 5310 | This form is deprecated, do not use it in any new configuration, use the new |
| 5311 | "option redispatch" instead. |
| 5312 | |
| 5313 | See also : "option redispatch" |
| 5314 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5315 | |
Willy Tarreau | 8abd4cd | 2010-01-31 14:30:44 +0100 | [diff] [blame] | 5316 | reqadd <string> [{if | unless} <cond>] |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5317 | Add a header at the end of the HTTP request |
| 5318 | May be used in sections : defaults | frontend | listen | backend |
| 5319 | no | yes | yes | yes |
| 5320 | Arguments : |
| 5321 | <string> is the complete line to be added. Any space or known delimiter |
| 5322 | must be escaped using a backslash ('\'). Please refer to section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5323 | 6 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5324 | |
Willy Tarreau | 8abd4cd | 2010-01-31 14:30:44 +0100 | [diff] [blame] | 5325 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5326 | possible to ignore this rule when other conditions are not met. |
| 5327 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5328 | A new line consisting in <string> followed by a line feed will be added after |
| 5329 | the last header of an HTTP request. |
| 5330 | |
| 5331 | Header transformations only apply to traffic which passes through HAProxy, |
| 5332 | and not to traffic generated by HAProxy, such as health-checks or error |
| 5333 | responses. |
| 5334 | |
Willy Tarreau | 8abd4cd | 2010-01-31 14:30:44 +0100 | [diff] [blame] | 5335 | Example : add "X-Proto: SSL" to requests coming via port 81 |
| 5336 | acl is-ssl dst_port 81 |
| 5337 | reqadd X-Proto:\ SSL if is-ssl |
| 5338 | |
| 5339 | See also: "rspadd", section 6 about HTTP header manipulation, and section 7 |
| 5340 | about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5341 | |
| 5342 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5343 | reqallow <search> [{if | unless} <cond>] |
| 5344 | reqiallow <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5345 | Definitely allow an HTTP request if a line matches a regular expression |
| 5346 | May be used in sections : defaults | frontend | listen | backend |
| 5347 | no | yes | yes | yes |
| 5348 | Arguments : |
| 5349 | <search> is the regular expression applied to HTTP headers and to the |
| 5350 | request line. This is an extended regular expression. Parenthesis |
| 5351 | grouping is supported and no preliminary backslash is required. |
| 5352 | Any space or known delimiter must be escaped using a backslash |
| 5353 | ('\'). The pattern applies to a full line at a time. The |
| 5354 | "reqallow" keyword strictly matches case while "reqiallow" |
| 5355 | ignores case. |
| 5356 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5357 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5358 | possible to ignore this rule when other conditions are not met. |
| 5359 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5360 | A request containing any line which matches extended regular expression |
| 5361 | <search> will mark the request as allowed, even if any later test would |
| 5362 | result in a deny. The test applies both to the request line and to request |
| 5363 | headers. Keep in mind that URLs in request line are case-sensitive while |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 5364 | header names are not. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5365 | |
| 5366 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 5367 | Reqdeny, reqallow and reqpass should be avoided in new designs. |
| 5368 | |
| 5369 | Example : |
| 5370 | # allow www.* but refuse *.local |
| 5371 | reqiallow ^Host:\ www\. |
| 5372 | reqideny ^Host:\ .*\.local |
| 5373 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5374 | See also: "reqdeny", "block", section 6 about HTTP header manipulation, and |
| 5375 | section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5376 | |
| 5377 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5378 | reqdel <search> [{if | unless} <cond>] |
| 5379 | reqidel <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5380 | Delete all headers matching a regular expression in an HTTP request |
| 5381 | May be used in sections : defaults | frontend | listen | backend |
| 5382 | no | yes | yes | yes |
| 5383 | Arguments : |
| 5384 | <search> is the regular expression applied to HTTP headers and to the |
| 5385 | request line. This is an extended regular expression. Parenthesis |
| 5386 | grouping is supported and no preliminary backslash is required. |
| 5387 | Any space or known delimiter must be escaped using a backslash |
| 5388 | ('\'). The pattern applies to a full line at a time. The "reqdel" |
| 5389 | keyword strictly matches case while "reqidel" ignores case. |
| 5390 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5391 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5392 | possible to ignore this rule when other conditions are not met. |
| 5393 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5394 | Any header line matching extended regular expression <search> in the request |
| 5395 | will be completely deleted. Most common use of this is to remove unwanted |
| 5396 | and/or dangerous headers or cookies from a request before passing it to the |
| 5397 | next servers. |
| 5398 | |
| 5399 | Header transformations only apply to traffic which passes through HAProxy, |
| 5400 | and not to traffic generated by HAProxy, such as health-checks or error |
| 5401 | responses. Keep in mind that header names are not case-sensitive. |
| 5402 | |
| 5403 | Example : |
| 5404 | # remove X-Forwarded-For header and SERVER cookie |
| 5405 | reqidel ^X-Forwarded-For:.* |
| 5406 | reqidel ^Cookie:.*SERVER= |
| 5407 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5408 | See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header |
| 5409 | manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5410 | |
| 5411 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5412 | reqdeny <search> [{if | unless} <cond>] |
| 5413 | reqideny <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5414 | Deny an HTTP request if a line matches a regular expression |
| 5415 | May be used in sections : defaults | frontend | listen | backend |
| 5416 | no | yes | yes | yes |
| 5417 | Arguments : |
| 5418 | <search> is the regular expression applied to HTTP headers and to the |
| 5419 | request line. This is an extended regular expression. Parenthesis |
| 5420 | grouping is supported and no preliminary backslash is required. |
| 5421 | Any space or known delimiter must be escaped using a backslash |
| 5422 | ('\'). The pattern applies to a full line at a time. The |
| 5423 | "reqdeny" keyword strictly matches case while "reqideny" ignores |
| 5424 | case. |
| 5425 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5426 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5427 | possible to ignore this rule when other conditions are not met. |
| 5428 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5429 | A request containing any line which matches extended regular expression |
| 5430 | <search> will mark the request as denied, even if any later test would |
| 5431 | result in an allow. The test applies both to the request line and to request |
| 5432 | headers. Keep in mind that URLs in request line are case-sensitive while |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 5433 | header names are not. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5434 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 5435 | A denied request will generate an "HTTP 403 forbidden" response once the |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 5436 | complete request has been parsed. This is consistent with what is practiced |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 5437 | using ACLs. |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 5438 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5439 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 5440 | Reqdeny, reqallow and reqpass should be avoided in new designs. |
| 5441 | |
| 5442 | Example : |
| 5443 | # refuse *.local, then allow www.* |
| 5444 | reqideny ^Host:\ .*\.local |
| 5445 | reqiallow ^Host:\ www\. |
| 5446 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5447 | See also: "reqallow", "rspdeny", "block", section 6 about HTTP header |
| 5448 | manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5449 | |
| 5450 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5451 | reqpass <search> [{if | unless} <cond>] |
| 5452 | reqipass <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5453 | Ignore any HTTP request line matching a regular expression in next rules |
| 5454 | May be used in sections : defaults | frontend | listen | backend |
| 5455 | no | yes | yes | yes |
| 5456 | Arguments : |
| 5457 | <search> is the regular expression applied to HTTP headers and to the |
| 5458 | request line. This is an extended regular expression. Parenthesis |
| 5459 | grouping is supported and no preliminary backslash is required. |
| 5460 | Any space or known delimiter must be escaped using a backslash |
| 5461 | ('\'). The pattern applies to a full line at a time. The |
| 5462 | "reqpass" keyword strictly matches case while "reqipass" ignores |
| 5463 | case. |
| 5464 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5465 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5466 | possible to ignore this rule when other conditions are not met. |
| 5467 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5468 | A request containing any line which matches extended regular expression |
| 5469 | <search> will skip next rules, without assigning any deny or allow verdict. |
| 5470 | The test applies both to the request line and to request headers. Keep in |
| 5471 | mind that URLs in request line are case-sensitive while header names are not. |
| 5472 | |
| 5473 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 5474 | Reqdeny, reqallow and reqpass should be avoided in new designs. |
| 5475 | |
| 5476 | Example : |
| 5477 | # refuse *.local, then allow www.*, but ignore "www.private.local" |
| 5478 | reqipass ^Host:\ www.private\.local |
| 5479 | reqideny ^Host:\ .*\.local |
| 5480 | reqiallow ^Host:\ www\. |
| 5481 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5482 | See also: "reqallow", "reqdeny", "block", section 6 about HTTP header |
| 5483 | manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5484 | |
| 5485 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5486 | reqrep <search> <string> [{if | unless} <cond>] |
| 5487 | reqirep <search> <string> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5488 | Replace a regular expression with a string in an HTTP request line |
| 5489 | May be used in sections : defaults | frontend | listen | backend |
| 5490 | no | yes | yes | yes |
| 5491 | Arguments : |
| 5492 | <search> is the regular expression applied to HTTP headers and to the |
| 5493 | request line. This is an extended regular expression. Parenthesis |
| 5494 | grouping is supported and no preliminary backslash is required. |
| 5495 | Any space or known delimiter must be escaped using a backslash |
| 5496 | ('\'). The pattern applies to a full line at a time. The "reqrep" |
| 5497 | keyword strictly matches case while "reqirep" ignores case. |
| 5498 | |
| 5499 | <string> is the complete line to be added. Any space or known delimiter |
| 5500 | must be escaped using a backslash ('\'). References to matched |
| 5501 | pattern groups are possible using the common \N form, with N |
| 5502 | being a single digit between 0 and 9. Please refer to section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5503 | 6 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5504 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5505 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5506 | possible to ignore this rule when other conditions are not met. |
| 5507 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5508 | Any line matching extended regular expression <search> in the request (both |
| 5509 | the request line and header lines) will be completely replaced with <string>. |
| 5510 | Most common use of this is to rewrite URLs or domain names in "Host" headers. |
| 5511 | |
| 5512 | Header transformations only apply to traffic which passes through HAProxy, |
| 5513 | and not to traffic generated by HAProxy, such as health-checks or error |
| 5514 | responses. Note that for increased readability, it is suggested to add enough |
| 5515 | spaces between the request and the response. Keep in mind that URLs in |
| 5516 | request line are case-sensitive while header names are not. |
| 5517 | |
| 5518 | Example : |
| 5519 | # replace "/static/" with "/" at the beginning of any request path. |
Dmitry Sivachenko | 7823de3 | 2012-05-16 14:00:26 +0400 | [diff] [blame] | 5520 | reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2 |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5521 | # replace "www.mydomain.com" with "www" in the host name. |
| 5522 | reqirep ^Host:\ www.mydomain.com Host:\ www |
| 5523 | |
Dmitry Sivachenko | f6f4f7b | 2012-10-21 18:10:25 +0400 | [diff] [blame] | 5524 | See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", section 6 about |
| 5525 | HTTP header manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5526 | |
| 5527 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5528 | reqtarpit <search> [{if | unless} <cond>] |
| 5529 | reqitarpit <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5530 | Tarpit an HTTP request containing a line matching a regular expression |
| 5531 | May be used in sections : defaults | frontend | listen | backend |
| 5532 | no | yes | yes | yes |
| 5533 | Arguments : |
| 5534 | <search> is the regular expression applied to HTTP headers and to the |
| 5535 | request line. This is an extended regular expression. Parenthesis |
| 5536 | grouping is supported and no preliminary backslash is required. |
| 5537 | Any space or known delimiter must be escaped using a backslash |
| 5538 | ('\'). The pattern applies to a full line at a time. The |
| 5539 | "reqtarpit" keyword strictly matches case while "reqitarpit" |
| 5540 | ignores case. |
| 5541 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5542 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5543 | possible to ignore this rule when other conditions are not met. |
| 5544 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5545 | A request containing any line which matches extended regular expression |
| 5546 | <search> will be tarpitted, which means that it will connect to nowhere, will |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 5547 | be kept open for a pre-defined time, then will return an HTTP error 500 so |
| 5548 | that the attacker does not suspect it has been tarpitted. The status 500 will |
| 5549 | be reported in the logs, but the completion flags will indicate "PT". The |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5550 | delay is defined by "timeout tarpit", or "timeout connect" if the former is |
| 5551 | not set. |
| 5552 | |
| 5553 | The goal of the tarpit is to slow down robots attacking servers with |
| 5554 | identifiable requests. Many robots limit their outgoing number of connections |
| 5555 | and stay connected waiting for a reply which can take several minutes to |
| 5556 | come. Depending on the environment and attack, it may be particularly |
| 5557 | efficient at reducing the load on the network and firewalls. |
| 5558 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5559 | Examples : |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5560 | # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but |
| 5561 | # block all others. |
| 5562 | reqipass ^User-Agent:\.*(Mozilla|MSIE) |
| 5563 | reqitarpit ^User-Agent: |
| 5564 | |
Willy Tarreau | 5321c42 | 2010-01-28 20:35:13 +0100 | [diff] [blame] | 5565 | # block bad guys |
| 5566 | acl badguys src 10.1.0.3 172.16.13.20/28 |
| 5567 | reqitarpit . if badguys |
| 5568 | |
| 5569 | See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header |
| 5570 | manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5571 | |
| 5572 | |
Willy Tarreau | e5c5ce9 | 2008-06-20 17:27:19 +0200 | [diff] [blame] | 5573 | retries <value> |
| 5574 | Set the number of retries to perform on a server after a connection failure |
| 5575 | May be used in sections: defaults | frontend | listen | backend |
| 5576 | yes | no | yes | yes |
| 5577 | Arguments : |
| 5578 | <value> is the number of times a connection attempt should be retried on |
| 5579 | a server when a connection either is refused or times out. The |
| 5580 | default value is 3. |
| 5581 | |
| 5582 | It is important to understand that this value applies to the number of |
| 5583 | connection attempts, not full requests. When a connection has effectively |
| 5584 | been established to a server, there will be no more retry. |
| 5585 | |
| 5586 | In order to avoid immediate reconnections to a server which is restarting, |
| 5587 | a turn-around timer of 1 second is applied before a retry occurs. |
| 5588 | |
| 5589 | When "option redispatch" is set, the last retry may be performed on another |
| 5590 | server even if a cookie references a different server. |
| 5591 | |
| 5592 | See also : "option redispatch" |
| 5593 | |
| 5594 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5595 | rspadd <string> [{if | unless} <cond>] |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5596 | Add a header at the end of the HTTP response |
| 5597 | May be used in sections : defaults | frontend | listen | backend |
| 5598 | no | yes | yes | yes |
| 5599 | Arguments : |
| 5600 | <string> is the complete line to be added. Any space or known delimiter |
| 5601 | must be escaped using a backslash ('\'). Please refer to section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5602 | 6 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5603 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5604 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5605 | possible to ignore this rule when other conditions are not met. |
| 5606 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5607 | A new line consisting in <string> followed by a line feed will be added after |
| 5608 | the last header of an HTTP response. |
| 5609 | |
| 5610 | Header transformations only apply to traffic which passes through HAProxy, |
| 5611 | and not to traffic generated by HAProxy, such as health-checks or error |
| 5612 | responses. |
| 5613 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5614 | See also: "reqadd", section 6 about HTTP header manipulation, and section 7 |
| 5615 | about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5616 | |
| 5617 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5618 | rspdel <search> [{if | unless} <cond>] |
| 5619 | rspidel <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5620 | Delete all headers matching a regular expression in an HTTP response |
| 5621 | May be used in sections : defaults | frontend | listen | backend |
| 5622 | no | yes | yes | yes |
| 5623 | Arguments : |
| 5624 | <search> is the regular expression applied to HTTP headers and to the |
| 5625 | response line. This is an extended regular expression, so |
| 5626 | parenthesis grouping is supported and no preliminary backslash |
| 5627 | is required. Any space or known delimiter must be escaped using |
| 5628 | a backslash ('\'). The pattern applies to a full line at a time. |
| 5629 | The "rspdel" keyword strictly matches case while "rspidel" |
| 5630 | ignores case. |
| 5631 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5632 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5633 | possible to ignore this rule when other conditions are not met. |
| 5634 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5635 | Any header line matching extended regular expression <search> in the response |
| 5636 | will be completely deleted. Most common use of this is to remove unwanted |
Willy Tarreau | 3c92c5f | 2011-08-28 09:45:47 +0200 | [diff] [blame] | 5637 | and/or sensitive headers or cookies from a response before passing it to the |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5638 | client. |
| 5639 | |
| 5640 | Header transformations only apply to traffic which passes through HAProxy, |
| 5641 | and not to traffic generated by HAProxy, such as health-checks or error |
| 5642 | responses. Keep in mind that header names are not case-sensitive. |
| 5643 | |
| 5644 | Example : |
| 5645 | # remove the Server header from responses |
Willy Tarreau | 5e80e02 | 2013-05-25 08:31:25 +0200 | [diff] [blame] | 5646 | rspidel ^Server:.* |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5647 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5648 | See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header |
| 5649 | manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5650 | |
| 5651 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5652 | rspdeny <search> [{if | unless} <cond>] |
| 5653 | rspideny <search> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5654 | Block an HTTP response if a line matches a regular expression |
| 5655 | May be used in sections : defaults | frontend | listen | backend |
| 5656 | no | yes | yes | yes |
| 5657 | Arguments : |
| 5658 | <search> is the regular expression applied to HTTP headers and to the |
| 5659 | response line. This is an extended regular expression, so |
| 5660 | parenthesis grouping is supported and no preliminary backslash |
| 5661 | is required. Any space or known delimiter must be escaped using |
| 5662 | a backslash ('\'). The pattern applies to a full line at a time. |
| 5663 | The "rspdeny" keyword strictly matches case while "rspideny" |
| 5664 | ignores case. |
| 5665 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5666 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5667 | possible to ignore this rule when other conditions are not met. |
| 5668 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5669 | A response containing any line which matches extended regular expression |
| 5670 | <search> will mark the request as denied. The test applies both to the |
| 5671 | response line and to response headers. Keep in mind that header names are not |
| 5672 | case-sensitive. |
| 5673 | |
| 5674 | Main use of this keyword is to prevent sensitive information leak and to |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 5675 | block the response before it reaches the client. If a response is denied, it |
| 5676 | will be replaced with an HTTP 502 error so that the client never retrieves |
| 5677 | any sensitive data. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5678 | |
| 5679 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 5680 | Rspdeny should be avoided in new designs. |
| 5681 | |
| 5682 | Example : |
| 5683 | # Ensure that no content type matching ms-word will leak |
| 5684 | rspideny ^Content-type:\.*/ms-word |
| 5685 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5686 | See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation |
| 5687 | and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5688 | |
| 5689 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5690 | rsprep <search> <string> [{if | unless} <cond>] |
| 5691 | rspirep <search> <string> [{if | unless} <cond>] (ignore case) |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5692 | Replace a regular expression with a string in an HTTP response line |
| 5693 | May be used in sections : defaults | frontend | listen | backend |
| 5694 | no | yes | yes | yes |
| 5695 | Arguments : |
| 5696 | <search> is the regular expression applied to HTTP headers and to the |
| 5697 | response line. This is an extended regular expression, so |
| 5698 | parenthesis grouping is supported and no preliminary backslash |
| 5699 | is required. Any space or known delimiter must be escaped using |
| 5700 | a backslash ('\'). The pattern applies to a full line at a time. |
| 5701 | The "rsprep" keyword strictly matches case while "rspirep" |
| 5702 | ignores case. |
| 5703 | |
| 5704 | <string> is the complete line to be added. Any space or known delimiter |
| 5705 | must be escaped using a backslash ('\'). References to matched |
| 5706 | pattern groups are possible using the common \N form, with N |
| 5707 | being a single digit between 0 and 9. Please refer to section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5708 | 6 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5709 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5710 | <cond> is an optional matching condition built from ACLs. It makes it |
| 5711 | possible to ignore this rule when other conditions are not met. |
| 5712 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5713 | Any line matching extended regular expression <search> in the response (both |
| 5714 | the response line and header lines) will be completely replaced with |
| 5715 | <string>. Most common use of this is to rewrite Location headers. |
| 5716 | |
| 5717 | Header transformations only apply to traffic which passes through HAProxy, |
| 5718 | and not to traffic generated by HAProxy, such as health-checks or error |
| 5719 | responses. Note that for increased readability, it is suggested to add enough |
| 5720 | spaces between the request and the response. Keep in mind that header names |
| 5721 | are not case-sensitive. |
| 5722 | |
| 5723 | Example : |
| 5724 | # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com" |
| 5725 | rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com |
| 5726 | |
Willy Tarreau | fdb563c | 2010-01-31 15:43:27 +0100 | [diff] [blame] | 5727 | See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header |
| 5728 | manipulation, and section 7 about ACLs. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 5729 | |
| 5730 | |
David du Colombier | 486df47 | 2011-03-17 10:40:26 +0100 | [diff] [blame] | 5731 | server <name> <address>[:[port]] [param*] |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5732 | Declare a server in a backend |
| 5733 | May be used in sections : defaults | frontend | listen | backend |
| 5734 | no | no | yes | yes |
| 5735 | Arguments : |
| 5736 | <name> is the internal name assigned to this server. This name will |
Cyril Bonté | 941a0c6 | 2012-10-15 19:44:24 +0200 | [diff] [blame] | 5737 | appear in logs and alerts. If "http-send-name-header" is |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 5738 | set, it will be added to the request header sent to the server. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5739 | |
David du Colombier | 486df47 | 2011-03-17 10:40:26 +0100 | [diff] [blame] | 5740 | <address> is the IPv4 or IPv6 address of the server. Alternatively, a |
| 5741 | resolvable hostname is supported, but this name will be resolved |
| 5742 | during start-up. Address "0.0.0.0" or "*" has a special meaning. |
| 5743 | It indicates that the connection will be forwarded to the same IP |
Willy Tarreau | d669a4f | 2010-07-13 14:49:50 +0200 | [diff] [blame] | 5744 | address as the one from the client connection. This is useful in |
| 5745 | transparent proxy architectures where the client's connection is |
| 5746 | intercepted and haproxy must forward to the original destination |
| 5747 | address. This is more or less what the "transparent" keyword does |
| 5748 | except that with a server it's possible to limit concurrency and |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 5749 | to report statistics. Optionally, an address family prefix may be |
| 5750 | used before the address to force the family regardless of the |
| 5751 | address format, which can be useful to specify a path to a unix |
| 5752 | socket with no slash ('/'). Currently supported prefixes are : |
| 5753 | - 'ipv4@' -> address is always IPv4 |
| 5754 | - 'ipv6@' -> address is always IPv6 |
| 5755 | - 'unix@' -> address is a path to a local unix socket |
Willy Tarreau | ccfccef | 2014-05-10 01:49:15 +0200 | [diff] [blame] | 5756 | - 'abns@' -> address is in abstract namespace (Linux only) |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 5757 | Any part of the address string may reference any number of |
| 5758 | environment variables by preceding their name with a dollar |
| 5759 | sign ('$') and optionally enclosing them with braces ('{}'), |
| 5760 | similarly to what is done in Bourne shell. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5761 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 5762 | <port> is an optional port specification. If set, all connections will |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5763 | be sent to this port. If unset, the same port the client |
| 5764 | connected to will be used. The port may also be prefixed by a "+" |
| 5765 | or a "-". In this case, the server's port will be determined by |
| 5766 | adding this value to the client's port. |
| 5767 | |
| 5768 | <param*> is a list of parameters for this server. The "server" keywords |
| 5769 | accepts an important number of options and has a complete section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5770 | dedicated to it. Please refer to section 5 for more details. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5771 | |
| 5772 | Examples : |
| 5773 | server first 10.1.1.1:1080 cookie first check inter 1000 |
| 5774 | server second 10.1.1.2:1080 cookie second check inter 1000 |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 5775 | server transp ipv4@ |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 5776 | server backup ${SRV_BACKUP}:1080 backup |
| 5777 | server www1_dc1 ${LAN_DC1}.101:80 |
| 5778 | server www1_dc2 ${LAN_DC2}.101:80 |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5779 | |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 5780 | See also: "default-server", "http-send-name-header" and section 5 about |
| 5781 | server options |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5782 | |
| 5783 | |
| 5784 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 5785 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ] |
Willy Tarreau | d53f96b | 2009-02-04 18:46:54 +0100 | [diff] [blame] | 5786 | source <addr>[:<port>] [interface <name>] |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5787 | Set the source address for outgoing connections |
| 5788 | May be used in sections : defaults | frontend | listen | backend |
| 5789 | yes | no | yes | yes |
| 5790 | Arguments : |
| 5791 | <addr> is the IPv4 address HAProxy will bind to before connecting to a |
| 5792 | server. This address is also used as a source for health checks. |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 5793 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5794 | The default value of 0.0.0.0 means that the system will select |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 5795 | the most appropriate address to reach its destination. Optionally |
| 5796 | an address family prefix may be used before the address to force |
| 5797 | the family regardless of the address format, which can be useful |
| 5798 | to specify a path to a unix socket with no slash ('/'). Currently |
| 5799 | supported prefixes are : |
| 5800 | - 'ipv4@' -> address is always IPv4 |
| 5801 | - 'ipv6@' -> address is always IPv6 |
| 5802 | - 'unix@' -> address is a path to a local unix socket |
Willy Tarreau | ccfccef | 2014-05-10 01:49:15 +0200 | [diff] [blame] | 5803 | - 'abns@' -> address is in abstract namespace (Linux only) |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 5804 | Any part of the address string may reference any number of |
| 5805 | environment variables by preceding their name with a dollar |
| 5806 | sign ('$') and optionally enclosing them with braces ('{}'), |
| 5807 | similarly to what is done in Bourne shell. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5808 | |
| 5809 | <port> is an optional port. It is normally not needed but may be useful |
| 5810 | in some very specific contexts. The default value of zero means |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 5811 | the system will select a free port. Note that port ranges are not |
| 5812 | supported in the backend. If you want to force port ranges, you |
| 5813 | have to specify them on each "server" line. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5814 | |
| 5815 | <addr2> is the IP address to present to the server when connections are |
| 5816 | forwarded in full transparent proxy mode. This is currently only |
| 5817 | supported on some patched Linux kernels. When this address is |
| 5818 | specified, clients connecting to the server will be presented |
| 5819 | with this address, while health checks will still use the address |
| 5820 | <addr>. |
| 5821 | |
| 5822 | <port2> is the optional port to present to the server when connections |
| 5823 | are forwarded in full transparent proxy mode (see <addr2> above). |
| 5824 | The default value of zero means the system will select a free |
| 5825 | port. |
| 5826 | |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 5827 | <hdr> is the name of a HTTP header in which to fetch the IP to bind to. |
| 5828 | This is the name of a comma-separated header list which can |
| 5829 | contain multiple IP addresses. By default, the last occurrence is |
| 5830 | used. This is designed to work with the X-Forwarded-For header |
Baptiste Assmann | ea3e73b | 2013-02-02 23:47:49 +0100 | [diff] [blame] | 5831 | and to automatically bind to the client's IP address as seen |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 5832 | by previous proxy, typically Stunnel. In order to use another |
| 5833 | occurrence from the last one, please see the <occ> parameter |
| 5834 | below. When the header (or occurrence) is not found, no binding |
| 5835 | is performed so that the proxy's default IP address is used. Also |
| 5836 | keep in mind that the header name is case insensitive, as for any |
| 5837 | HTTP header. |
| 5838 | |
| 5839 | <occ> is the occurrence number of a value to be used in a multi-value |
| 5840 | header. This is to be used in conjunction with "hdr_ip(<hdr>)", |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 5841 | in order to specify which occurrence to use for the source IP |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 5842 | address. Positive values indicate a position from the first |
| 5843 | occurrence, 1 being the first one. Negative values indicate |
| 5844 | positions relative to the last one, -1 being the last one. This |
| 5845 | is helpful for situations where an X-Forwarded-For header is set |
| 5846 | at the entry point of an infrastructure and must be used several |
| 5847 | proxy layers away. When this value is not specified, -1 is |
| 5848 | assumed. Passing a zero here disables the feature. |
| 5849 | |
Willy Tarreau | d53f96b | 2009-02-04 18:46:54 +0100 | [diff] [blame] | 5850 | <name> is an optional interface name to which to bind to for outgoing |
| 5851 | traffic. On systems supporting this features (currently, only |
| 5852 | Linux), this allows one to bind all traffic to the server to |
| 5853 | this interface even if it is not the one the system would select |
| 5854 | based on routing tables. This should be used with extreme care. |
| 5855 | Note that using this option requires root privileges. |
| 5856 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5857 | The "source" keyword is useful in complex environments where a specific |
| 5858 | address only is allowed to connect to the servers. It may be needed when a |
| 5859 | private address must be used through a public gateway for instance, and it is |
| 5860 | known that the system cannot determine the adequate source address by itself. |
| 5861 | |
| 5862 | An extension which is available on certain patched Linux kernels may be used |
| 5863 | through the "usesrc" optional keyword. It makes it possible to connect to the |
| 5864 | servers with an IP address which does not belong to the system itself. This |
| 5865 | is called "full transparent proxy mode". For this to work, the destination |
| 5866 | servers have to route their traffic back to this address through the machine |
| 5867 | running HAProxy, and IP forwarding must generally be enabled on this machine. |
| 5868 | |
| 5869 | In this "full transparent proxy" mode, it is possible to force a specific IP |
| 5870 | address to be presented to the servers. This is not much used in fact. A more |
| 5871 | common use is to tell HAProxy to present the client's IP address. For this, |
| 5872 | there are two methods : |
| 5873 | |
| 5874 | - present the client's IP and port addresses. This is the most transparent |
| 5875 | mode, but it can cause problems when IP connection tracking is enabled on |
| 5876 | the machine, because a same connection may be seen twice with different |
| 5877 | states. However, this solution presents the huge advantage of not |
| 5878 | limiting the system to the 64k outgoing address+port couples, because all |
| 5879 | of the client ranges may be used. |
| 5880 | |
| 5881 | - present only the client's IP address and select a spare port. This |
| 5882 | solution is still quite elegant but slightly less transparent (downstream |
| 5883 | firewalls logs will not match upstream's). It also presents the downside |
| 5884 | of limiting the number of concurrent connections to the usual 64k ports. |
| 5885 | However, since the upstream and downstream ports are different, local IP |
| 5886 | connection tracking on the machine will not be upset by the reuse of the |
| 5887 | same session. |
| 5888 | |
| 5889 | Note that depending on the transparent proxy technology used, it may be |
| 5890 | required to force the source address. In fact, cttproxy version 2 requires an |
| 5891 | IP address in <addr> above, and does not support setting of "0.0.0.0" as the |
| 5892 | IP address because it creates NAT entries which much match the exact outgoing |
| 5893 | address. Tproxy version 4 and some other kernel patches which work in pure |
| 5894 | forwarding mode generally will not have this limitation. |
| 5895 | |
| 5896 | This option sets the default source for all servers in the backend. It may |
| 5897 | also be specified in a "defaults" section. Finer source address specification |
| 5898 | is possible at the server level using the "source" server option. Refer to |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5899 | section 5 for more information. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5900 | |
| 5901 | Examples : |
| 5902 | backend private |
| 5903 | # Connect to the servers using our 192.168.1.200 source address |
| 5904 | source 192.168.1.200 |
| 5905 | |
| 5906 | backend transparent_ssl1 |
| 5907 | # Connect to the SSL farm from the client's source address |
| 5908 | source 192.168.1.200 usesrc clientip |
| 5909 | |
| 5910 | backend transparent_ssl2 |
| 5911 | # Connect to the SSL farm from the client's source address and port |
| 5912 | # not recommended if IP conntrack is present on the local machine. |
| 5913 | source 192.168.1.200 usesrc client |
| 5914 | |
| 5915 | backend transparent_ssl3 |
| 5916 | # Connect to the SSL farm from the client's source address. It |
| 5917 | # is more conntrack-friendly. |
| 5918 | source 192.168.1.200 usesrc clientip |
| 5919 | |
| 5920 | backend transparent_smtp |
| 5921 | # Connect to the SMTP farm from the client's source address/port |
| 5922 | # with Tproxy version 4. |
| 5923 | source 0.0.0.0 usesrc clientip |
| 5924 | |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 5925 | backend transparent_http |
| 5926 | # Connect to the servers using the client's IP as seen by previous |
| 5927 | # proxy. |
| 5928 | source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1) |
| 5929 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 5930 | See also : the "source" server option in section 5, the Tproxy patches for |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 5931 | the Linux kernel on www.balabit.com, the "bind" keyword. |
| 5932 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 5933 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5934 | srvtimeout <timeout> (deprecated) |
| 5935 | Set the maximum inactivity time on the server side. |
| 5936 | May be used in sections : defaults | frontend | listen | backend |
| 5937 | yes | no | yes | yes |
| 5938 | Arguments : |
| 5939 | <timeout> is the timeout value specified in milliseconds by default, but |
| 5940 | can be in any other unit if the number is suffixed by the unit, |
| 5941 | as explained at the top of this document. |
| 5942 | |
| 5943 | The inactivity timeout applies when the server is expected to acknowledge or |
| 5944 | send data. In HTTP mode, this timeout is particularly important to consider |
| 5945 | during the first phase of the server's response, when it has to send the |
| 5946 | headers, as it directly represents the server's processing time for the |
| 5947 | request. To find out what value to put there, it's often good to start with |
| 5948 | what would be considered as unacceptable response times, then check the logs |
| 5949 | to observe the response time distribution, and adjust the value accordingly. |
| 5950 | |
| 5951 | The value is specified in milliseconds by default, but can be in any other |
| 5952 | unit if the number is suffixed by the unit, as specified at the top of this |
| 5953 | document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly |
| 5954 | recommended that the client timeout remains equal to the server timeout in |
| 5955 | order to avoid complex situations to debug. Whatever the expected server |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 5956 | response times, it is a good practice to cover at least one or several TCP |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5957 | packet losses by specifying timeouts that are slightly above multiples of 3 |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 5958 | seconds (eg: 4 or 5 seconds minimum). |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5959 | |
| 5960 | This parameter is specific to backends, but can be specified once for all in |
| 5961 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 5962 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 5963 | is not recommended. Such a usage is accepted and works but reports a warning |
| 5964 | during startup because it may results in accumulation of expired sessions in |
| 5965 | the system if the system's timeouts are not configured either. |
| 5966 | |
| 5967 | This parameter is provided for compatibility but is currently deprecated. |
| 5968 | Please use "timeout server" instead. |
| 5969 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 5970 | See also : "timeout server", "timeout tunnel", "timeout client" and |
| 5971 | "clitimeout". |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 5972 | |
| 5973 | |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 5974 | stats admin { if | unless } <cond> |
| 5975 | Enable statistics admin level if/unless a condition is matched |
| 5976 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 5977 | no | yes | yes | yes |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 5978 | |
| 5979 | This statement enables the statistics admin level if/unless a condition is |
| 5980 | matched. |
| 5981 | |
| 5982 | The admin level allows to enable/disable servers from the web interface. By |
| 5983 | default, statistics page is read-only for security reasons. |
| 5984 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 5985 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 5986 | unless you know what you do : memory is not shared between the |
| 5987 | processes, which can result in random behaviours. |
| 5988 | |
Cyril Bonté | 23b39d9 | 2011-02-10 22:54:44 +0100 | [diff] [blame] | 5989 | Currently, the POST request is limited to the buffer size minus the reserved |
| 5990 | buffer space, which means that if the list of servers is too long, the |
| 5991 | request won't be processed. It is recommended to alter few servers at a |
| 5992 | time. |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 5993 | |
| 5994 | Example : |
| 5995 | # statistics admin level only for localhost |
| 5996 | backend stats_localhost |
| 5997 | stats enable |
| 5998 | stats admin if LOCALHOST |
| 5999 | |
| 6000 | Example : |
| 6001 | # statistics admin level always enabled because of the authentication |
| 6002 | backend stats_auth |
| 6003 | stats enable |
| 6004 | stats auth admin:AdMiN123 |
| 6005 | stats admin if TRUE |
| 6006 | |
| 6007 | Example : |
| 6008 | # statistics admin level depends on the authenticated user |
| 6009 | userlist stats-auth |
| 6010 | group admin users admin |
| 6011 | user admin insecure-password AdMiN123 |
| 6012 | group readonly users haproxy |
| 6013 | user haproxy insecure-password haproxy |
| 6014 | |
| 6015 | backend stats_auth |
| 6016 | stats enable |
| 6017 | acl AUTH http_auth(stats-auth) |
| 6018 | acl AUTH_ADMIN http_auth_group(stats-auth) admin |
| 6019 | stats http-request auth unless AUTH |
| 6020 | stats admin if AUTH_ADMIN |
| 6021 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6022 | See also : "stats enable", "stats auth", "stats http-request", "nbproc", |
| 6023 | "bind-process", section 3.4 about userlists and section 7 about |
| 6024 | ACL usage. |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 6025 | |
| 6026 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6027 | stats auth <user>:<passwd> |
| 6028 | Enable statistics with authentication and grant access to an account |
| 6029 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6030 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6031 | Arguments : |
| 6032 | <user> is a user name to grant access to |
| 6033 | |
| 6034 | <passwd> is the cleartext password associated to this user |
| 6035 | |
| 6036 | This statement enables statistics with default settings, and restricts access |
| 6037 | to declared users only. It may be repeated as many times as necessary to |
| 6038 | allow as many users as desired. When a user tries to access the statistics |
| 6039 | without a valid account, a "401 Forbidden" response will be returned so that |
| 6040 | the browser asks the user to provide a valid user and password. The real |
| 6041 | which will be returned to the browser is configurable using "stats realm". |
| 6042 | |
| 6043 | Since the authentication method is HTTP Basic Authentication, the passwords |
| 6044 | circulate in cleartext on the network. Thus, it was decided that the |
| 6045 | configuration file would also use cleartext passwords to remind the users |
Willy Tarreau | 3c92c5f | 2011-08-28 09:45:47 +0200 | [diff] [blame] | 6046 | that those ones should not be sensitive and not shared with any other account. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6047 | |
| 6048 | It is also possible to reduce the scope of the proxies which appear in the |
| 6049 | report using "stats scope". |
| 6050 | |
| 6051 | Though this statement alone is enough to enable statistics reporting, it is |
| 6052 | recommended to set all other settings in order to avoid relying on default |
| 6053 | unobvious parameters. |
| 6054 | |
| 6055 | Example : |
| 6056 | # public access (limited to this backend only) |
| 6057 | backend public_www |
| 6058 | server srv1 192.168.0.1:80 |
| 6059 | stats enable |
| 6060 | stats hide-version |
| 6061 | stats scope . |
| 6062 | stats uri /admin?stats |
| 6063 | stats realm Haproxy\ Statistics |
| 6064 | stats auth admin1:AdMiN123 |
| 6065 | stats auth admin2:AdMiN321 |
| 6066 | |
| 6067 | # internal monitoring access (unlimited) |
| 6068 | backend private_monitoring |
| 6069 | stats enable |
| 6070 | stats uri /admin?stats |
| 6071 | stats refresh 5s |
| 6072 | |
| 6073 | See also : "stats enable", "stats realm", "stats scope", "stats uri" |
| 6074 | |
| 6075 | |
| 6076 | stats enable |
| 6077 | Enable statistics reporting with default settings |
| 6078 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6079 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6080 | Arguments : none |
| 6081 | |
| 6082 | This statement enables statistics reporting with default settings defined |
| 6083 | at build time. Unless stated otherwise, these settings are used : |
| 6084 | - stats uri : /haproxy?stats |
| 6085 | - stats realm : "HAProxy Statistics" |
| 6086 | - stats auth : no authentication |
| 6087 | - stats scope : no restriction |
| 6088 | |
| 6089 | Though this statement alone is enough to enable statistics reporting, it is |
| 6090 | recommended to set all other settings in order to avoid relying on default |
| 6091 | unobvious parameters. |
| 6092 | |
| 6093 | Example : |
| 6094 | # public access (limited to this backend only) |
| 6095 | backend public_www |
| 6096 | server srv1 192.168.0.1:80 |
| 6097 | stats enable |
| 6098 | stats hide-version |
| 6099 | stats scope . |
| 6100 | stats uri /admin?stats |
| 6101 | stats realm Haproxy\ Statistics |
| 6102 | stats auth admin1:AdMiN123 |
| 6103 | stats auth admin2:AdMiN321 |
| 6104 | |
| 6105 | # internal monitoring access (unlimited) |
| 6106 | backend private_monitoring |
| 6107 | stats enable |
| 6108 | stats uri /admin?stats |
| 6109 | stats refresh 5s |
| 6110 | |
| 6111 | See also : "stats auth", "stats realm", "stats uri" |
| 6112 | |
| 6113 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6114 | stats hide-version |
| 6115 | Enable statistics and hide HAProxy version reporting |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 6116 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6117 | yes | yes | yes | yes |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6118 | Arguments : none |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 6119 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6120 | By default, the stats page reports some useful status information along with |
| 6121 | the statistics. Among them is HAProxy's version. However, it is generally |
| 6122 | considered dangerous to report precise version to anyone, as it can help them |
| 6123 | target known weaknesses with specific attacks. The "stats hide-version" |
| 6124 | statement removes the version from the statistics report. This is recommended |
| 6125 | for public sites or any site with a weak login/password. |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 6126 | |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 6127 | Though this statement alone is enough to enable statistics reporting, it is |
| 6128 | recommended to set all other settings in order to avoid relying on default |
| 6129 | unobvious parameters. |
| 6130 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6131 | Example : |
| 6132 | # public access (limited to this backend only) |
| 6133 | backend public_www |
| 6134 | server srv1 192.168.0.1:80 |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 6135 | stats enable |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6136 | stats hide-version |
| 6137 | stats scope . |
| 6138 | stats uri /admin?stats |
| 6139 | stats realm Haproxy\ Statistics |
| 6140 | stats auth admin1:AdMiN123 |
| 6141 | stats auth admin2:AdMiN321 |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 6142 | |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 6143 | # internal monitoring access (unlimited) |
| 6144 | backend private_monitoring |
| 6145 | stats enable |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6146 | stats uri /admin?stats |
| 6147 | stats refresh 5s |
Krzysztof Piotr Oledzki | 15514c2 | 2010-01-04 16:03:09 +0100 | [diff] [blame] | 6148 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6149 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 6150 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 6151 | |
Cyril Bonté | 2be1b3f | 2010-09-30 23:46:30 +0200 | [diff] [blame] | 6152 | stats http-request { allow | deny | auth [realm <realm>] } |
| 6153 | [ { if | unless } <condition> ] |
| 6154 | Access control for statistics |
| 6155 | |
| 6156 | May be used in sections: defaults | frontend | listen | backend |
| 6157 | no | no | yes | yes |
| 6158 | |
| 6159 | As "http-request", these set of options allow to fine control access to |
| 6160 | statistics. Each option may be followed by if/unless and acl. |
| 6161 | First option with matched condition (or option without condition) is final. |
| 6162 | For "deny" a 403 error will be returned, for "allow" normal processing is |
| 6163 | performed, for "auth" a 401/407 error code is returned so the client |
| 6164 | should be asked to enter a username and password. |
| 6165 | |
| 6166 | There is no fixed limit to the number of http-request statements per |
| 6167 | instance. |
| 6168 | |
| 6169 | See also : "http-request", section 3.4 about userlists and section 7 |
| 6170 | about ACL usage. |
| 6171 | |
| 6172 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6173 | stats realm <realm> |
| 6174 | Enable statistics and set authentication realm |
| 6175 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6176 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6177 | Arguments : |
| 6178 | <realm> is the name of the HTTP Basic Authentication realm reported to |
| 6179 | the browser. The browser uses it to display it in the pop-up |
| 6180 | inviting the user to enter a valid username and password. |
| 6181 | |
| 6182 | The realm is read as a single word, so any spaces in it should be escaped |
| 6183 | using a backslash ('\'). |
| 6184 | |
| 6185 | This statement is useful only in conjunction with "stats auth" since it is |
| 6186 | only related to authentication. |
| 6187 | |
| 6188 | Though this statement alone is enough to enable statistics reporting, it is |
| 6189 | recommended to set all other settings in order to avoid relying on default |
| 6190 | unobvious parameters. |
| 6191 | |
| 6192 | Example : |
| 6193 | # public access (limited to this backend only) |
| 6194 | backend public_www |
| 6195 | server srv1 192.168.0.1:80 |
| 6196 | stats enable |
| 6197 | stats hide-version |
| 6198 | stats scope . |
| 6199 | stats uri /admin?stats |
| 6200 | stats realm Haproxy\ Statistics |
| 6201 | stats auth admin1:AdMiN123 |
| 6202 | stats auth admin2:AdMiN321 |
| 6203 | |
| 6204 | # internal monitoring access (unlimited) |
| 6205 | backend private_monitoring |
| 6206 | stats enable |
| 6207 | stats uri /admin?stats |
| 6208 | stats refresh 5s |
| 6209 | |
| 6210 | See also : "stats auth", "stats enable", "stats uri" |
| 6211 | |
| 6212 | |
| 6213 | stats refresh <delay> |
| 6214 | Enable statistics with automatic refresh |
| 6215 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6216 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6217 | Arguments : |
| 6218 | <delay> is the suggested refresh delay, specified in seconds, which will |
| 6219 | be returned to the browser consulting the report page. While the |
| 6220 | browser is free to apply any delay, it will generally respect it |
| 6221 | and refresh the page this every seconds. The refresh interval may |
| 6222 | be specified in any other non-default time unit, by suffixing the |
| 6223 | unit after the value, as explained at the top of this document. |
| 6224 | |
| 6225 | This statement is useful on monitoring displays with a permanent page |
| 6226 | reporting the load balancer's activity. When set, the HTML report page will |
| 6227 | include a link "refresh"/"stop refresh" so that the user can select whether |
| 6228 | he wants automatic refresh of the page or not. |
| 6229 | |
| 6230 | Though this statement alone is enough to enable statistics reporting, it is |
| 6231 | recommended to set all other settings in order to avoid relying on default |
| 6232 | unobvious parameters. |
| 6233 | |
| 6234 | Example : |
| 6235 | # public access (limited to this backend only) |
| 6236 | backend public_www |
| 6237 | server srv1 192.168.0.1:80 |
| 6238 | stats enable |
| 6239 | stats hide-version |
| 6240 | stats scope . |
| 6241 | stats uri /admin?stats |
| 6242 | stats realm Haproxy\ Statistics |
| 6243 | stats auth admin1:AdMiN123 |
| 6244 | stats auth admin2:AdMiN321 |
| 6245 | |
| 6246 | # internal monitoring access (unlimited) |
| 6247 | backend private_monitoring |
| 6248 | stats enable |
| 6249 | stats uri /admin?stats |
| 6250 | stats refresh 5s |
| 6251 | |
| 6252 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 6253 | |
| 6254 | |
| 6255 | stats scope { <name> | "." } |
| 6256 | Enable statistics and limit access scope |
| 6257 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6258 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6259 | Arguments : |
| 6260 | <name> is the name of a listen, frontend or backend section to be |
| 6261 | reported. The special name "." (a single dot) designates the |
| 6262 | section in which the statement appears. |
| 6263 | |
| 6264 | When this statement is specified, only the sections enumerated with this |
| 6265 | statement will appear in the report. All other ones will be hidden. This |
| 6266 | statement may appear as many times as needed if multiple sections need to be |
| 6267 | reported. Please note that the name checking is performed as simple string |
| 6268 | comparisons, and that it is never checked that a give section name really |
| 6269 | exists. |
| 6270 | |
| 6271 | Though this statement alone is enough to enable statistics reporting, it is |
| 6272 | recommended to set all other settings in order to avoid relying on default |
| 6273 | unobvious parameters. |
| 6274 | |
| 6275 | Example : |
| 6276 | # public access (limited to this backend only) |
| 6277 | backend public_www |
| 6278 | server srv1 192.168.0.1:80 |
| 6279 | stats enable |
| 6280 | stats hide-version |
| 6281 | stats scope . |
| 6282 | stats uri /admin?stats |
| 6283 | stats realm Haproxy\ Statistics |
| 6284 | stats auth admin1:AdMiN123 |
| 6285 | stats auth admin2:AdMiN321 |
| 6286 | |
| 6287 | # internal monitoring access (unlimited) |
| 6288 | backend private_monitoring |
| 6289 | stats enable |
| 6290 | stats uri /admin?stats |
| 6291 | stats refresh 5s |
| 6292 | |
| 6293 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 6294 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6295 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 6296 | stats show-desc [ <desc> ] |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6297 | Enable reporting of a description on the statistics page. |
| 6298 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6299 | yes | yes | yes | yes |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6300 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 6301 | <desc> is an optional description to be reported. If unspecified, the |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6302 | description from global section is automatically used instead. |
| 6303 | |
| 6304 | This statement is useful for users that offer shared services to their |
| 6305 | customers, where node or description should be different for each customer. |
| 6306 | |
| 6307 | Though this statement alone is enough to enable statistics reporting, it is |
| 6308 | recommended to set all other settings in order to avoid relying on default |
Dmitry Sivachenko | 7823de3 | 2012-05-16 14:00:26 +0400 | [diff] [blame] | 6309 | unobvious parameters. By default description is not shown. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6310 | |
| 6311 | Example : |
| 6312 | # internal monitoring access (unlimited) |
| 6313 | backend private_monitoring |
| 6314 | stats enable |
| 6315 | stats show-desc Master node for Europe, Asia, Africa |
| 6316 | stats uri /admin?stats |
| 6317 | stats refresh 5s |
| 6318 | |
| 6319 | See also: "show-node", "stats enable", "stats uri" and "description" in |
| 6320 | global section. |
| 6321 | |
| 6322 | |
| 6323 | stats show-legends |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6324 | Enable reporting additional information on the statistics page |
| 6325 | May be used in sections : defaults | frontend | listen | backend |
| 6326 | yes | yes | yes | yes |
| 6327 | Arguments : none |
| 6328 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 6329 | Enable reporting additional information on the statistics page : |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6330 | - cap: capabilities (proxy) |
| 6331 | - mode: one of tcp, http or health (proxy) |
| 6332 | - id: SNMP ID (proxy, socket, server) |
| 6333 | - IP (socket, server) |
| 6334 | - cookie (backend, server) |
| 6335 | |
| 6336 | Though this statement alone is enough to enable statistics reporting, it is |
| 6337 | recommended to set all other settings in order to avoid relying on default |
Dmitry Sivachenko | 7823de3 | 2012-05-16 14:00:26 +0400 | [diff] [blame] | 6338 | unobvious parameters. Default behaviour is not to show this information. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6339 | |
| 6340 | See also: "stats enable", "stats uri". |
| 6341 | |
| 6342 | |
| 6343 | stats show-node [ <name> ] |
| 6344 | Enable reporting of a host name on the statistics page. |
| 6345 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6346 | yes | yes | yes | yes |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6347 | Arguments: |
| 6348 | <name> is an optional name to be reported. If unspecified, the |
| 6349 | node name from global section is automatically used instead. |
| 6350 | |
| 6351 | This statement is useful for users that offer shared services to their |
| 6352 | customers, where node or description might be different on a stats page |
Dmitry Sivachenko | 7823de3 | 2012-05-16 14:00:26 +0400 | [diff] [blame] | 6353 | provided for each customer. Default behaviour is not to show host name. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6354 | |
| 6355 | Though this statement alone is enough to enable statistics reporting, it is |
| 6356 | recommended to set all other settings in order to avoid relying on default |
| 6357 | unobvious parameters. |
| 6358 | |
| 6359 | Example: |
| 6360 | # internal monitoring access (unlimited) |
| 6361 | backend private_monitoring |
| 6362 | stats enable |
| 6363 | stats show-node Europe-1 |
| 6364 | stats uri /admin?stats |
| 6365 | stats refresh 5s |
| 6366 | |
| 6367 | See also: "show-desc", "stats enable", "stats uri", and "node" in global |
| 6368 | section. |
| 6369 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6370 | |
| 6371 | stats uri <prefix> |
| 6372 | Enable statistics and define the URI prefix to access them |
| 6373 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 6374 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6375 | Arguments : |
| 6376 | <prefix> is the prefix of any URI which will be redirected to stats. This |
| 6377 | prefix may contain a question mark ('?') to indicate part of a |
| 6378 | query string. |
| 6379 | |
| 6380 | The statistics URI is intercepted on the relayed traffic, so it appears as a |
| 6381 | page within the normal application. It is strongly advised to ensure that the |
| 6382 | selected URI will never appear in the application, otherwise it will never be |
| 6383 | possible to reach it in the application. |
| 6384 | |
| 6385 | The default URI compiled in haproxy is "/haproxy?stats", but this may be |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 6386 | changed at build time, so it's better to always explicitly specify it here. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6387 | It is generally a good idea to include a question mark in the URI so that |
| 6388 | intermediate proxies refrain from caching the results. Also, since any string |
| 6389 | beginning with the prefix will be accepted as a stats request, the question |
| 6390 | mark helps ensuring that no valid URI will begin with the same words. |
| 6391 | |
| 6392 | It is sometimes very convenient to use "/" as the URI prefix, and put that |
| 6393 | statement in a "listen" instance of its own. That makes it easy to dedicate |
| 6394 | an address or a port to statistics only. |
| 6395 | |
| 6396 | Though this statement alone is enough to enable statistics reporting, it is |
| 6397 | recommended to set all other settings in order to avoid relying on default |
| 6398 | unobvious parameters. |
| 6399 | |
| 6400 | Example : |
| 6401 | # public access (limited to this backend only) |
| 6402 | backend public_www |
| 6403 | server srv1 192.168.0.1:80 |
| 6404 | stats enable |
| 6405 | stats hide-version |
| 6406 | stats scope . |
| 6407 | stats uri /admin?stats |
| 6408 | stats realm Haproxy\ Statistics |
| 6409 | stats auth admin1:AdMiN123 |
| 6410 | stats auth admin2:AdMiN321 |
| 6411 | |
| 6412 | # internal monitoring access (unlimited) |
| 6413 | backend private_monitoring |
| 6414 | stats enable |
| 6415 | stats uri /admin?stats |
| 6416 | stats refresh 5s |
| 6417 | |
| 6418 | See also : "stats auth", "stats enable", "stats realm" |
| 6419 | |
| 6420 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6421 | stick match <pattern> [table <table>] [{if | unless} <cond>] |
| 6422 | Define a request pattern matching condition to stick a user to a server |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 6423 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 6424 | no | no | yes | yes |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6425 | |
| 6426 | Arguments : |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 6427 | <pattern> is a pattern extraction rule as described in section 7.3. It |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6428 | describes what elements of the incoming request or connection |
| 6429 | will be analysed in the hope to find a matching entry in a |
| 6430 | stickiness table. This rule is mandatory. |
| 6431 | |
| 6432 | <table> is an optional stickiness table name. If unspecified, the same |
| 6433 | backend's table is used. A stickiness table is declared using |
| 6434 | the "stick-table" statement. |
| 6435 | |
| 6436 | <cond> is an optional matching condition. It makes it possible to match |
| 6437 | on a certain criterion only when other conditions are met (or |
| 6438 | not met). For instance, it could be used to match on a source IP |
| 6439 | address except when a request passes through a known proxy, in |
| 6440 | which case we'd match on a header containing that IP address. |
| 6441 | |
| 6442 | Some protocols or applications require complex stickiness rules and cannot |
| 6443 | always simply rely on cookies nor hashing. The "stick match" statement |
| 6444 | describes a rule to extract the stickiness criterion from an incoming request |
| 6445 | or connection. See section 7 for a complete list of possible patterns and |
| 6446 | transformation rules. |
| 6447 | |
| 6448 | The table has to be declared using the "stick-table" statement. It must be of |
| 6449 | a type compatible with the pattern. By default it is the one which is present |
| 6450 | in the same backend. It is possible to share a table with other backends by |
| 6451 | referencing it using the "table" keyword. If another table is referenced, |
| 6452 | the server's ID inside the backends are used. By default, all server IDs |
| 6453 | start at 1 in each backend, so the server ordering is enough. But in case of |
| 6454 | doubt, it is highly recommended to force server IDs using their "id" setting. |
| 6455 | |
| 6456 | It is possible to restrict the conditions where a "stick match" statement |
| 6457 | will apply, using "if" or "unless" followed by a condition. See section 7 for |
| 6458 | ACL based conditions. |
| 6459 | |
| 6460 | There is no limit on the number of "stick match" statements. The first that |
| 6461 | applies and matches will cause the request to be directed to the same server |
| 6462 | as was used for the request which created the entry. That way, multiple |
| 6463 | matches can be used as fallbacks. |
| 6464 | |
| 6465 | The stick rules are checked after the persistence cookies, so they will not |
| 6466 | affect stickiness if a cookie has already been used to select a server. That |
| 6467 | way, it becomes very easy to insert cookies and match on IP addresses in |
| 6468 | order to maintain stickiness between HTTP and HTTPS. |
| 6469 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6470 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 6471 | unless you know what you do : memory is not shared between the |
| 6472 | processes, which can result in random behaviours. |
| 6473 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6474 | Example : |
| 6475 | # forward SMTP users to the same server they just used for POP in the |
| 6476 | # last 30 minutes |
| 6477 | backend pop |
| 6478 | mode tcp |
| 6479 | balance roundrobin |
| 6480 | stick store-request src |
| 6481 | stick-table type ip size 200k expire 30m |
| 6482 | server s1 192.168.1.1:110 |
| 6483 | server s2 192.168.1.1:110 |
| 6484 | |
| 6485 | backend smtp |
| 6486 | mode tcp |
| 6487 | balance roundrobin |
| 6488 | stick match src table pop |
| 6489 | server s1 192.168.1.1:25 |
| 6490 | server s2 192.168.1.1:25 |
| 6491 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6492 | See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7 |
| 6493 | about ACLs and pattern extraction. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6494 | |
| 6495 | |
| 6496 | stick on <pattern> [table <table>] [{if | unless} <condition>] |
| 6497 | Define a request pattern to associate a user to a server |
| 6498 | May be used in sections : defaults | frontend | listen | backend |
| 6499 | no | no | yes | yes |
| 6500 | |
| 6501 | Note : This form is exactly equivalent to "stick match" followed by |
| 6502 | "stick store-request", all with the same arguments. Please refer |
| 6503 | to both keywords for details. It is only provided as a convenience |
| 6504 | for writing more maintainable configurations. |
| 6505 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6506 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 6507 | unless you know what you do : memory is not shared between the |
| 6508 | processes, which can result in random behaviours. |
| 6509 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6510 | Examples : |
| 6511 | # The following form ... |
Willy Tarreau | ec579d8 | 2010-02-26 19:15:04 +0100 | [diff] [blame] | 6512 | stick on src table pop if !localhost |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6513 | |
| 6514 | # ...is strictly equivalent to this one : |
| 6515 | stick match src table pop if !localhost |
| 6516 | stick store-request src table pop if !localhost |
| 6517 | |
| 6518 | |
| 6519 | # Use cookie persistence for HTTP, and stick on source address for HTTPS as |
| 6520 | # well as HTTP without cookie. Share the same table between both accesses. |
| 6521 | backend http |
| 6522 | mode http |
| 6523 | balance roundrobin |
| 6524 | stick on src table https |
| 6525 | cookie SRV insert indirect nocache |
| 6526 | server s1 192.168.1.1:80 cookie s1 |
| 6527 | server s2 192.168.1.1:80 cookie s2 |
| 6528 | |
| 6529 | backend https |
| 6530 | mode tcp |
| 6531 | balance roundrobin |
| 6532 | stick-table type ip size 200k expire 30m |
| 6533 | stick on src |
| 6534 | server s1 192.168.1.1:443 |
| 6535 | server s2 192.168.1.1:443 |
| 6536 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6537 | See also : "stick match", "stick store-request", "nbproc" and "bind-process". |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6538 | |
| 6539 | |
| 6540 | stick store-request <pattern> [table <table>] [{if | unless} <condition>] |
| 6541 | Define a request pattern used to create an entry in a stickiness table |
| 6542 | May be used in sections : defaults | frontend | listen | backend |
| 6543 | no | no | yes | yes |
| 6544 | |
| 6545 | Arguments : |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 6546 | <pattern> is a pattern extraction rule as described in section 7.3. It |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6547 | describes what elements of the incoming request or connection |
| 6548 | will be analysed, extracted and stored in the table once a |
| 6549 | server is selected. |
| 6550 | |
| 6551 | <table> is an optional stickiness table name. If unspecified, the same |
| 6552 | backend's table is used. A stickiness table is declared using |
| 6553 | the "stick-table" statement. |
| 6554 | |
| 6555 | <cond> is an optional storage condition. It makes it possible to store |
| 6556 | certain criteria only when some conditions are met (or not met). |
| 6557 | For instance, it could be used to store the source IP address |
| 6558 | except when the request passes through a known proxy, in which |
| 6559 | case we'd store a converted form of a header containing that IP |
| 6560 | address. |
| 6561 | |
| 6562 | Some protocols or applications require complex stickiness rules and cannot |
| 6563 | always simply rely on cookies nor hashing. The "stick store-request" statement |
| 6564 | describes a rule to decide what to extract from the request and when to do |
| 6565 | it, in order to store it into a stickiness table for further requests to |
| 6566 | match it using the "stick match" statement. Obviously the extracted part must |
| 6567 | make sense and have a chance to be matched in a further request. Storing a |
| 6568 | client's IP address for instance often makes sense. Storing an ID found in a |
| 6569 | URL parameter also makes sense. Storing a source port will almost never make |
| 6570 | any sense because it will be randomly matched. See section 7 for a complete |
| 6571 | list of possible patterns and transformation rules. |
| 6572 | |
| 6573 | The table has to be declared using the "stick-table" statement. It must be of |
| 6574 | a type compatible with the pattern. By default it is the one which is present |
| 6575 | in the same backend. It is possible to share a table with other backends by |
| 6576 | referencing it using the "table" keyword. If another table is referenced, |
| 6577 | the server's ID inside the backends are used. By default, all server IDs |
| 6578 | start at 1 in each backend, so the server ordering is enough. But in case of |
| 6579 | doubt, it is highly recommended to force server IDs using their "id" setting. |
| 6580 | |
| 6581 | It is possible to restrict the conditions where a "stick store-request" |
| 6582 | statement will apply, using "if" or "unless" followed by a condition. This |
| 6583 | condition will be evaluated while parsing the request, so any criteria can be |
| 6584 | used. See section 7 for ACL based conditions. |
| 6585 | |
| 6586 | There is no limit on the number of "stick store-request" statements, but |
| 6587 | there is a limit of 8 simultaneous stores per request or response. This |
| 6588 | makes it possible to store up to 8 criteria, all extracted from either the |
| 6589 | request or the response, regardless of the number of rules. Only the 8 first |
| 6590 | ones which match will be kept. Using this, it is possible to feed multiple |
| 6591 | tables at once in the hope to increase the chance to recognize a user on |
Willy Tarreau | 9667a80 | 2013-12-09 12:52:13 +0100 | [diff] [blame] | 6592 | another protocol or access method. Using multiple store-request rules with |
| 6593 | the same table is possible and may be used to find the best criterion to rely |
| 6594 | on, by arranging the rules by decreasing preference order. Only the first |
| 6595 | extracted criterion for a given table will be stored. All subsequent store- |
| 6596 | request rules referencing the same table will be skipped and their ACLs will |
| 6597 | not be evaluated. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6598 | |
| 6599 | The "store-request" rules are evaluated once the server connection has been |
| 6600 | established, so that the table will contain the real server that processed |
| 6601 | the request. |
| 6602 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6603 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 6604 | unless you know what you do : memory is not shared between the |
| 6605 | processes, which can result in random behaviours. |
| 6606 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6607 | Example : |
| 6608 | # forward SMTP users to the same server they just used for POP in the |
| 6609 | # last 30 minutes |
| 6610 | backend pop |
| 6611 | mode tcp |
| 6612 | balance roundrobin |
| 6613 | stick store-request src |
| 6614 | stick-table type ip size 200k expire 30m |
| 6615 | server s1 192.168.1.1:110 |
| 6616 | server s2 192.168.1.1:110 |
| 6617 | |
| 6618 | backend smtp |
| 6619 | mode tcp |
| 6620 | balance roundrobin |
| 6621 | stick match src table pop |
| 6622 | server s1 192.168.1.1:25 |
| 6623 | server s2 192.168.1.1:25 |
| 6624 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6625 | See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7 |
| 6626 | about ACLs and pattern extraction. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6627 | |
| 6628 | |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 6629 | stick-table type {ip | integer | string [len <length>] | binary [len <length>]} |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 6630 | size <size> [expire <expire>] [nopurge] [peers <peersect>] |
| 6631 | [store <data_type>]* |
Godbach | 64cef79 | 2013-12-04 16:08:22 +0800 | [diff] [blame] | 6632 | Configure the stickiness table for the current section |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6633 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | c00cdc2 | 2010-06-06 16:48:26 +0200 | [diff] [blame] | 6634 | no | yes | yes | yes |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6635 | |
| 6636 | Arguments : |
| 6637 | ip a table declared with "type ip" will only store IPv4 addresses. |
| 6638 | This form is very compact (about 50 bytes per entry) and allows |
| 6639 | very fast entry lookup and stores with almost no overhead. This |
| 6640 | is mainly used to store client source IP addresses. |
| 6641 | |
David du Colombier | 9a6d3c9 | 2011-03-17 10:40:24 +0100 | [diff] [blame] | 6642 | ipv6 a table declared with "type ipv6" will only store IPv6 addresses. |
| 6643 | This form is very compact (about 60 bytes per entry) and allows |
| 6644 | very fast entry lookup and stores with almost no overhead. This |
| 6645 | is mainly used to store client source IP addresses. |
| 6646 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6647 | integer a table declared with "type integer" will store 32bit integers |
| 6648 | which can represent a client identifier found in a request for |
| 6649 | instance. |
| 6650 | |
| 6651 | string a table declared with "type string" will store substrings of up |
| 6652 | to <len> characters. If the string provided by the pattern |
| 6653 | extractor is larger than <len>, it will be truncated before |
| 6654 | being stored. During matching, at most <len> characters will be |
| 6655 | compared between the string in the table and the extracted |
| 6656 | pattern. When not specified, the string is automatically limited |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 6657 | to 32 characters. |
| 6658 | |
| 6659 | binary a table declared with "type binary" will store binary blocks |
| 6660 | of <len> bytes. If the block provided by the pattern |
| 6661 | extractor is larger than <len>, it will be truncated before |
| 6662 | being stored. If the block provided by the pattern extractor |
| 6663 | is shorter than <len>, it will be padded by 0. When not |
| 6664 | specified, the block is automatically limited to 32 bytes. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6665 | |
| 6666 | <length> is the maximum number of characters that will be stored in a |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 6667 | "string" type table (See type "string" above). Or the number |
| 6668 | of bytes of the block in "binary" type table. Be careful when |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6669 | changing this parameter as memory usage will proportionally |
| 6670 | increase. |
| 6671 | |
| 6672 | <size> is the maximum number of entries that can fit in the table. This |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 6673 | value directly impacts memory usage. Count approximately |
| 6674 | 50 bytes per entry, plus the size of a string if any. The size |
| 6675 | supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6676 | |
| 6677 | [nopurge] indicates that we refuse to purge older entries when the table |
| 6678 | is full. When not specified and the table is full when haproxy |
| 6679 | wants to store an entry in it, it will flush a few of the oldest |
| 6680 | entries in order to release some space for the new ones. This is |
| 6681 | most often the desired behaviour. In some specific cases, it |
| 6682 | be desirable to refuse new entries instead of purging the older |
| 6683 | ones. That may be the case when the amount of data to store is |
| 6684 | far above the hardware limits and we prefer not to offer access |
| 6685 | to new clients than to reject the ones already connected. When |
| 6686 | using this parameter, be sure to properly set the "expire" |
| 6687 | parameter (see below). |
| 6688 | |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 6689 | <peersect> is the name of the peers section to use for replication. Entries |
| 6690 | which associate keys to server IDs are kept synchronized with |
| 6691 | the remote peers declared in this section. All entries are also |
| 6692 | automatically learned from the local peer (old process) during a |
| 6693 | soft restart. |
| 6694 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 6695 | NOTE : peers can't be used in multi-process mode. |
| 6696 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6697 | <expire> defines the maximum duration of an entry in the table since it |
| 6698 | was last created, refreshed or matched. The expiration delay is |
| 6699 | defined using the standard time format, similarly as the various |
| 6700 | timeouts. The maximum duration is slightly above 24 days. See |
| 6701 | section 2.2 for more information. If this delay is not specified, |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 6702 | the session won't automatically expire, but older entries will |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6703 | be removed once full. Be sure not to use the "nopurge" parameter |
| 6704 | if not expiration delay is specified. |
| 6705 | |
Willy Tarreau | 08d5f98 | 2010-06-06 13:34:54 +0200 | [diff] [blame] | 6706 | <data_type> is used to store additional information in the stick-table. This |
| 6707 | may be used by ACLs in order to control various criteria related |
| 6708 | to the activity of the client matching the stick-table. For each |
| 6709 | item specified here, the size of each entry will be inflated so |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 6710 | that the additional data can fit. Several data types may be |
| 6711 | stored with an entry. Multiple data types may be specified after |
| 6712 | the "store" keyword, as a comma-separated list. Alternatively, |
| 6713 | it is possible to repeat the "store" keyword followed by one or |
| 6714 | several data types. Except for the "server_id" type which is |
| 6715 | automatically detected and enabled, all data types must be |
| 6716 | explicitly declared to be stored. If an ACL references a data |
| 6717 | type which is not stored, the ACL will simply not match. Some |
| 6718 | data types require an argument which must be passed just after |
| 6719 | the type between parenthesis. See below for the supported data |
| 6720 | types and their arguments. |
| 6721 | |
| 6722 | The data types that can be stored with an entry are the following : |
| 6723 | - server_id : this is an integer which holds the numeric ID of the server a |
| 6724 | request was assigned to. It is used by the "stick match", "stick store", |
| 6725 | and "stick on" rules. It is automatically enabled when referenced. |
| 6726 | |
| 6727 | - gpc0 : first General Purpose Counter. It is a positive 32-bit integer |
| 6728 | integer which may be used for anything. Most of the time it will be used |
| 6729 | to put a special tag on some entries, for instance to note that a |
| 6730 | specific behaviour was detected and must be known for future matches. |
| 6731 | |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 6732 | - gpc0_rate(<period>) : increment rate of the first General Purpose Counter |
| 6733 | over a period. It is a positive 32-bit integer integer which may be used |
| 6734 | for anything. Just like <gpc0>, it counts events, but instead of keeping |
| 6735 | a cumulative count, it maintains the rate at which the counter is |
| 6736 | incremented. Most of the time it will be used to measure the frequency of |
| 6737 | occurrence of certain events (eg: requests to a specific URL). |
| 6738 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 6739 | - conn_cnt : Connection Count. It is a positive 32-bit integer which counts |
| 6740 | the absolute number of connections received from clients which matched |
| 6741 | this entry. It does not mean the connections were accepted, just that |
| 6742 | they were received. |
| 6743 | |
| 6744 | - conn_cur : Current Connections. It is a positive 32-bit integer which |
| 6745 | stores the concurrent connection counts for the entry. It is incremented |
| 6746 | once an incoming connection matches the entry, and decremented once the |
| 6747 | connection leaves. That way it is possible to know at any time the exact |
| 6748 | number of concurrent connections for an entry. |
| 6749 | |
| 6750 | - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 6751 | integer parameter <period> which indicates in milliseconds the length |
| 6752 | of the period over which the average is measured. It reports the average |
| 6753 | incoming connection rate over that period, in connections per period. The |
| 6754 | result is an integer which can be matched using ACLs. |
| 6755 | |
| 6756 | - sess_cnt : Session Count. It is a positive 32-bit integer which counts |
| 6757 | the absolute number of sessions received from clients which matched this |
| 6758 | entry. A session is a connection that was accepted by the layer 4 rules. |
| 6759 | |
| 6760 | - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 6761 | integer parameter <period> which indicates in milliseconds the length |
| 6762 | of the period over which the average is measured. It reports the average |
| 6763 | incoming session rate over that period, in sessions per period. The |
| 6764 | result is an integer which can be matched using ACLs. |
| 6765 | |
| 6766 | - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which |
| 6767 | counts the absolute number of HTTP requests received from clients which |
| 6768 | matched this entry. It does not matter whether they are valid requests or |
| 6769 | not. Note that this is different from sessions when keep-alive is used on |
| 6770 | the client side. |
| 6771 | |
| 6772 | - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 6773 | integer parameter <period> which indicates in milliseconds the length |
| 6774 | of the period over which the average is measured. It reports the average |
| 6775 | HTTP request rate over that period, in requests per period. The result is |
| 6776 | an integer which can be matched using ACLs. It does not matter whether |
| 6777 | they are valid requests or not. Note that this is different from sessions |
| 6778 | when keep-alive is used on the client side. |
| 6779 | |
| 6780 | - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which |
| 6781 | counts the absolute number of HTTP requests errors induced by clients |
| 6782 | which matched this entry. Errors are counted on invalid and truncated |
| 6783 | requests, as well as on denied or tarpitted requests, and on failed |
| 6784 | authentications. If the server responds with 4xx, then the request is |
| 6785 | also counted as an error since it's an error triggered by the client |
| 6786 | (eg: vulnerability scan). |
| 6787 | |
| 6788 | - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 6789 | integer parameter <period> which indicates in milliseconds the length |
| 6790 | of the period over which the average is measured. It reports the average |
| 6791 | HTTP request error rate over that period, in requests per period (see |
| 6792 | http_err_cnt above for what is accounted as an error). The result is an |
| 6793 | integer which can be matched using ACLs. |
| 6794 | |
| 6795 | - bytes_in_cnt : client to server byte count. It is a positive 64-bit |
| 6796 | integer which counts the cumulated amount of bytes received from clients |
| 6797 | which matched this entry. Headers are included in the count. This may be |
| 6798 | used to limit abuse of upload features on photo or video servers. |
| 6799 | |
| 6800 | - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 6801 | integer parameter <period> which indicates in milliseconds the length |
| 6802 | of the period over which the average is measured. It reports the average |
| 6803 | incoming bytes rate over that period, in bytes per period. It may be used |
| 6804 | to detect users which upload too much and too fast. Warning: with large |
| 6805 | uploads, it is possible that the amount of uploaded data will be counted |
| 6806 | once upon termination, thus causing spikes in the average transfer speed |
| 6807 | instead of having a smooth one. This may partially be smoothed with |
| 6808 | "option contstats" though this is not perfect yet. Use of byte_in_cnt is |
| 6809 | recommended for better fairness. |
| 6810 | |
| 6811 | - bytes_out_cnt : server to client byte count. It is a positive 64-bit |
| 6812 | integer which counts the cumulated amount of bytes sent to clients which |
| 6813 | matched this entry. Headers are included in the count. This may be used |
| 6814 | to limit abuse of bots sucking the whole site. |
| 6815 | |
| 6816 | - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes |
| 6817 | an integer parameter <period> which indicates in milliseconds the length |
| 6818 | of the period over which the average is measured. It reports the average |
| 6819 | outgoing bytes rate over that period, in bytes per period. It may be used |
| 6820 | to detect users which download too much and too fast. Warning: with large |
| 6821 | transfers, it is possible that the amount of transferred data will be |
| 6822 | counted once upon termination, thus causing spikes in the average |
| 6823 | transfer speed instead of having a smooth one. This may partially be |
| 6824 | smoothed with "option contstats" though this is not perfect yet. Use of |
| 6825 | byte_out_cnt is recommended for better fairness. |
Willy Tarreau | 08d5f98 | 2010-06-06 13:34:54 +0200 | [diff] [blame] | 6826 | |
Willy Tarreau | c00cdc2 | 2010-06-06 16:48:26 +0200 | [diff] [blame] | 6827 | There is only one stick-table per proxy. At the moment of writing this doc, |
| 6828 | it does not seem useful to have multiple tables per proxy. If this happens |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6829 | to be required, simply create a dummy backend with a stick-table in it and |
| 6830 | reference it. |
| 6831 | |
| 6832 | It is important to understand that stickiness based on learning information |
| 6833 | has some limitations, including the fact that all learned associations are |
| 6834 | lost upon restart. In general it can be good as a complement but not always |
| 6835 | as an exclusive stickiness. |
| 6836 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 6837 | Last, memory requirements may be important when storing many data types. |
| 6838 | Indeed, storing all indicators above at once in each entry requires 116 bytes |
| 6839 | per entry, or 116 MB for a 1-million entries table. This is definitely not |
| 6840 | something that can be ignored. |
| 6841 | |
| 6842 | Example: |
| 6843 | # Keep track of counters of up to 1 million IP addresses over 5 minutes |
| 6844 | # and store a general purpose counter and the average connection rate |
| 6845 | # computed over a sliding window of 30 seconds. |
| 6846 | stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s) |
| 6847 | |
| 6848 | See also : "stick match", "stick on", "stick store-request", section 2.2 |
David du Colombier | a13d1b9 | 2011-03-17 10:40:22 +0100 | [diff] [blame] | 6849 | about time format and section 7 about ACLs. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 6850 | |
| 6851 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6852 | stick store-response <pattern> [table <table>] [{if | unless} <condition>] |
| 6853 | Define a request pattern used to create an entry in a stickiness table |
| 6854 | May be used in sections : defaults | frontend | listen | backend |
| 6855 | no | no | yes | yes |
| 6856 | |
| 6857 | Arguments : |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 6858 | <pattern> is a pattern extraction rule as described in section 7.3. It |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6859 | describes what elements of the response or connection will |
| 6860 | be analysed, extracted and stored in the table once a |
| 6861 | server is selected. |
| 6862 | |
| 6863 | <table> is an optional stickiness table name. If unspecified, the same |
| 6864 | backend's table is used. A stickiness table is declared using |
| 6865 | the "stick-table" statement. |
| 6866 | |
| 6867 | <cond> is an optional storage condition. It makes it possible to store |
| 6868 | certain criteria only when some conditions are met (or not met). |
| 6869 | For instance, it could be used to store the SSL session ID only |
| 6870 | when the response is a SSL server hello. |
| 6871 | |
| 6872 | Some protocols or applications require complex stickiness rules and cannot |
| 6873 | always simply rely on cookies nor hashing. The "stick store-response" |
| 6874 | statement describes a rule to decide what to extract from the response and |
| 6875 | when to do it, in order to store it into a stickiness table for further |
| 6876 | requests to match it using the "stick match" statement. Obviously the |
| 6877 | extracted part must make sense and have a chance to be matched in a further |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 6878 | request. Storing an ID found in a header of a response makes sense. |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6879 | See section 7 for a complete list of possible patterns and transformation |
| 6880 | rules. |
| 6881 | |
| 6882 | The table has to be declared using the "stick-table" statement. It must be of |
| 6883 | a type compatible with the pattern. By default it is the one which is present |
| 6884 | in the same backend. It is possible to share a table with other backends by |
| 6885 | referencing it using the "table" keyword. If another table is referenced, |
| 6886 | the server's ID inside the backends are used. By default, all server IDs |
| 6887 | start at 1 in each backend, so the server ordering is enough. But in case of |
| 6888 | doubt, it is highly recommended to force server IDs using their "id" setting. |
| 6889 | |
| 6890 | It is possible to restrict the conditions where a "stick store-response" |
| 6891 | statement will apply, using "if" or "unless" followed by a condition. This |
| 6892 | condition will be evaluated while parsing the response, so any criteria can |
| 6893 | be used. See section 7 for ACL based conditions. |
| 6894 | |
| 6895 | There is no limit on the number of "stick store-response" statements, but |
| 6896 | there is a limit of 8 simultaneous stores per request or response. This |
| 6897 | makes it possible to store up to 8 criteria, all extracted from either the |
| 6898 | request or the response, regardless of the number of rules. Only the 8 first |
| 6899 | ones which match will be kept. Using this, it is possible to feed multiple |
| 6900 | tables at once in the hope to increase the chance to recognize a user on |
Willy Tarreau | 9667a80 | 2013-12-09 12:52:13 +0100 | [diff] [blame] | 6901 | another protocol or access method. Using multiple store-response rules with |
| 6902 | the same table is possible and may be used to find the best criterion to rely |
| 6903 | on, by arranging the rules by decreasing preference order. Only the first |
| 6904 | extracted criterion for a given table will be stored. All subsequent store- |
| 6905 | response rules referencing the same table will be skipped and their ACLs will |
| 6906 | not be evaluated. However, even if a store-request rule references a table, a |
| 6907 | store-response rule may also use the same table. This means that each table |
| 6908 | may learn exactly one element from the request and one element from the |
| 6909 | response at once. |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6910 | |
| 6911 | The table will contain the real server that processed the request. |
| 6912 | |
| 6913 | Example : |
| 6914 | # Learn SSL session ID from both request and response and create affinity. |
| 6915 | backend https |
| 6916 | mode tcp |
| 6917 | balance roundrobin |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 6918 | # maximum SSL session ID length is 32 bytes. |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6919 | stick-table type binary len 32 size 30k expire 30m |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 6920 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6921 | acl clienthello req_ssl_hello_type 1 |
| 6922 | acl serverhello rep_ssl_hello_type 2 |
| 6923 | |
| 6924 | # use tcp content accepts to detects ssl client and server hello. |
| 6925 | tcp-request inspect-delay 5s |
| 6926 | tcp-request content accept if clienthello |
| 6927 | |
| 6928 | # no timeout on response inspect delay by default. |
| 6929 | tcp-response content accept if serverhello |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 6930 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6931 | # SSL session ID (SSLID) may be present on a client or server hello. |
| 6932 | # Its length is coded on 1 byte at offset 43 and its value starts |
| 6933 | # at offset 44. |
| 6934 | |
| 6935 | # Match and learn on request if client hello. |
| 6936 | stick on payload_lv(43,1) if clienthello |
| 6937 | |
| 6938 | # Learn on response if server hello. |
| 6939 | stick store-response payload_lv(43,1) if serverhello |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 6940 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 6941 | server s1 192.168.1.1:443 |
| 6942 | server s2 192.168.1.1:443 |
| 6943 | |
| 6944 | See also : "stick-table", "stick on", and section 7 about ACLs and pattern |
| 6945 | extraction. |
| 6946 | |
| 6947 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 6948 | tcp-check connect [params*] |
| 6949 | Opens a new connection |
| 6950 | May be used in sections: defaults | frontend | listen | backend |
| 6951 | no | no | yes | yes |
| 6952 | |
| 6953 | When an application lies on more than a single TCP port or when HAProxy |
| 6954 | load-balance many services in a single backend, it makes sense to probe all |
| 6955 | the services individually before considering a server as operational. |
| 6956 | |
| 6957 | When there are no TCP port configured on the server line neither server port |
| 6958 | directive, then the 'tcp-check connect port <port>' must be the first step |
| 6959 | of the sequence. |
| 6960 | |
| 6961 | In a tcp-check ruleset a 'connect' is required, it is also mandatory to start |
| 6962 | the ruleset with a 'connect' rule. Purpose is to ensure admin know what they |
| 6963 | do. |
| 6964 | |
| 6965 | Parameters : |
| 6966 | They are optional and can be used to describe how HAProxy should open and |
| 6967 | use the TCP connection. |
| 6968 | |
| 6969 | port if not set, check port or server port is used. |
| 6970 | It tells HAProxy where to open the connection to. |
| 6971 | <port> must be a valid TCP port source integer, from 1 to 65535. |
| 6972 | |
| 6973 | send-proxy send a PROXY protocol string |
| 6974 | |
| 6975 | ssl opens a ciphered connection |
| 6976 | |
| 6977 | Examples: |
| 6978 | # check HTTP and HTTPs services on a server. |
| 6979 | # first open port 80 thanks to server line port directive, then |
| 6980 | # tcp-check opens port 443, ciphered and run a request on it: |
| 6981 | option tcp-check |
| 6982 | tcp-check connect |
| 6983 | tcp-check send GET\ /\ HTTP/1.0\r\n |
| 6984 | tcp-check send Host:\ haproxy.1wt.eu\r\n |
| 6985 | tcp-check send \r\n |
| 6986 | tcp-check expect rstring (2..|3..) |
| 6987 | tcp-check connect port 443 ssl |
| 6988 | tcp-check send GET\ /\ HTTP/1.0\r\n |
| 6989 | tcp-check send Host:\ haproxy.1wt.eu\r\n |
| 6990 | tcp-check send \r\n |
| 6991 | tcp-check expect rstring (2..|3..) |
| 6992 | server www 10.0.0.1 check port 80 |
| 6993 | |
| 6994 | # check both POP and IMAP from a single server: |
| 6995 | option tcp-check |
| 6996 | tcp-check connect port 110 |
| 6997 | tcp-check expect string +OK\ POP3\ ready |
| 6998 | tcp-check connect port 143 |
| 6999 | tcp-check expect string *\ OK\ IMAP4\ ready |
| 7000 | server mail 10.0.0.1 check |
| 7001 | |
| 7002 | See also : "option tcp-check", "tcp-check send", "tcp-check expect" |
| 7003 | |
| 7004 | |
| 7005 | tcp-check expect [!] <match> <pattern> |
| 7006 | Specify data to be collected and analysed during a generic health check |
| 7007 | May be used in sections: defaults | frontend | listen | backend |
| 7008 | no | no | yes | yes |
| 7009 | |
| 7010 | Arguments : |
| 7011 | <match> is a keyword indicating how to look for a specific pattern in the |
| 7012 | response. The keyword may be one of "string", "rstring" or |
| 7013 | binary. |
| 7014 | The keyword may be preceded by an exclamation mark ("!") to negate |
| 7015 | the match. Spaces are allowed between the exclamation mark and the |
| 7016 | keyword. See below for more details on the supported keywords. |
| 7017 | |
| 7018 | <pattern> is the pattern to look for. It may be a string or a regular |
| 7019 | expression. If the pattern contains spaces, they must be escaped |
| 7020 | with the usual backslash ('\'). |
| 7021 | If the match is set to binary, then the pattern must be passed as |
| 7022 | a serie of hexadecimal digits in an even number. Each sequence of |
| 7023 | two digits will represent a byte. The hexadecimal digits may be |
| 7024 | used upper or lower case. |
| 7025 | |
| 7026 | |
| 7027 | The available matches are intentionally similar to their http-check cousins : |
| 7028 | |
| 7029 | string <string> : test the exact string matches in the response buffer. |
| 7030 | A health check response will be considered valid if the |
| 7031 | response's buffer contains this exact string. If the |
| 7032 | "string" keyword is prefixed with "!", then the response |
| 7033 | will be considered invalid if the body contains this |
| 7034 | string. This can be used to look for a mandatory pattern |
| 7035 | in a protocol response, or to detect a failure when a |
| 7036 | specific error appears in a protocol banner. |
| 7037 | |
| 7038 | rstring <regex> : test a regular expression on the response buffer. |
| 7039 | A health check response will be considered valid if the |
| 7040 | response's buffer matches this expression. If the |
| 7041 | "rstring" keyword is prefixed with "!", then the response |
| 7042 | will be considered invalid if the body matches the |
| 7043 | expression. |
| 7044 | |
| 7045 | binary <hexstring> : test the exact string in its hexadecimal form matches |
| 7046 | in the response buffer. A health check response will |
| 7047 | be considered valid if the response's buffer contains |
| 7048 | this exact hexadecimal string. |
| 7049 | Purpose is to match data on binary protocols. |
| 7050 | |
| 7051 | It is important to note that the responses will be limited to a certain size |
| 7052 | defined by the global "tune.chksize" option, which defaults to 16384 bytes. |
| 7053 | Thus, too large responses may not contain the mandatory pattern when using |
| 7054 | "string", "rstring" or binary. If a large response is absolutely required, it |
| 7055 | is possible to change the default max size by setting the global variable. |
| 7056 | However, it is worth keeping in mind that parsing very large responses can |
| 7057 | waste some CPU cycles, especially when regular expressions are used, and that |
| 7058 | it is always better to focus the checks on smaller resources. Also, in its |
| 7059 | current state, the check will not find any string nor regex past a null |
| 7060 | character in the response. Similarly it is not possible to request matching |
| 7061 | the null character. |
| 7062 | |
| 7063 | Examples : |
| 7064 | # perform a POP check |
| 7065 | option tcp-check |
| 7066 | tcp-check expect string +OK\ POP3\ ready |
| 7067 | |
| 7068 | # perform an IMAP check |
| 7069 | option tcp-check |
| 7070 | tcp-check expect string *\ OK\ IMAP4\ ready |
| 7071 | |
| 7072 | # look for the redis master server |
| 7073 | option tcp-check |
| 7074 | tcp-check send PING\r\n |
| 7075 | tcp-check expect +PONG |
| 7076 | tcp-check send info\ replication\r\n |
| 7077 | tcp-check expect string role:master |
| 7078 | tcp-check send QUIT\r\n |
| 7079 | tcp-check expect string +OK |
| 7080 | |
| 7081 | |
| 7082 | See also : "option tcp-check", "tcp-check connect", "tcp-check send", |
| 7083 | "tcp-check send-binary", "http-check expect", tune.chksize |
| 7084 | |
| 7085 | |
| 7086 | tcp-check send <data> |
| 7087 | Specify a string to be sent as a question during a generic health check |
| 7088 | May be used in sections: defaults | frontend | listen | backend |
| 7089 | no | no | yes | yes |
| 7090 | |
| 7091 | <data> : the data to be sent as a question during a generic health check |
| 7092 | session. For now, <data> must be a string. |
| 7093 | |
| 7094 | Examples : |
| 7095 | # look for the redis master server |
| 7096 | option tcp-check |
| 7097 | tcp-check send info\ replication\r\n |
| 7098 | tcp-check expect string role:master |
| 7099 | |
| 7100 | See also : "option tcp-check", "tcp-check connect", "tcp-check expect", |
| 7101 | "tcp-check send-binary", tune.chksize |
| 7102 | |
| 7103 | |
| 7104 | tcp-check send-binary <hexastring> |
| 7105 | Specify an hexa digits string to be sent as a binary question during a raw |
| 7106 | tcp health check |
| 7107 | May be used in sections: defaults | frontend | listen | backend |
| 7108 | no | no | yes | yes |
| 7109 | |
| 7110 | <data> : the data to be sent as a question during a generic health check |
| 7111 | session. For now, <data> must be a string. |
| 7112 | <hexastring> : test the exact string in its hexadecimal form matches in the |
| 7113 | response buffer. A health check response will be considered |
| 7114 | valid if the response's buffer contains this exact |
| 7115 | hexadecimal string. |
| 7116 | Purpose is to send binary data to ask on binary protocols. |
| 7117 | |
| 7118 | Examples : |
| 7119 | # redis check in binary |
| 7120 | option tcp-check |
| 7121 | tcp-check send-binary 50494e470d0a # PING\r\n |
| 7122 | tcp-check expect binary 2b504F4e47 # +PONG |
| 7123 | |
| 7124 | |
| 7125 | See also : "option tcp-check", "tcp-check connect", "tcp-check expect", |
| 7126 | "tcp-check send", tune.chksize |
| 7127 | |
| 7128 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7129 | tcp-request connection <action> [{if | unless} <condition>] |
| 7130 | Perform an action on an incoming connection depending on a layer 4 condition |
Willy Tarreau | 1a68794 | 2010-05-23 22:40:30 +0200 | [diff] [blame] | 7131 | May be used in sections : defaults | frontend | listen | backend |
| 7132 | no | yes | yes | no |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7133 | Arguments : |
| 7134 | <action> defines the action to perform if the condition applies. Valid |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7135 | actions include : "accept", "reject", "track-sc0", "track-sc1", |
| 7136 | "track-sc2", and "expect-proxy". See below for more details. |
Willy Tarreau | 1a68794 | 2010-05-23 22:40:30 +0200 | [diff] [blame] | 7137 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7138 | <condition> is a standard layer4-only ACL-based condition (see section 7). |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7139 | |
| 7140 | Immediately after acceptance of a new incoming connection, it is possible to |
| 7141 | evaluate some conditions to decide whether this connection must be accepted |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7142 | or dropped or have its counters tracked. Those conditions cannot make use of |
| 7143 | any data contents because the connection has not been read from yet, and the |
| 7144 | buffers are not yet allocated. This is used to selectively and very quickly |
| 7145 | accept or drop connections from various sources with a very low overhead. If |
| 7146 | some contents need to be inspected in order to take the decision, the |
| 7147 | "tcp-request content" statements must be used instead. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7148 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7149 | The "tcp-request connection" rules are evaluated in their exact declaration |
| 7150 | order. If no rule matches or if there is no rule, the default action is to |
| 7151 | accept the incoming connection. There is no specific limit to the number of |
| 7152 | rules which may be inserted. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7153 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7154 | Three types of actions are supported : |
| 7155 | - accept : |
| 7156 | accepts the connection if the condition is true (when used with "if") |
| 7157 | or false (when used with "unless"). The first such rule executed ends |
| 7158 | the rules evaluation. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7159 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7160 | - reject : |
| 7161 | rejects the connection if the condition is true (when used with "if") |
| 7162 | or false (when used with "unless"). The first such rule executed ends |
| 7163 | the rules evaluation. Rejected connections do not even become a |
| 7164 | session, which is why they are accounted separately for in the stats, |
| 7165 | as "denied connections". They are not considered for the session |
| 7166 | rate-limit and are not logged either. The reason is that these rules |
| 7167 | should only be used to filter extremely high connection rates such as |
| 7168 | the ones encountered during a massive DDoS attack. Under these extreme |
| 7169 | conditions, the simple action of logging each event would make the |
| 7170 | system collapse and would considerably lower the filtering capacity. If |
| 7171 | logging is absolutely desired, then "tcp-request content" rules should |
| 7172 | be used instead. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7173 | |
Willy Tarreau | 4f0d919 | 2013-06-11 20:40:55 +0200 | [diff] [blame] | 7174 | - expect-proxy layer4 : |
| 7175 | configures the client-facing connection to receive a PROXY protocol |
| 7176 | header before any byte is read from the socket. This is equivalent to |
| 7177 | having the "accept-proxy" keyword on the "bind" line, except that using |
| 7178 | the TCP rule allows the PROXY protocol to be accepted only for certain |
| 7179 | IP address ranges using an ACL. This is convenient when multiple layers |
| 7180 | of load balancers are passed through by traffic coming from public |
| 7181 | hosts. |
| 7182 | |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7183 | - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] : |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7184 | enables tracking of sticky counters from current connection. These |
| 7185 | rules do not stop evaluation and do not change default action. Two sets |
| 7186 | of counters may be simultaneously tracked by the same connection. The |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7187 | first "track-sc0" rule executed enables tracking of the counters of the |
| 7188 | specified table as the first set. The first "track-sc1" rule executed |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7189 | enables tracking of the counters of the specified table as the second |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7190 | set. The first "track-sc2" rule executed enables tracking of the |
| 7191 | counters of the specified table as the third set. It is a recommended |
| 7192 | practice to use the first set of counters for the per-frontend counters |
| 7193 | and the second set for the per-backend ones. But this is just a |
| 7194 | guideline, all may be used everywhere. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7195 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7196 | These actions take one or two arguments : |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7197 | <key> is mandatory, and is a pattern extraction rule as described |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 7198 | in section 7.3. It describes what elements of the incoming |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7199 | request or connection will be analysed, extracted, combined, |
| 7200 | and used to select which table entry to update the counters. |
| 7201 | Note that "tcp-request connection" cannot use content-based |
| 7202 | fetches. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7203 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7204 | <table> is an optional table to be used instead of the default one, |
| 7205 | which is the stick-table declared in the current proxy. All |
| 7206 | the counters for the matches and updates for the key will |
| 7207 | then be performed in that table until the session ends. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7208 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7209 | Once a "track-sc*" rule is executed, the key is looked up in the table |
| 7210 | and if it is not found, an entry is allocated for it. Then a pointer to |
| 7211 | that entry is kept during all the session's life, and this entry's |
| 7212 | counters are updated as often as possible, every time the session's |
| 7213 | counters are updated, and also systematically when the session ends. |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7214 | Counters are only updated for events that happen after the tracking has |
| 7215 | been started. For example, connection counters will not be updated when |
| 7216 | tracking layer 7 information, since the connection event happens before |
| 7217 | layer7 information is extracted. |
| 7218 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7219 | If the entry tracks concurrent connection counters, one connection is |
| 7220 | counted for as long as the entry is tracked, and the entry will not |
| 7221 | expire during that time. Tracking counters also provides a performance |
| 7222 | advantage over just checking the keys, because only one table lookup is |
| 7223 | performed for all ACL checks that make use of it. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7224 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7225 | Note that the "if/unless" condition is optional. If no condition is set on |
| 7226 | the action, it is simply performed unconditionally. That can be useful for |
| 7227 | "track-sc*" actions as well as for changing the default action to a reject. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7228 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7229 | Example: accept all connections from white-listed hosts, reject too fast |
| 7230 | connection without counting them, and track accepted connections. |
| 7231 | This results in connection rate being capped from abusive sources. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7232 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7233 | tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst } |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7234 | tcp-request connection reject if { src_conn_rate gt 10 } |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7235 | tcp-request connection track-sc0 src |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7236 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7237 | Example: accept all connections from white-listed hosts, count all other |
| 7238 | connections and reject too fast ones. This results in abusive ones |
| 7239 | being blocked as long as they don't slow down. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7240 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7241 | tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst } |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7242 | tcp-request connection track-sc0 src |
| 7243 | tcp-request connection reject if { sc0_conn_rate gt 10 } |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7244 | |
Willy Tarreau | 4f0d919 | 2013-06-11 20:40:55 +0200 | [diff] [blame] | 7245 | Example: enable the PROXY protocol for traffic coming from all known proxies. |
| 7246 | |
| 7247 | tcp-request connection expect-proxy layer4 if { src -f proxies.lst } |
| 7248 | |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7249 | See section 7 about ACL usage. |
| 7250 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7251 | See also : "tcp-request content", "stick-table" |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7252 | |
| 7253 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7254 | tcp-request content <action> [{if | unless} <condition>] |
| 7255 | Perform an action on a new session depending on a layer 4-7 condition |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7256 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | fb35620 | 2010-08-03 14:02:05 +0200 | [diff] [blame] | 7257 | no | yes | yes | yes |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7258 | Arguments : |
| 7259 | <action> defines the action to perform if the condition applies. Valid |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7260 | actions include : "accept", "reject", "track-sc0", "track-sc1", |
| 7261 | and "track-sc2". See "tcp-request connection" above for their |
Willy Tarreau | e25c917 | 2013-05-28 18:32:20 +0200 | [diff] [blame] | 7262 | signification. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7263 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7264 | <condition> is a standard layer 4-7 ACL-based condition (see section 7). |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7265 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7266 | A request's contents can be analysed at an early stage of request processing |
| 7267 | called "TCP content inspection". During this stage, ACL-based rules are |
| 7268 | evaluated every time the request contents are updated, until either an |
| 7269 | "accept" or a "reject" rule matches, or the TCP request inspection delay |
| 7270 | expires with no matching rule. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7271 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7272 | The first difference between these rules and "tcp-request connection" rules |
| 7273 | is that "tcp-request content" rules can make use of contents to take a |
| 7274 | decision. Most often, these decisions will consider a protocol recognition or |
| 7275 | validity. The second difference is that content-based rules can be used in |
Willy Tarreau | f333834 | 2014-01-28 21:40:28 +0100 | [diff] [blame] | 7276 | both frontends and backends. In case of HTTP keep-alive with the client, all |
| 7277 | tcp-request content rules are evaluated again, so haproxy keeps a record of |
| 7278 | what sticky counters were assigned by a "tcp-request connection" versus a |
| 7279 | "tcp-request content" rule, and flushes all the content-related ones after |
| 7280 | processing an HTTP request, so that they may be evaluated again by the rules |
| 7281 | being evaluated again for the next request. This is of particular importance |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 7282 | when the rule tracks some L7 information or when it is conditioned by an |
Willy Tarreau | f333834 | 2014-01-28 21:40:28 +0100 | [diff] [blame] | 7283 | L7-based ACL, since tracking may change between requests. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7284 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7285 | Content-based rules are evaluated in their exact declaration order. If no |
| 7286 | rule matches or if there is no rule, the default action is to accept the |
| 7287 | contents. There is no specific limit to the number of rules which may be |
| 7288 | inserted. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7289 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7290 | Three types of actions are supported : |
| 7291 | - accept : |
| 7292 | - reject : |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7293 | - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7294 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7295 | They have the same meaning as their counter-parts in "tcp-request connection" |
| 7296 | so please refer to that section for a complete description. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7297 | |
Willy Tarreau | f333834 | 2014-01-28 21:40:28 +0100 | [diff] [blame] | 7298 | While there is nothing mandatory about it, it is recommended to use the |
| 7299 | track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request |
| 7300 | content" rules in the frontend, and track-sc2 for "tcp-request content" |
| 7301 | rules in the backend, because that makes the configuration more readable |
| 7302 | and easier to troubleshoot, but this is just a guideline and all counters |
| 7303 | may be used everywhere. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7304 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 7305 | Note that the "if/unless" condition is optional. If no condition is set on |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7306 | the action, it is simply performed unconditionally. That can be useful for |
| 7307 | "track-sc*" actions as well as for changing the default action to a reject. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7308 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7309 | It is perfectly possible to match layer 7 contents with "tcp-request content" |
Willy Tarreau | c0239e0 | 2012-04-16 14:42:55 +0200 | [diff] [blame] | 7310 | rules, since HTTP-specific ACL matches are able to preliminarily parse the |
| 7311 | contents of a buffer before extracting the required data. If the buffered |
| 7312 | contents do not parse as a valid HTTP message, then the ACL does not match. |
| 7313 | The parser which is involved there is exactly the same as for all other HTTP |
Willy Tarreau | f333834 | 2014-01-28 21:40:28 +0100 | [diff] [blame] | 7314 | processing, so there is no risk of parsing something differently. In an HTTP |
| 7315 | backend connected to from an HTTP frontend, it is guaranteed that HTTP |
| 7316 | contents will always be immediately present when the rule is evaluated first. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7317 | |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7318 | Tracking layer7 information is also possible provided that the information |
| 7319 | are present when the rule is processed. The current solution for making the |
| 7320 | rule engine wait for such information is to set an inspect delay and to |
| 7321 | condition its execution with an ACL relying on such information. |
| 7322 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7323 | Example: |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7324 | # Accept HTTP requests containing a Host header saying "example.com" |
| 7325 | # and reject everything else. |
| 7326 | acl is_host_com hdr(Host) -i example.com |
| 7327 | tcp-request inspect-delay 30s |
Willy Tarreau | c0239e0 | 2012-04-16 14:42:55 +0200 | [diff] [blame] | 7328 | tcp-request content accept if is_host_com |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7329 | tcp-request content reject |
| 7330 | |
| 7331 | Example: |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7332 | # reject SMTP connection if client speaks first |
| 7333 | tcp-request inspect-delay 30s |
| 7334 | acl content_present req_len gt 0 |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7335 | tcp-request content reject if content_present |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7336 | |
| 7337 | # Forward HTTPS connection only if client speaks |
| 7338 | tcp-request inspect-delay 30s |
| 7339 | acl content_present req_len gt 0 |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 7340 | tcp-request content accept if content_present |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7341 | tcp-request content reject |
| 7342 | |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7343 | Example: |
| 7344 | # Track the last IP from X-Forwarded-For |
| 7345 | tcp-request inspect-delay 10s |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7346 | tcp-request content track-sc0 hdr(x-forwarded-for,-1) if HTTP |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7347 | |
| 7348 | Example: |
| 7349 | # track request counts per "base" (concatenation of Host+URL) |
| 7350 | tcp-request inspect-delay 10s |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7351 | tcp-request content track-sc0 base table req-rate if HTTP |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 7352 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7353 | Example: track per-frontend and per-backend counters, block abusers at the |
| 7354 | frontend when the backend detects abuse. |
| 7355 | |
| 7356 | frontend http |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7357 | # Use General Purpose Couter 0 in SC0 as a global abuse counter |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7358 | # protecting all our sites |
| 7359 | stick-table type ip size 1m expire 5m store gpc0 |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7360 | tcp-request connection track-sc0 src |
| 7361 | tcp-request connection reject if { sc0_get_gpc0 gt 0 } |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7362 | ... |
| 7363 | use_backend http_dynamic if { path_end .php } |
| 7364 | |
| 7365 | backend http_dynamic |
| 7366 | # if a source makes too fast requests to this dynamic site (tracked |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7367 | # by SC1), block it globally in the frontend. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7368 | stick-table type ip size 1m expire 5m store http_req_rate(10s) |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 7369 | acl click_too_fast sc1_http_req_rate gt 10 |
| 7370 | acl mark_as_abuser sc0_inc_gpc0 gt 0 |
| 7371 | tcp-request content track-sc1 src |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7372 | tcp-request content reject if click_too_fast mark_as_abuser |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7373 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 7374 | See section 7 about ACL usage. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7375 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 7376 | See also : "tcp-request connection", "tcp-request inspect-delay" |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7377 | |
| 7378 | |
| 7379 | tcp-request inspect-delay <timeout> |
| 7380 | Set the maximum allowed time to wait for data during content inspection |
| 7381 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | fb35620 | 2010-08-03 14:02:05 +0200 | [diff] [blame] | 7382 | no | yes | yes | yes |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7383 | Arguments : |
| 7384 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7385 | can be in any other unit if the number is suffixed by the unit, |
| 7386 | as explained at the top of this document. |
| 7387 | |
| 7388 | People using haproxy primarily as a TCP relay are often worried about the |
| 7389 | risk of passing any type of protocol to a server without any analysis. In |
| 7390 | order to be able to analyze the request contents, we must first withhold |
| 7391 | the data then analyze them. This statement simply enables withholding of |
| 7392 | data for at most the specified amount of time. |
| 7393 | |
Willy Tarreau | fb35620 | 2010-08-03 14:02:05 +0200 | [diff] [blame] | 7394 | TCP content inspection applies very early when a connection reaches a |
| 7395 | frontend, then very early when the connection is forwarded to a backend. This |
| 7396 | means that a connection may experience a first delay in the frontend and a |
| 7397 | second delay in the backend if both have tcp-request rules. |
| 7398 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7399 | Note that when performing content inspection, haproxy will evaluate the whole |
| 7400 | rules for every new chunk which gets in, taking into account the fact that |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 7401 | those data are partial. If no rule matches before the aforementioned delay, |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7402 | a last check is performed upon expiration, this time considering that the |
Willy Tarreau | d869b24 | 2009-03-15 14:43:58 +0100 | [diff] [blame] | 7403 | contents are definitive. If no delay is set, haproxy will not wait at all |
| 7404 | and will immediately apply a verdict based on the available information. |
| 7405 | Obviously this is unlikely to be very useful and might even be racy, so such |
| 7406 | setups are not recommended. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7407 | |
| 7408 | As soon as a rule matches, the request is released and continues as usual. If |
| 7409 | the timeout is reached and no rule matches, the default policy will be to let |
| 7410 | it pass through unaffected. |
| 7411 | |
| 7412 | For most protocols, it is enough to set it to a few seconds, as most clients |
| 7413 | send the full request immediately upon connection. Add 3 or more seconds to |
| 7414 | cover TCP retransmits but that's all. For some protocols, it may make sense |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 7415 | to use large values, for instance to ensure that the client never talks |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7416 | before the server (eg: SMTP), or to wait for a client to talk before passing |
| 7417 | data to the server (eg: SSL). Note that the client timeout must cover at |
Willy Tarreau | b824b00 | 2010-09-29 16:36:16 +0200 | [diff] [blame] | 7418 | least the inspection delay, otherwise it will expire first. If the client |
| 7419 | closes the connection or if the buffer is full, the delay immediately expires |
| 7420 | since the contents will not be able to change anymore. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7421 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 7422 | See also : "tcp-request content accept", "tcp-request content reject", |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 7423 | "timeout client". |
| 7424 | |
| 7425 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 7426 | tcp-response content <action> [{if | unless} <condition>] |
| 7427 | Perform an action on a session response depending on a layer 4-7 condition |
| 7428 | May be used in sections : defaults | frontend | listen | backend |
| 7429 | no | no | yes | yes |
| 7430 | Arguments : |
| 7431 | <action> defines the action to perform if the condition applies. Valid |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 7432 | actions include : "accept", "close", "reject". |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 7433 | |
| 7434 | <condition> is a standard layer 4-7 ACL-based condition (see section 7). |
| 7435 | |
| 7436 | Response contents can be analysed at an early stage of response processing |
| 7437 | called "TCP content inspection". During this stage, ACL-based rules are |
| 7438 | evaluated every time the response contents are updated, until either an |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 7439 | "accept", "close" or a "reject" rule matches, or a TCP response inspection |
| 7440 | delay is set and expires with no matching rule. |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 7441 | |
| 7442 | Most often, these decisions will consider a protocol recognition or validity. |
| 7443 | |
| 7444 | Content-based rules are evaluated in their exact declaration order. If no |
| 7445 | rule matches or if there is no rule, the default action is to accept the |
| 7446 | contents. There is no specific limit to the number of rules which may be |
| 7447 | inserted. |
| 7448 | |
| 7449 | Two types of actions are supported : |
| 7450 | - accept : |
| 7451 | accepts the response if the condition is true (when used with "if") |
| 7452 | or false (when used with "unless"). The first such rule executed ends |
| 7453 | the rules evaluation. |
| 7454 | |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 7455 | - close : |
| 7456 | immediately closes the connection with the server if the condition is |
| 7457 | true (when used with "if"), or false (when used with "unless"). The |
| 7458 | first such rule executed ends the rules evaluation. The main purpose of |
| 7459 | this action is to force a connection to be finished between a client |
| 7460 | and a server after an exchange when the application protocol expects |
| 7461 | some long time outs to elapse first. The goal is to eliminate idle |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 7462 | connections which take significant resources on servers with certain |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 7463 | protocols. |
| 7464 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 7465 | - reject : |
| 7466 | rejects the response if the condition is true (when used with "if") |
| 7467 | or false (when used with "unless"). The first such rule executed ends |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 7468 | the rules evaluation. Rejected session are immediately closed. |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 7469 | |
| 7470 | Note that the "if/unless" condition is optional. If no condition is set on |
| 7471 | the action, it is simply performed unconditionally. That can be useful for |
| 7472 | for changing the default action to a reject. |
| 7473 | |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 7474 | It is perfectly possible to match layer 7 contents with "tcp-response |
| 7475 | content" rules, but then it is important to ensure that a full response has |
| 7476 | been buffered, otherwise no contents will match. In order to achieve this, |
| 7477 | the best solution involves detecting the HTTP protocol during the inspection |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 7478 | period. |
| 7479 | |
| 7480 | See section 7 about ACL usage. |
| 7481 | |
| 7482 | See also : "tcp-request content", "tcp-response inspect-delay" |
| 7483 | |
| 7484 | |
| 7485 | tcp-response inspect-delay <timeout> |
| 7486 | Set the maximum allowed time to wait for a response during content inspection |
| 7487 | May be used in sections : defaults | frontend | listen | backend |
| 7488 | no | no | yes | yes |
| 7489 | Arguments : |
| 7490 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7491 | can be in any other unit if the number is suffixed by the unit, |
| 7492 | as explained at the top of this document. |
| 7493 | |
| 7494 | See also : "tcp-response content", "tcp-request inspect-delay". |
| 7495 | |
| 7496 | |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 7497 | timeout check <timeout> |
| 7498 | Set additional check timeout, but only after a connection has been already |
| 7499 | established. |
| 7500 | |
| 7501 | May be used in sections: defaults | frontend | listen | backend |
| 7502 | yes | no | yes | yes |
| 7503 | Arguments: |
| 7504 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7505 | can be in any other unit if the number is suffixed by the unit, |
| 7506 | as explained at the top of this document. |
| 7507 | |
| 7508 | If set, haproxy uses min("timeout connect", "inter") as a connect timeout |
| 7509 | for check and "timeout check" as an additional read timeout. The "min" is |
| 7510 | used so that people running with *very* long "timeout connect" (eg. those |
| 7511 | who needed this due to the queue or tarpit) do not slow down their checks. |
Willy Tarreau | d7550a2 | 2010-02-10 05:10:19 +0100 | [diff] [blame] | 7512 | (Please also note that there is no valid reason to have such long connect |
| 7513 | timeouts, because "timeout queue" and "timeout tarpit" can always be used to |
| 7514 | avoid that). |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 7515 | |
| 7516 | If "timeout check" is not set haproxy uses "inter" for complete check |
| 7517 | timeout (connect + read) exactly like all <1.3.15 version. |
| 7518 | |
| 7519 | In most cases check request is much simpler and faster to handle than normal |
| 7520 | requests and people may want to kick out laggy servers so this timeout should |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 7521 | be smaller than "timeout server". |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 7522 | |
| 7523 | This parameter is specific to backends, but can be specified once for all in |
| 7524 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 7525 | forget about it. |
| 7526 | |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 7527 | See also: "timeout connect", "timeout queue", "timeout server", |
| 7528 | "timeout tarpit". |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 7529 | |
| 7530 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7531 | timeout client <timeout> |
| 7532 | timeout clitimeout <timeout> (deprecated) |
| 7533 | Set the maximum inactivity time on the client side. |
| 7534 | May be used in sections : defaults | frontend | listen | backend |
| 7535 | yes | yes | yes | no |
| 7536 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7537 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7538 | can be in any other unit if the number is suffixed by the unit, |
| 7539 | as explained at the top of this document. |
| 7540 | |
| 7541 | The inactivity timeout applies when the client is expected to acknowledge or |
| 7542 | send data. In HTTP mode, this timeout is particularly important to consider |
| 7543 | during the first phase, when the client sends the request, and during the |
| 7544 | response while it is reading data sent by the server. The value is specified |
| 7545 | in milliseconds by default, but can be in any other unit if the number is |
| 7546 | suffixed by the unit, as specified at the top of this document. In TCP mode |
| 7547 | (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| 7548 | client timeout remains equal to the server timeout in order to avoid complex |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 7549 | situations to debug. It is a good practice to cover one or several TCP packet |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7550 | losses by specifying timeouts that are slightly above multiples of 3 seconds |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7551 | (eg: 4 or 5 seconds). If some long-lived sessions are mixed with short-lived |
| 7552 | sessions (eg: WebSocket and HTTP), it's worth considering "timeout tunnel", |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 7553 | which overrides "timeout client" and "timeout server" for tunnels, as well as |
| 7554 | "timeout client-fin" for half-closed connections. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7555 | |
| 7556 | This parameter is specific to frontends, but can be specified once for all in |
| 7557 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 7558 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 7559 | is not recommended. Such a usage is accepted and works but reports a warning |
| 7560 | during startup because it may results in accumulation of expired sessions in |
| 7561 | the system if the system's timeouts are not configured either. |
| 7562 | |
| 7563 | This parameter replaces the old, deprecated "clitimeout". It is recommended |
| 7564 | to use it to write new configurations. The form "timeout clitimeout" is |
| 7565 | provided only by backwards compatibility but its use is strongly discouraged. |
| 7566 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7567 | See also : "clitimeout", "timeout server", "timeout tunnel". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7568 | |
| 7569 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 7570 | timeout client-fin <timeout> |
| 7571 | Set the inactivity timeout on the client side for half-closed connections. |
| 7572 | May be used in sections : defaults | frontend | listen | backend |
| 7573 | yes | yes | yes | no |
| 7574 | Arguments : |
| 7575 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7576 | can be in any other unit if the number is suffixed by the unit, |
| 7577 | as explained at the top of this document. |
| 7578 | |
| 7579 | The inactivity timeout applies when the client is expected to acknowledge or |
| 7580 | send data while one direction is already shut down. This timeout is different |
| 7581 | from "timeout client" in that it only applies to connections which are closed |
| 7582 | in one direction. This is particularly useful to avoid keeping connections in |
| 7583 | FIN_WAIT state for too long when clients do not disconnect cleanly. This |
| 7584 | problem is particularly common long connections such as RDP or WebSocket. |
| 7585 | Note that this timeout can override "timeout tunnel" when a connection shuts |
| 7586 | down in one direction. |
| 7587 | |
| 7588 | This parameter is specific to frontends, but can be specified once for all in |
| 7589 | "defaults" sections. By default it is not set, so half-closed connections |
| 7590 | will use the other timeouts (timeout.client or timeout.tunnel). |
| 7591 | |
| 7592 | See also : "timeout client", "timeout server-fin", and "timeout tunnel". |
| 7593 | |
| 7594 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7595 | timeout connect <timeout> |
| 7596 | timeout contimeout <timeout> (deprecated) |
| 7597 | Set the maximum time to wait for a connection attempt to a server to succeed. |
| 7598 | May be used in sections : defaults | frontend | listen | backend |
| 7599 | yes | no | yes | yes |
| 7600 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7601 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7602 | can be in any other unit if the number is suffixed by the unit, |
| 7603 | as explained at the top of this document. |
| 7604 | |
| 7605 | If the server is located on the same LAN as haproxy, the connection should be |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 7606 | immediate (less than a few milliseconds). Anyway, it is a good practice to |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 7607 | cover one or several TCP packet losses by specifying timeouts that are |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7608 | slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 7609 | connect timeout also presets both queue and tarpit timeouts to the same value |
| 7610 | if these have not been specified. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7611 | |
| 7612 | This parameter is specific to backends, but can be specified once for all in |
| 7613 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 7614 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 7615 | is not recommended. Such a usage is accepted and works but reports a warning |
| 7616 | during startup because it may results in accumulation of failed sessions in |
| 7617 | the system if the system's timeouts are not configured either. |
| 7618 | |
| 7619 | This parameter replaces the old, deprecated "contimeout". It is recommended |
| 7620 | to use it to write new configurations. The form "timeout contimeout" is |
| 7621 | provided only by backwards compatibility but its use is strongly discouraged. |
| 7622 | |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 7623 | See also: "timeout check", "timeout queue", "timeout server", "contimeout", |
| 7624 | "timeout tarpit". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7625 | |
| 7626 | |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 7627 | timeout http-keep-alive <timeout> |
| 7628 | Set the maximum allowed time to wait for a new HTTP request to appear |
| 7629 | May be used in sections : defaults | frontend | listen | backend |
| 7630 | yes | yes | yes | yes |
| 7631 | Arguments : |
| 7632 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7633 | can be in any other unit if the number is suffixed by the unit, |
| 7634 | as explained at the top of this document. |
| 7635 | |
| 7636 | By default, the time to wait for a new request in case of keep-alive is set |
| 7637 | by "timeout http-request". However this is not always convenient because some |
| 7638 | people want very short keep-alive timeouts in order to release connections |
| 7639 | faster, and others prefer to have larger ones but still have short timeouts |
| 7640 | once the request has started to present itself. |
| 7641 | |
| 7642 | The "http-keep-alive" timeout covers these needs. It will define how long to |
| 7643 | wait for a new HTTP request to start coming after a response was sent. Once |
| 7644 | the first byte of request has been seen, the "http-request" timeout is used |
| 7645 | to wait for the complete request to come. Note that empty lines prior to a |
| 7646 | new request do not refresh the timeout and are not counted as a new request. |
| 7647 | |
| 7648 | There is also another difference between the two timeouts : when a connection |
| 7649 | expires during timeout http-keep-alive, no error is returned, the connection |
| 7650 | just closes. If the connection expires in "http-request" while waiting for a |
| 7651 | connection to complete, a HTTP 408 error is returned. |
| 7652 | |
| 7653 | In general it is optimal to set this value to a few tens to hundreds of |
| 7654 | milliseconds, to allow users to fetch all objects of a page at once but |
| 7655 | without waiting for further clicks. Also, if set to a very small value (eg: |
| 7656 | 1 millisecond) it will probably only accept pipelined requests but not the |
| 7657 | non-pipelined ones. It may be a nice trade-off for very large sites running |
Patrick Mézard | 2382ad6 | 2010-05-09 10:43:32 +0200 | [diff] [blame] | 7658 | with tens to hundreds of thousands of clients. |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 7659 | |
| 7660 | If this parameter is not set, the "http-request" timeout applies, and if both |
| 7661 | are not set, "timeout client" still applies at the lower level. It should be |
| 7662 | set in the frontend to take effect, unless the frontend is in TCP mode, in |
| 7663 | which case the HTTP backend's timeout will be used. |
| 7664 | |
| 7665 | See also : "timeout http-request", "timeout client". |
| 7666 | |
| 7667 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7668 | timeout http-request <timeout> |
| 7669 | Set the maximum allowed time to wait for a complete HTTP request |
| 7670 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | cd7afc0 | 2009-07-12 10:03:17 +0200 | [diff] [blame] | 7671 | yes | yes | yes | yes |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7672 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7673 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7674 | can be in any other unit if the number is suffixed by the unit, |
| 7675 | as explained at the top of this document. |
| 7676 | |
| 7677 | In order to offer DoS protection, it may be required to lower the maximum |
| 7678 | accepted time to receive a complete HTTP request without affecting the client |
| 7679 | timeout. This helps protecting against established connections on which |
| 7680 | nothing is sent. The client timeout cannot offer a good protection against |
| 7681 | this abuse because it is an inactivity timeout, which means that if the |
| 7682 | attacker sends one character every now and then, the timeout will not |
| 7683 | trigger. With the HTTP request timeout, no matter what speed the client |
| 7684 | types, the request will be aborted if it does not complete in time. |
| 7685 | |
| 7686 | Note that this timeout only applies to the header part of the request, and |
| 7687 | not to any data. As soon as the empty line is received, this timeout is not |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 7688 | used anymore. It is used again on keep-alive connections to wait for a second |
| 7689 | request if "timeout http-keep-alive" is not set. |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7690 | |
| 7691 | Generally it is enough to set it to a few seconds, as most clients send the |
| 7692 | full request immediately upon connection. Add 3 or more seconds to cover TCP |
| 7693 | retransmits but that's all. Setting it to very low values (eg: 50 ms) will |
| 7694 | generally work on local networks as long as there are no packet losses. This |
| 7695 | will prevent people from sending bare HTTP requests using telnet. |
| 7696 | |
| 7697 | If this parameter is not set, the client timeout still applies between each |
Willy Tarreau | cd7afc0 | 2009-07-12 10:03:17 +0200 | [diff] [blame] | 7698 | chunk of the incoming request. It should be set in the frontend to take |
| 7699 | effect, unless the frontend is in TCP mode, in which case the HTTP backend's |
| 7700 | timeout will be used. |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7701 | |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 7702 | See also : "timeout http-keep-alive", "timeout client". |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7703 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7704 | |
| 7705 | timeout queue <timeout> |
| 7706 | Set the maximum time to wait in the queue for a connection slot to be free |
| 7707 | May be used in sections : defaults | frontend | listen | backend |
| 7708 | yes | no | yes | yes |
| 7709 | Arguments : |
| 7710 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7711 | can be in any other unit if the number is suffixed by the unit, |
| 7712 | as explained at the top of this document. |
| 7713 | |
| 7714 | When a server's maxconn is reached, connections are left pending in a queue |
| 7715 | which may be server-specific or global to the backend. In order not to wait |
| 7716 | indefinitely, a timeout is applied to requests pending in the queue. If the |
| 7717 | timeout is reached, it is considered that the request will almost never be |
| 7718 | served, so it is dropped and a 503 error is returned to the client. |
| 7719 | |
| 7720 | The "timeout queue" statement allows to fix the maximum time for a request to |
| 7721 | be left pending in a queue. If unspecified, the same value as the backend's |
| 7722 | connection timeout ("timeout connect") is used, for backwards compatibility |
| 7723 | with older versions with no "timeout queue" parameter. |
| 7724 | |
| 7725 | See also : "timeout connect", "contimeout". |
| 7726 | |
| 7727 | |
| 7728 | timeout server <timeout> |
| 7729 | timeout srvtimeout <timeout> (deprecated) |
| 7730 | Set the maximum inactivity time on the server side. |
| 7731 | May be used in sections : defaults | frontend | listen | backend |
| 7732 | yes | no | yes | yes |
| 7733 | Arguments : |
| 7734 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7735 | can be in any other unit if the number is suffixed by the unit, |
| 7736 | as explained at the top of this document. |
| 7737 | |
| 7738 | The inactivity timeout applies when the server is expected to acknowledge or |
| 7739 | send data. In HTTP mode, this timeout is particularly important to consider |
| 7740 | during the first phase of the server's response, when it has to send the |
| 7741 | headers, as it directly represents the server's processing time for the |
| 7742 | request. To find out what value to put there, it's often good to start with |
| 7743 | what would be considered as unacceptable response times, then check the logs |
| 7744 | to observe the response time distribution, and adjust the value accordingly. |
| 7745 | |
| 7746 | The value is specified in milliseconds by default, but can be in any other |
| 7747 | unit if the number is suffixed by the unit, as specified at the top of this |
| 7748 | document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly |
| 7749 | recommended that the client timeout remains equal to the server timeout in |
| 7750 | order to avoid complex situations to debug. Whatever the expected server |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 7751 | response times, it is a good practice to cover at least one or several TCP |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7752 | packet losses by specifying timeouts that are slightly above multiples of 3 |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7753 | seconds (eg: 4 or 5 seconds minimum). If some long-lived sessions are mixed |
| 7754 | with short-lived sessions (eg: WebSocket and HTTP), it's worth considering |
| 7755 | "timeout tunnel", which overrides "timeout client" and "timeout server" for |
| 7756 | tunnels. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7757 | |
| 7758 | This parameter is specific to backends, but can be specified once for all in |
| 7759 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 7760 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 7761 | is not recommended. Such a usage is accepted and works but reports a warning |
| 7762 | during startup because it may results in accumulation of expired sessions in |
| 7763 | the system if the system's timeouts are not configured either. |
| 7764 | |
| 7765 | This parameter replaces the old, deprecated "srvtimeout". It is recommended |
| 7766 | to use it to write new configurations. The form "timeout srvtimeout" is |
| 7767 | provided only by backwards compatibility but its use is strongly discouraged. |
| 7768 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7769 | See also : "srvtimeout", "timeout client" and "timeout tunnel". |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7770 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 7771 | |
| 7772 | timeout server-fin <timeout> |
| 7773 | Set the inactivity timeout on the server side for half-closed connections. |
| 7774 | May be used in sections : defaults | frontend | listen | backend |
| 7775 | yes | no | yes | yes |
| 7776 | Arguments : |
| 7777 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7778 | can be in any other unit if the number is suffixed by the unit, |
| 7779 | as explained at the top of this document. |
| 7780 | |
| 7781 | The inactivity timeout applies when the server is expected to acknowledge or |
| 7782 | send data while one direction is already shut down. This timeout is different |
| 7783 | from "timeout server" in that it only applies to connections which are closed |
| 7784 | in one direction. This is particularly useful to avoid keeping connections in |
| 7785 | FIN_WAIT state for too long when a remote server does not disconnect cleanly. |
| 7786 | This problem is particularly common long connections such as RDP or WebSocket. |
| 7787 | Note that this timeout can override "timeout tunnel" when a connection shuts |
| 7788 | down in one direction. This setting was provided for completeness, but in most |
| 7789 | situations, it should not be needed. |
| 7790 | |
| 7791 | This parameter is specific to backends, but can be specified once for all in |
| 7792 | "defaults" sections. By default it is not set, so half-closed connections |
| 7793 | will use the other timeouts (timeout.server or timeout.tunnel). |
| 7794 | |
| 7795 | See also : "timeout client-fin", "timeout server", and "timeout tunnel". |
| 7796 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7797 | |
| 7798 | timeout tarpit <timeout> |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 7799 | Set the duration for which tarpitted connections will be maintained |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7800 | May be used in sections : defaults | frontend | listen | backend |
| 7801 | yes | yes | yes | yes |
| 7802 | Arguments : |
| 7803 | <timeout> is the tarpit duration specified in milliseconds by default, but |
| 7804 | can be in any other unit if the number is suffixed by the unit, |
| 7805 | as explained at the top of this document. |
| 7806 | |
| 7807 | When a connection is tarpitted using "reqtarpit", it is maintained open with |
| 7808 | no activity for a certain amount of time, then closed. "timeout tarpit" |
| 7809 | defines how long it will be maintained open. |
| 7810 | |
| 7811 | The value is specified in milliseconds by default, but can be in any other |
| 7812 | unit if the number is suffixed by the unit, as specified at the top of this |
| 7813 | document. If unspecified, the same value as the backend's connection timeout |
| 7814 | ("timeout connect") is used, for backwards compatibility with older versions |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 7815 | with no "timeout tarpit" parameter. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7816 | |
| 7817 | See also : "timeout connect", "contimeout". |
| 7818 | |
| 7819 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7820 | timeout tunnel <timeout> |
| 7821 | Set the maximum inactivity time on the client and server side for tunnels. |
| 7822 | May be used in sections : defaults | frontend | listen | backend |
| 7823 | yes | no | yes | yes |
| 7824 | Arguments : |
| 7825 | <timeout> is the timeout value specified in milliseconds by default, but |
| 7826 | can be in any other unit if the number is suffixed by the unit, |
| 7827 | as explained at the top of this document. |
| 7828 | |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 7829 | The tunnel timeout applies when a bidirectional connection is established |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7830 | between a client and a server, and the connection remains inactive in both |
| 7831 | directions. This timeout supersedes both the client and server timeouts once |
| 7832 | the connection becomes a tunnel. In TCP, this timeout is used as soon as no |
| 7833 | analyser remains attached to either connection (eg: tcp content rules are |
| 7834 | accepted). In HTTP, this timeout is used when a connection is upgraded (eg: |
| 7835 | when switching to the WebSocket protocol, or forwarding a CONNECT request |
| 7836 | to a proxy), or after the first response when no keepalive/close option is |
| 7837 | specified. |
| 7838 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 7839 | Since this timeout is usually used in conjunction with long-lived connections, |
| 7840 | it usually is a good idea to also set "timeout client-fin" to handle the |
| 7841 | situation where a client suddenly disappears from the net and does not |
| 7842 | acknowledge a close, or sends a shutdown and does not acknowledge pending |
| 7843 | data anymore. This can happen in lossy networks where firewalls are present, |
| 7844 | and is detected by the presence of large amounts of sessions in a FIN_WAIT |
| 7845 | state. |
| 7846 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7847 | The value is specified in milliseconds by default, but can be in any other |
| 7848 | unit if the number is suffixed by the unit, as specified at the top of this |
| 7849 | document. Whatever the expected normal idle time, it is a good practice to |
| 7850 | cover at least one or several TCP packet losses by specifying timeouts that |
| 7851 | are slightly above multiples of 3 seconds (eg: 4 or 5 seconds minimum). |
| 7852 | |
| 7853 | This parameter is specific to backends, but can be specified once for all in |
| 7854 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 7855 | forget about it. |
| 7856 | |
| 7857 | Example : |
| 7858 | defaults http |
| 7859 | option http-server-close |
| 7860 | timeout connect 5s |
| 7861 | timeout client 30s |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 7862 | timeout client-fin 30s |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7863 | timeout server 30s |
| 7864 | timeout tunnel 1h # timeout to use with WebSocket and CONNECT |
| 7865 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame^] | 7866 | See also : "timeout client", "timeout client-fin", "timeout server". |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 7867 | |
| 7868 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7869 | transparent (deprecated) |
| 7870 | Enable client-side transparent proxying |
| 7871 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 4b1f859 | 2008-12-23 23:13:55 +0100 | [diff] [blame] | 7872 | yes | no | yes | yes |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7873 | Arguments : none |
| 7874 | |
| 7875 | This keyword was introduced in order to provide layer 7 persistence to layer |
| 7876 | 3 load balancers. The idea is to use the OS's ability to redirect an incoming |
| 7877 | connection for a remote address to a local process (here HAProxy), and let |
| 7878 | this process know what address was initially requested. When this option is |
| 7879 | used, sessions without cookies will be forwarded to the original destination |
| 7880 | IP address of the incoming request (which should match that of another |
| 7881 | equipment), while requests with cookies will still be forwarded to the |
| 7882 | appropriate server. |
| 7883 | |
| 7884 | The "transparent" keyword is deprecated, use "option transparent" instead. |
| 7885 | |
| 7886 | Note that contrary to a common belief, this option does NOT make HAProxy |
| 7887 | present the client's IP to the server when establishing the connection. |
| 7888 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7889 | See also: "option transparent" |
| 7890 | |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7891 | unique-id-format <string> |
| 7892 | Generate a unique ID for each request. |
| 7893 | May be used in sections : defaults | frontend | listen | backend |
| 7894 | yes | yes | yes | no |
| 7895 | Arguments : |
| 7896 | <string> is a log-format string. |
| 7897 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7898 | This keyword creates a ID for each request using the custom log format. A |
| 7899 | unique ID is useful to trace a request passing through many components of |
| 7900 | a complex infrastructure. The newly created ID may also be logged using the |
| 7901 | %ID tag the log-format string. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7902 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7903 | The format should be composed from elements that are guaranteed to be |
| 7904 | unique when combined together. For instance, if multiple haproxy instances |
| 7905 | are involved, it might be important to include the node name. It is often |
| 7906 | needed to log the incoming connection's source and destination addresses |
| 7907 | and ports. Note that since multiple requests may be performed over the same |
| 7908 | connection, including a request counter may help differentiate them. |
| 7909 | Similarly, a timestamp may protect against a rollover of the counter. |
| 7910 | Logging the process ID will avoid collisions after a service restart. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7911 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7912 | It is recommended to use hexadecimal notation for many fields since it |
| 7913 | makes them more compact and saves space in logs. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7914 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7915 | Example: |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7916 | |
Julien Vehent | f21be32 | 2014-03-07 08:27:34 -0500 | [diff] [blame] | 7917 | unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7918 | |
| 7919 | will generate: |
| 7920 | |
| 7921 | 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A |
| 7922 | |
| 7923 | See also: "unique-id-header" |
| 7924 | |
| 7925 | unique-id-header <name> |
| 7926 | Add a unique ID header in the HTTP request. |
| 7927 | May be used in sections : defaults | frontend | listen | backend |
| 7928 | yes | yes | yes | no |
| 7929 | Arguments : |
| 7930 | <name> is the name of the header. |
| 7931 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7932 | Add a unique-id header in the HTTP request sent to the server, using the |
| 7933 | unique-id-format. It can't work if the unique-id-format doesn't exist. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7934 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7935 | Example: |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7936 | |
Julien Vehent | f21be32 | 2014-03-07 08:27:34 -0500 | [diff] [blame] | 7937 | unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 7938 | unique-id-header X-Unique-ID |
| 7939 | |
| 7940 | will generate: |
| 7941 | |
| 7942 | X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A |
| 7943 | |
| 7944 | See also: "unique-id-format" |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7945 | |
Willy Tarreau | f51658d | 2014-04-23 01:21:56 +0200 | [diff] [blame] | 7946 | use_backend <backend> [{if | unless} <condition>] |
Willy Tarreau | 1d0dfb1 | 2009-07-07 15:10:31 +0200 | [diff] [blame] | 7947 | Switch to a specific backend if/unless an ACL-based condition is matched. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7948 | May be used in sections : defaults | frontend | listen | backend |
| 7949 | no | yes | yes | no |
| 7950 | Arguments : |
Bertrand Jacquin | 702d44f | 2013-11-19 11:43:06 +0100 | [diff] [blame] | 7951 | <backend> is the name of a valid backend or "listen" section, or a |
| 7952 | "log-format" string resolving to a backend name. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7953 | |
Willy Tarreau | f51658d | 2014-04-23 01:21:56 +0200 | [diff] [blame] | 7954 | <condition> is a condition composed of ACLs, as described in section 7. If |
| 7955 | it is omitted, the rule is unconditionally applied. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7956 | |
| 7957 | When doing content-switching, connections arrive on a frontend and are then |
| 7958 | dispatched to various backends depending on a number of conditions. The |
| 7959 | relation between the conditions and the backends is described with the |
Willy Tarreau | 1d0dfb1 | 2009-07-07 15:10:31 +0200 | [diff] [blame] | 7960 | "use_backend" keyword. While it is normally used with HTTP processing, it can |
| 7961 | also be used in pure TCP, either without content using stateless ACLs (eg: |
| 7962 | source address validation) or combined with a "tcp-request" rule to wait for |
| 7963 | some payload. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 7964 | |
| 7965 | There may be as many "use_backend" rules as desired. All of these rules are |
| 7966 | evaluated in their declaration order, and the first one which matches will |
| 7967 | assign the backend. |
| 7968 | |
| 7969 | In the first form, the backend will be used if the condition is met. In the |
| 7970 | second form, the backend will be used if the condition is not met. If no |
| 7971 | condition is valid, the backend defined with "default_backend" will be used. |
| 7972 | If no default backend is defined, either the servers in the same section are |
| 7973 | used (in case of a "listen" section) or, in case of a frontend, no server is |
| 7974 | used and a 503 service unavailable response is returned. |
| 7975 | |
Willy Tarreau | 51aecc7 | 2009-07-12 09:47:04 +0200 | [diff] [blame] | 7976 | Note that it is possible to switch from a TCP frontend to an HTTP backend. In |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 7977 | this case, either the frontend has already checked that the protocol is HTTP, |
Willy Tarreau | 51aecc7 | 2009-07-12 09:47:04 +0200 | [diff] [blame] | 7978 | and backend processing will immediately follow, or the backend will wait for |
| 7979 | a complete HTTP request to get in. This feature is useful when a frontend |
| 7980 | must decode several protocols on a unique port, one of them being HTTP. |
| 7981 | |
Bertrand Jacquin | 702d44f | 2013-11-19 11:43:06 +0100 | [diff] [blame] | 7982 | When <backend> is a simple name, it is resolved at configuration time, and an |
| 7983 | error is reported if the specified backend does not exist. If <backend> is |
| 7984 | a log-format string instead, no check may be done at configuration time, so |
| 7985 | the backend name is resolved dynamically at run time. If the resulting |
| 7986 | backend name does not correspond to any valid backend, no other rule is |
| 7987 | evaluated, and the default_backend directive is applied instead. Note that |
| 7988 | when using dynamic backend names, it is highly recommended to use a prefix |
| 7989 | that no other backend uses in order to ensure that an unauthorized backend |
| 7990 | cannot be forced from the request. |
| 7991 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 7992 | It is worth mentioning that "use_backend" rules with an explicit name are |
Bertrand Jacquin | 702d44f | 2013-11-19 11:43:06 +0100 | [diff] [blame] | 7993 | used to detect the association between frontends and backends to compute the |
| 7994 | backend's "fullconn" setting. This cannot be done for dynamic names. |
| 7995 | |
| 7996 | See also: "default_backend", "tcp-request", "fullconn", "log-format", and |
| 7997 | section 7 about ACLs. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 7998 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 7999 | |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 8000 | use-server <server> if <condition> |
| 8001 | use-server <server> unless <condition> |
| 8002 | Only use a specific server if/unless an ACL-based condition is matched. |
| 8003 | May be used in sections : defaults | frontend | listen | backend |
| 8004 | no | no | yes | yes |
| 8005 | Arguments : |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 8006 | <server> is the name of a valid server in the same backend section. |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 8007 | |
| 8008 | <condition> is a condition composed of ACLs, as described in section 7. |
| 8009 | |
| 8010 | By default, connections which arrive to a backend are load-balanced across |
| 8011 | the available servers according to the configured algorithm, unless a |
| 8012 | persistence mechanism such as a cookie is used and found in the request. |
| 8013 | |
| 8014 | Sometimes it is desirable to forward a particular request to a specific |
| 8015 | server without having to declare a dedicated backend for this server. This |
| 8016 | can be achieved using the "use-server" rules. These rules are evaluated after |
| 8017 | the "redirect" rules and before evaluating cookies, and they have precedence |
| 8018 | on them. There may be as many "use-server" rules as desired. All of these |
| 8019 | rules are evaluated in their declaration order, and the first one which |
| 8020 | matches will assign the server. |
| 8021 | |
| 8022 | If a rule designates a server which is down, and "option persist" is not used |
| 8023 | and no force-persist rule was validated, it is ignored and evaluation goes on |
| 8024 | with the next rules until one matches. |
| 8025 | |
| 8026 | In the first form, the server will be used if the condition is met. In the |
| 8027 | second form, the server will be used if the condition is not met. If no |
| 8028 | condition is valid, the processing continues and the server will be assigned |
| 8029 | according to other persistence mechanisms. |
| 8030 | |
| 8031 | Note that even if a rule is matched, cookie processing is still performed but |
| 8032 | does not assign the server. This allows prefixed cookies to have their prefix |
| 8033 | stripped. |
| 8034 | |
| 8035 | The "use-server" statement works both in HTTP and TCP mode. This makes it |
| 8036 | suitable for use with content-based inspection. For instance, a server could |
| 8037 | be selected in a farm according to the TLS SNI field. And if these servers |
| 8038 | have their weight set to zero, they will not be used for other traffic. |
| 8039 | |
| 8040 | Example : |
| 8041 | # intercept incoming TLS requests based on the SNI field |
| 8042 | use-server www if { req_ssl_sni -i www.example.com } |
| 8043 | server www 192.168.0.1:443 weight 0 |
| 8044 | use-server mail if { req_ssl_sni -i mail.example.com } |
| 8045 | server mail 192.168.0.1:587 weight 0 |
| 8046 | use-server imap if { req_ssl_sni -i imap.example.com } |
| 8047 | server mail 192.168.0.1:993 weight 0 |
| 8048 | # all the rest is forwarded to this server |
| 8049 | server default 192.168.0.2:443 check |
| 8050 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8051 | See also: "use_backend", section 5 about server and section 7 about ACLs. |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 8052 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8053 | |
| 8054 | 5. Bind and Server options |
| 8055 | -------------------------- |
| 8056 | |
| 8057 | The "bind", "server" and "default-server" keywords support a number of settings |
| 8058 | depending on some build options and on the system HAProxy was built on. These |
| 8059 | settings generally each consist in one word sometimes followed by a value, |
| 8060 | written on the same line as the "bind" or "server" line. All these options are |
| 8061 | described in this section. |
| 8062 | |
| 8063 | |
| 8064 | 5.1. Bind options |
| 8065 | ----------------- |
| 8066 | |
| 8067 | The "bind" keyword supports a certain number of settings which are all passed |
| 8068 | as arguments on the same line. The order in which those arguments appear makes |
| 8069 | no importance, provided that they appear after the bind address. All of these |
| 8070 | parameters are optional. Some of them consist in a single words (booleans), |
| 8071 | while other ones expect a value after them. In this case, the value must be |
| 8072 | provided immediately after the setting name. |
| 8073 | |
| 8074 | The currently supported settings are the following ones. |
| 8075 | |
| 8076 | accept-proxy |
| 8077 | Enforces the use of the PROXY protocol over any connection accepted by any of |
| 8078 | the sockets declared on the same line. The PROXY protocol dictates the layer |
| 8079 | 3/4 addresses of the incoming connection to be used everywhere an address is |
| 8080 | used, with the only exception of "tcp-request connection" rules which will |
| 8081 | only see the real connection address. Logs will reflect the addresses |
| 8082 | indicated in the protocol, unless it is violated, in which case the real |
| 8083 | address will still be used. This keyword combined with support from external |
| 8084 | components can be used as an efficient and reliable alternative to the |
| 8085 | X-Forwarded-For mechanism which is not always reliable and not even always |
Willy Tarreau | 4f0d919 | 2013-06-11 20:40:55 +0200 | [diff] [blame] | 8086 | usable. See also "tcp-request connection expect-proxy" for a finer-grained |
| 8087 | setting of which client is allowed to use the protocol. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8088 | |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 8089 | alpn <protocols> |
| 8090 | This enables the TLS ALPN extension and advertises the specified protocol |
| 8091 | list as supported on top of ALPN. The protocol list consists in a comma- |
| 8092 | delimited list of protocol names, for instance: "http/1.1,http/1.0" (without |
| 8093 | quotes). This requires that the SSL library is build with support for TLS |
| 8094 | extensions enabled (check with haproxy -vv). The ALPN extension replaces the |
| 8095 | initial NPN extension. |
| 8096 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8097 | backlog <backlog> |
| 8098 | Sets the socket's backlog to this value. If unspecified, the frontend's |
| 8099 | backlog is used instead, which generally defaults to the maxconn value. |
| 8100 | |
Emeric Brun | 7fb3442 | 2012-09-28 15:26:15 +0200 | [diff] [blame] | 8101 | ecdhe <named curve> |
| 8102 | This setting is only available when support for OpenSSL was built in. It sets |
Emeric Brun | 6924ef8 | 2013-03-06 14:08:53 +0100 | [diff] [blame] | 8103 | the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default, |
| 8104 | used named curve is prime256v1. |
Emeric Brun | 7fb3442 | 2012-09-28 15:26:15 +0200 | [diff] [blame] | 8105 | |
Emeric Brun | fd33a26 | 2012-10-11 16:28:27 +0200 | [diff] [blame] | 8106 | ca-file <cafile> |
Emeric Brun | 1a073b4 | 2012-09-28 17:07:34 +0200 | [diff] [blame] | 8107 | This setting is only available when support for OpenSSL was built in. It |
| 8108 | designates a PEM file from which to load CA certificates used to verify |
| 8109 | client's certificate. |
| 8110 | |
Emeric Brun | b6dc934 | 2012-09-28 17:55:37 +0200 | [diff] [blame] | 8111 | ca-ignore-err [all|<errorID>,...] |
| 8112 | This setting is only available when support for OpenSSL was built in. |
| 8113 | Sets a comma separated list of errorIDs to ignore during verify at depth > 0. |
| 8114 | If set to 'all', all errors are ignored. SSL handshake is not aborted if an |
| 8115 | error is ignored. |
| 8116 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8117 | ciphers <ciphers> |
| 8118 | This setting is only available when support for OpenSSL was built in. It sets |
| 8119 | the string describing the list of cipher algorithms ("cipher suite") that are |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8120 | negotiated during the SSL/TLS handshake. The format of the string is defined |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8121 | in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string |
| 8122 | such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). |
| 8123 | |
Emeric Brun | fd33a26 | 2012-10-11 16:28:27 +0200 | [diff] [blame] | 8124 | crl-file <crlfile> |
Emeric Brun | 1a073b4 | 2012-09-28 17:07:34 +0200 | [diff] [blame] | 8125 | This setting is only available when support for OpenSSL was built in. It |
| 8126 | designates a PEM file from which to load certificate revocation list used |
| 8127 | to verify client's certificate. |
| 8128 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8129 | crt <cert> |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 8130 | This setting is only available when support for OpenSSL was built in. It |
| 8131 | designates a PEM file containing both the required certificates and any |
| 8132 | associated private keys. This file can be built by concatenating multiple |
| 8133 | PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA |
| 8134 | requires an intermediate certificate, this can also be concatenated into this |
| 8135 | file. |
| 8136 | |
| 8137 | If the OpenSSL used supports Diffie-Hellman, parameters present in this file |
| 8138 | are loaded. |
| 8139 | |
| 8140 | If a directory name is used instead of a PEM file, then all files found in |
| 8141 | that directory will be loaded. This directive may be specified multiple times |
| 8142 | in order to load certificates from multiple files or directories. The |
| 8143 | certificates will be presented to clients who provide a valid TLS Server Name |
| 8144 | Indication field matching one of their CN or alt subjects. Wildcards are |
| 8145 | supported, where a wildcard character '*' is used instead of the first |
| 8146 | hostname component (eg: *.example.org matches www.example.org but not |
| 8147 | www.sub.example.org). |
| 8148 | |
| 8149 | If no SNI is provided by the client or if the SSL library does not support |
| 8150 | TLS extensions, or if the client provides an SNI hostname which does not |
| 8151 | match any certificate, then the first loaded certificate will be presented. |
| 8152 | This means that when loading certificates from a directory, it is highly |
| 8153 | recommended to load the default one first as a file. |
| 8154 | |
Emeric Brun | e032bfa | 2012-09-28 13:01:45 +0200 | [diff] [blame] | 8155 | Note that the same cert may be loaded multiple times without side effects. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8156 | |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 8157 | Some CAs (such as Godaddy) offer a drop down list of server types that do not |
| 8158 | include HAProxy when obtaining a certificate. If this happens be sure to |
Godbach | 8bf60a1 | 2014-04-21 21:42:41 +0800 | [diff] [blame] | 8159 | choose a webserver that the CA believes requires an intermediate CA (for |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 8160 | Godaddy, selection Apache Tomcat will get the correct bundle, but many |
| 8161 | others, e.g. nginx, result in a wrong bundle that will not work for some |
| 8162 | clients). |
| 8163 | |
Emeric Brun | b6dc934 | 2012-09-28 17:55:37 +0200 | [diff] [blame] | 8164 | crt-ignore-err <errors> |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 8165 | This setting is only available when support for OpenSSL was built in. Sets a |
| 8166 | comma separated list of errorIDs to ignore during verify at depth == 0. If |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8167 | set to 'all', all errors are ignored. SSL handshake is not aborted if an error |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 8168 | is ignored. |
Emeric Brun | b6dc934 | 2012-09-28 17:55:37 +0200 | [diff] [blame] | 8169 | |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 8170 | crt-list <file> |
| 8171 | This setting is only available when support for OpenSSL was built in. It |
Emmanuel Hocdet | 7c41a1b | 2013-05-07 20:20:06 +0200 | [diff] [blame] | 8172 | designates a list of PEM file with an optional list of SNI filter per |
| 8173 | certificate, with the following format for each line : |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 8174 | |
Emmanuel Hocdet | 7c41a1b | 2013-05-07 20:20:06 +0200 | [diff] [blame] | 8175 | <crtfile> [[!]<snifilter> ...] |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 8176 | |
Emmanuel Hocdet | 7c41a1b | 2013-05-07 20:20:06 +0200 | [diff] [blame] | 8177 | Wildcards are supported in the SNI filter. Negative filter are also supported, |
| 8178 | only useful in combination with a wildcard filter to exclude a particular SNI. |
| 8179 | The certificates will be presented to clients who provide a valid TLS Server |
| 8180 | Name Indication field matching one of the SNI filters. If no SNI filter is |
| 8181 | specified, the CN and alt subjects are used. This directive may be specified |
| 8182 | multiple times. See the "crt" option for more information. The default |
| 8183 | certificate is still needed to meet OpenSSL expectations. If it is not used, |
| 8184 | the 'strict-sni' option may be used. |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 8185 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8186 | defer-accept |
| 8187 | Is an optional keyword which is supported only on certain Linux kernels. It |
| 8188 | states that a connection will only be accepted once some data arrive on it, |
| 8189 | or at worst after the first retransmit. This should be used only on protocols |
| 8190 | for which the client talks first (eg: HTTP). It can slightly improve |
| 8191 | performance by ensuring that most of the request is already available when |
| 8192 | the connection is accepted. On the other hand, it will not be able to detect |
| 8193 | connections which don't talk. It is important to note that this option is |
| 8194 | broken in all kernels up to 2.6.31, as the connection is never accepted until |
| 8195 | the client talks. This can cause issues with front firewalls which would see |
| 8196 | an established connection while the proxy will only see it in SYN_RECV. This |
| 8197 | option is only supported on TCPv4/TCPv6 sockets and ignored by other ones. |
| 8198 | |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8199 | force-sslv3 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8200 | This option enforces use of SSLv3 only on SSL connections instantiated from |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8201 | this listener. SSLv3 is generally less expensive than the TLS counterparts |
| 8202 | for high connection rates. See also "force-tls*", "no-sslv3", and "no-tls*". |
| 8203 | |
| 8204 | force-tlsv10 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8205 | This option enforces use of TLSv1.0 only on SSL connections instantiated from |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8206 | this listener. See also "force-tls*", "no-sslv3", and "no-tls*". |
| 8207 | |
| 8208 | force-tlsv11 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8209 | This option enforces use of TLSv1.1 only on SSL connections instantiated from |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8210 | this listener. See also "force-tls*", "no-sslv3", and "no-tls*". |
| 8211 | |
| 8212 | force-tlsv12 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8213 | This option enforces use of TLSv1.2 only on SSL connections instantiated from |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8214 | this listener. See also "force-tls*", "no-sslv3", and "no-tls*". |
| 8215 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8216 | gid <gid> |
| 8217 | Sets the group of the UNIX sockets to the designated system gid. It can also |
| 8218 | be set by default in the global section's "unix-bind" statement. Note that |
| 8219 | some platforms simply ignore this. This setting is equivalent to the "group" |
| 8220 | setting except that the group ID is used instead of its name. This setting is |
| 8221 | ignored by non UNIX sockets. |
| 8222 | |
| 8223 | group <group> |
| 8224 | Sets the group of the UNIX sockets to the designated system group. It can |
| 8225 | also be set by default in the global section's "unix-bind" statement. Note |
| 8226 | that some platforms simply ignore this. This setting is equivalent to the |
| 8227 | "gid" setting except that the group name is used instead of its gid. This |
| 8228 | setting is ignored by non UNIX sockets. |
| 8229 | |
| 8230 | id <id> |
| 8231 | Fixes the socket ID. By default, socket IDs are automatically assigned, but |
| 8232 | sometimes it is more convenient to fix them to ease monitoring. This value |
| 8233 | must be strictly positive and unique within the listener/frontend. This |
| 8234 | option can only be used when defining only a single socket. |
| 8235 | |
| 8236 | interface <interface> |
Lukas Tribus | fce2e96 | 2013-02-12 22:13:19 +0100 | [diff] [blame] | 8237 | Restricts the socket to a specific interface. When specified, only packets |
| 8238 | received from that particular interface are processed by the socket. This is |
| 8239 | currently only supported on Linux. The interface must be a primary system |
| 8240 | interface, not an aliased interface. It is also possible to bind multiple |
| 8241 | frontends to the same address if they are bound to different interfaces. Note |
| 8242 | that binding to a network interface requires root privileges. This parameter |
| 8243 | is only compatible with TCPv4/TCPv6 sockets. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8244 | |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 8245 | level <level> |
| 8246 | This setting is used with the stats sockets only to restrict the nature of |
| 8247 | the commands that can be issued on the socket. It is ignored by other |
| 8248 | sockets. <level> can be one of : |
| 8249 | - "user" is the least privileged level ; only non-sensitive stats can be |
| 8250 | read, and no change is allowed. It would make sense on systems where it |
| 8251 | is not easy to restrict access to the socket. |
| 8252 | - "operator" is the default level and fits most common uses. All data can |
| 8253 | be read, and only non-sensitive changes are permitted (eg: clear max |
| 8254 | counters). |
| 8255 | - "admin" should be used with care, as everything is permitted (eg: clear |
| 8256 | all counters). |
| 8257 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8258 | maxconn <maxconn> |
| 8259 | Limits the sockets to this number of concurrent connections. Extraneous |
| 8260 | connections will remain in the system's backlog until a connection is |
| 8261 | released. If unspecified, the limit will be the same as the frontend's |
| 8262 | maxconn. Note that in case of port ranges or multiple addresses, the same |
| 8263 | value will be applied to each socket. This setting enables different |
| 8264 | limitations on expensive sockets, for instance SSL entries which may easily |
| 8265 | eat all memory. |
| 8266 | |
| 8267 | mode <mode> |
| 8268 | Sets the octal mode used to define access permissions on the UNIX socket. It |
| 8269 | can also be set by default in the global section's "unix-bind" statement. |
| 8270 | Note that some platforms simply ignore this. This setting is ignored by non |
| 8271 | UNIX sockets. |
| 8272 | |
| 8273 | mss <maxseg> |
| 8274 | Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming |
| 8275 | connections. This can be used to force a lower MSS for certain specific |
| 8276 | ports, for instance for connections passing through a VPN. Note that this |
| 8277 | relies on a kernel feature which is theoretically supported under Linux but |
| 8278 | was buggy in all versions prior to 2.6.28. It may or may not work on other |
| 8279 | operating systems. It may also not change the advertised value but change the |
| 8280 | effective size of outgoing segments. The commonly advertised value for TCPv4 |
| 8281 | over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is |
| 8282 | positive, it will be used as the advertised MSS. If it is negative, it will |
| 8283 | indicate by how much to reduce the incoming connection's advertised MSS for |
| 8284 | outgoing segments. This parameter is only compatible with TCP v4/v6 sockets. |
| 8285 | |
| 8286 | name <name> |
| 8287 | Sets an optional name for these sockets, which will be reported on the stats |
| 8288 | page. |
| 8289 | |
| 8290 | nice <nice> |
| 8291 | Sets the 'niceness' of connections initiated from the socket. Value must be |
| 8292 | in the range -1024..1024 inclusive, and defaults to zero. Positive values |
| 8293 | means that such connections are more friendly to others and easily offer |
| 8294 | their place in the scheduler. On the opposite, negative values mean that |
| 8295 | connections want to run with a higher priority than others. The difference |
| 8296 | only happens under high loads when the system is close to saturation. |
| 8297 | Negative values are appropriate for low-latency or administration services, |
| 8298 | and high values are generally recommended for CPU intensive tasks such as SSL |
| 8299 | processing or bulk transfers which are less sensible to latency. For example, |
| 8300 | it may make sense to use a positive value for an SMTP socket and a negative |
| 8301 | one for an RDP socket. |
| 8302 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8303 | no-sslv3 |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8304 | This setting is only available when support for OpenSSL was built in. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8305 | disables support for SSLv3 on any sockets instantiated from the listener when |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8306 | SSL is supported. Note that SSLv2 is forced disabled in the code and cannot |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8307 | be enabled using any configuration option. See also "force-tls*", |
| 8308 | and "force-sslv3". |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8309 | |
Emeric Brun | 90ad872 | 2012-10-02 14:00:59 +0200 | [diff] [blame] | 8310 | no-tls-tickets |
| 8311 | This setting is only available when support for OpenSSL was built in. It |
| 8312 | disables the stateless session resumption (RFC 5077 TLS Ticket |
| 8313 | extension) and force to use stateful session resumption. Stateless |
| 8314 | session resumption is more expensive in CPU usage. |
| 8315 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8316 | no-tlsv10 |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8317 | This setting is only available when support for OpenSSL was built in. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8318 | disables support for TLSv1.0 on any sockets instantiated from the listener |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8319 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
| 8320 | cannot be enabled using any configuration option. See also "force-tls*", |
| 8321 | and "force-sslv3". |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8322 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8323 | no-tlsv11 |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8324 | This setting is only available when support for OpenSSL was built in. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8325 | disables support for TLSv1.1 on any sockets instantiated from the listener |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8326 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
| 8327 | cannot be enabled using any configuration option. See also "force-tls*", |
| 8328 | and "force-sslv3". |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8329 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8330 | no-tlsv12 |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8331 | This setting is only available when support for OpenSSL was built in. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8332 | disables support for TLSv1.2 on any sockets instantiated from the listener |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 8333 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
| 8334 | cannot be enabled using any configuration option. See also "force-tls*", |
| 8335 | and "force-sslv3". |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8336 | |
Willy Tarreau | 6c9a3d5 | 2012-10-18 18:57:14 +0200 | [diff] [blame] | 8337 | npn <protocols> |
| 8338 | This enables the NPN TLS extension and advertises the specified protocol list |
| 8339 | as supported on top of NPN. The protocol list consists in a comma-delimited |
| 8340 | list of protocol names, for instance: "http/1.1,http/1.0" (without quotes). |
| 8341 | This requires that the SSL library is build with support for TLS extensions |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 8342 | enabled (check with haproxy -vv). Note that the NPN extension has been |
| 8343 | replaced with the ALPN extension (see the "alpn" keyword). |
Willy Tarreau | 6c9a3d5 | 2012-10-18 18:57:14 +0200 | [diff] [blame] | 8344 | |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 8345 | process [ all | odd | even | <number 1-64>[-<number 1-64>] ] |
| 8346 | This restricts the list of processes on which this listener is allowed to |
| 8347 | run. It does not enforce any process but eliminates those which do not match. |
| 8348 | If the frontend uses a "bind-process" setting, the intersection between the |
| 8349 | two is applied. If in the end the listener is not allowed to run on any |
| 8350 | remaining process, a warning is emitted, and the listener will either run on |
| 8351 | the first process of the listener if a single process was specified, or on |
| 8352 | all of its processes if multiple processes were specified. For the unlikely |
Willy Tarreau | ae30253 | 2014-05-07 19:22:24 +0200 | [diff] [blame] | 8353 | case where several ranges are needed, this directive may be repeated. The |
| 8354 | main purpose of this directive is to be used with the stats sockets and have |
| 8355 | one different socket per process. The second purpose is to have multiple bind |
| 8356 | lines sharing the same IP:port but not the same process in a listener, so |
| 8357 | that the system can distribute the incoming connections into multiple queues |
| 8358 | and allow a smoother inter-process load balancing. Currently Linux 3.9 and |
| 8359 | above is known for supporting this. See also "bind-process" and "nbproc". |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 8360 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8361 | ssl |
| 8362 | This setting is only available when support for OpenSSL was built in. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8363 | enables SSL deciphering on connections instantiated from this listener. A |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8364 | certificate is necessary (see "crt" above). All contents in the buffers will |
| 8365 | appear in clear text, so that ACLs and HTTP processing will only have access |
| 8366 | to deciphered contents. |
| 8367 | |
Emmanuel Hocdet | 6562337 | 2013-01-24 17:17:15 +0100 | [diff] [blame] | 8368 | strict-sni |
| 8369 | This setting is only available when support for OpenSSL was built in. The |
| 8370 | SSL/TLS negotiation is allow only if the client provided an SNI which match |
| 8371 | a certificate. The default certificate is not used. |
| 8372 | See the "crt" option for more information. |
| 8373 | |
Willy Tarreau | 1c862c5 | 2012-10-05 16:21:00 +0200 | [diff] [blame] | 8374 | tfo |
Lukas Tribus | 0defb90 | 2013-02-13 23:35:39 +0100 | [diff] [blame] | 8375 | Is an optional keyword which is supported only on Linux kernels >= 3.7. It |
Willy Tarreau | 1c862c5 | 2012-10-05 16:21:00 +0200 | [diff] [blame] | 8376 | enables TCP Fast Open on the listening socket, which means that clients which |
| 8377 | support this feature will be able to send a request and receive a response |
| 8378 | during the 3-way handshake starting from second connection, thus saving one |
| 8379 | round-trip after the first connection. This only makes sense with protocols |
| 8380 | that use high connection rates and where each round trip matters. This can |
| 8381 | possibly cause issues with many firewalls which do not accept data on SYN |
| 8382 | packets, so this option should only be enabled once well tested. This option |
Lukas Tribus | 0999f76 | 2013-04-02 16:43:24 +0200 | [diff] [blame] | 8383 | is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may |
| 8384 | need to build HAProxy with USE_TFO=1 if your libc doesn't define |
| 8385 | TCP_FASTOPEN. |
Willy Tarreau | 1c862c5 | 2012-10-05 16:21:00 +0200 | [diff] [blame] | 8386 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8387 | transparent |
| 8388 | Is an optional keyword which is supported only on certain Linux kernels. It |
| 8389 | indicates that the addresses will be bound even if they do not belong to the |
| 8390 | local machine, and that packets targeting any of these addresses will be |
| 8391 | intercepted just as if the addresses were locally configured. This normally |
| 8392 | requires that IP forwarding is enabled. Caution! do not use this with the |
| 8393 | default address '*', as it would redirect any traffic for the specified port. |
| 8394 | This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1. |
| 8395 | This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on |
| 8396 | kernel version. Some distribution kernels include backports of the feature, |
| 8397 | so check for support with your vendor. |
| 8398 | |
Willy Tarreau | 77e3af9 | 2012-11-24 15:07:23 +0100 | [diff] [blame] | 8399 | v4v6 |
| 8400 | Is an optional keyword which is supported only on most recent systems |
| 8401 | including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4 |
| 8402 | and IPv6 when it uses the default address. Doing so is sometimes necessary |
| 8403 | on systems which bind to IPv6 only by default. It has no effect on non-IPv6 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8404 | sockets, and is overridden by the "v6only" option. |
Willy Tarreau | 77e3af9 | 2012-11-24 15:07:23 +0100 | [diff] [blame] | 8405 | |
Willy Tarreau | 9b6700f | 2012-11-24 11:55:28 +0100 | [diff] [blame] | 8406 | v6only |
| 8407 | Is an optional keyword which is supported only on most recent systems |
| 8408 | including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only |
| 8409 | when it uses the default address. Doing so is sometimes preferred to doing it |
Willy Tarreau | 77e3af9 | 2012-11-24 15:07:23 +0100 | [diff] [blame] | 8410 | system-wide as it is per-listener. It has no effect on non-IPv6 sockets and |
| 8411 | has precedence over the "v4v6" option. |
Willy Tarreau | 9b6700f | 2012-11-24 11:55:28 +0100 | [diff] [blame] | 8412 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8413 | uid <uid> |
| 8414 | Sets the owner of the UNIX sockets to the designated system uid. It can also |
| 8415 | be set by default in the global section's "unix-bind" statement. Note that |
| 8416 | some platforms simply ignore this. This setting is equivalent to the "user" |
| 8417 | setting except that the user numeric ID is used instead of its name. This |
| 8418 | setting is ignored by non UNIX sockets. |
| 8419 | |
| 8420 | user <user> |
| 8421 | Sets the owner of the UNIX sockets to the designated system user. It can also |
| 8422 | be set by default in the global section's "unix-bind" statement. Note that |
| 8423 | some platforms simply ignore this. This setting is equivalent to the "uid" |
| 8424 | setting except that the user name is used instead of its uid. This setting is |
| 8425 | ignored by non UNIX sockets. |
| 8426 | |
Emeric Brun | 1a073b4 | 2012-09-28 17:07:34 +0200 | [diff] [blame] | 8427 | verify [none|optional|required] |
| 8428 | This setting is only available when support for OpenSSL was built in. If set |
| 8429 | to 'none', client certificate is not requested. This is the default. In other |
| 8430 | cases, a client certificate is requested. If the client does not provide a |
| 8431 | certificate after the request and if 'verify' is set to 'required', then the |
| 8432 | handshake is aborted, while it would have succeeded if set to 'optional'. The |
Emeric Brun | fd33a26 | 2012-10-11 16:28:27 +0200 | [diff] [blame] | 8433 | certificate provided by the client is always verified using CAs from |
| 8434 | 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake |
| 8435 | is aborted, regardless of the 'verify' option, unless the error code exactly |
| 8436 | matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'. |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 8437 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 8438 | 5.2. Server and default-server options |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 8439 | ------------------------------------ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8440 | |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 8441 | The "server" and "default-server" keywords support a certain number of settings |
| 8442 | which are all passed as arguments on the server line. The order in which those |
| 8443 | arguments appear does not count, and they are all optional. Some of those |
| 8444 | settings are single words (booleans) while others expect one or several values |
| 8445 | after them. In this case, the values must immediately follow the setting name. |
| 8446 | Except default-server, all those settings must be specified after the server's |
| 8447 | address if they are used: |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8448 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8449 | server <name> <address>[:port] [settings ...] |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 8450 | default-server [settings ...] |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8451 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8452 | The currently supported settings are the following ones. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 8453 | |
Willy Tarreau | ceb4ac9 | 2012-04-28 00:41:46 +0200 | [diff] [blame] | 8454 | addr <ipv4|ipv6> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8455 | Using the "addr" parameter, it becomes possible to use a different IP address |
| 8456 | to send health-checks. On some servers, it may be desirable to dedicate an IP |
| 8457 | address to specific component able to perform complex tests which are more |
| 8458 | suitable to health-checks than the application. This parameter is ignored if |
| 8459 | the "check" parameter is not set. See also the "port" parameter. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8460 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8461 | Supported in default-server: No |
| 8462 | |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 8463 | agent-check |
| 8464 | Enable an auxiliary agent check which is run independently of a regular |
| 8465 | health check. An agent health check is performed by making a TCP |
| 8466 | connection to the port set by the "agent-port" parameter" and reading |
| 8467 | an ASCII string. The string should have one of the following forms: |
| 8468 | |
| 8469 | * An ASCII representation of an positive integer percentage. |
| 8470 | e.g. "75%" |
| 8471 | |
| 8472 | Values in this format will set the weight proportional to the initial |
| 8473 | weight of a server as configured when haproxy starts. |
| 8474 | |
| 8475 | * The string "drain". |
| 8476 | |
| 8477 | This will cause the weight of a server to be set to 0, and thus it will |
| 8478 | not accept any new connections other than those that are accepted via |
| 8479 | persistence. |
| 8480 | |
| 8481 | * The string "down", optionally followed by a description string. |
| 8482 | |
| 8483 | Mark the server as down and log the description string as the reason. |
| 8484 | |
| 8485 | * The string "stopped", optionally followed by a description string. |
| 8486 | |
| 8487 | This currently has the same behaviour as "down". |
| 8488 | |
| 8489 | * The string "fail", optionally followed by a description string. |
| 8490 | |
| 8491 | This currently has the same behaviour as "down". |
| 8492 | |
Simon Horman | 2f1f955 | 2013-11-25 10:46:37 +0900 | [diff] [blame] | 8493 | Failure to connect to the agent is not considered an error as connectivity |
| 8494 | is tested by the regular health check which is enabled by the "check" |
| 8495 | parameter. |
| 8496 | |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 8497 | Requires the ""agent-port" parameter to be set. |
| 8498 | See also the "agent-check" parameter. |
| 8499 | |
| 8500 | Supported in default-server: No |
| 8501 | |
| 8502 | agent-inter <delay> |
| 8503 | The "agent-inter" parameter sets the interval between two agent checks |
| 8504 | to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms. |
| 8505 | |
| 8506 | Just as with every other time-based parameter, it may be entered in any |
| 8507 | other explicit unit among { us, ms, s, m, h, d }. The "agent-inter" |
| 8508 | parameter also serves as a timeout for agent checks "timeout check" is |
| 8509 | not set. In order to reduce "resonance" effects when multiple servers are |
| 8510 | hosted on the same hardware, the agent and health checks of all servers |
| 8511 | are started with a small time offset between them. It is also possible to |
| 8512 | add some random noise in the agent and health checks interval using the |
| 8513 | global "spread-checks" keyword. This makes sense for instance when a lot |
| 8514 | of backends use the same servers. |
| 8515 | |
| 8516 | See also the "agent-check" and "agent-port" parameters. |
| 8517 | |
| 8518 | Supported in default-server: Yes |
| 8519 | |
| 8520 | agent-port <port> |
| 8521 | The "agent-port" parameter sets the TCP port used for agent checks. |
| 8522 | |
| 8523 | See also the "agent-check" and "agent-inter" parameters. |
| 8524 | |
| 8525 | Supported in default-server: Yes |
| 8526 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8527 | backup |
| 8528 | When "backup" is present on a server line, the server is only used in load |
| 8529 | balancing when all other non-backup servers are unavailable. Requests coming |
| 8530 | with a persistence cookie referencing the server will always be served |
| 8531 | though. By default, only the first operational backup server is used, unless |
| 8532 | the "allbackups" option is set in the backend. See also the "allbackups" |
| 8533 | option. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8534 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8535 | Supported in default-server: No |
| 8536 | |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 8537 | ca-file <cafile> |
| 8538 | This setting is only available when support for OpenSSL was built in. It |
| 8539 | designates a PEM file from which to load CA certificates used to verify |
| 8540 | server's certificate. |
| 8541 | |
| 8542 | Supported in default-server: No |
| 8543 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8544 | check |
| 8545 | This option enables health checks on the server. By default, a server is |
Patrick Mézard | b7aeec6 | 2012-01-22 16:01:22 +0100 | [diff] [blame] | 8546 | always considered available. If "check" is set, the server is available when |
| 8547 | accepting periodic TCP connections, to ensure that it is really able to serve |
| 8548 | requests. The default address and port to send the tests to are those of the |
| 8549 | server, and the default source is the same as the one defined in the |
| 8550 | backend. It is possible to change the address using the "addr" parameter, the |
| 8551 | port using the "port" parameter, the source address using the "source" |
| 8552 | address, and the interval and timers using the "inter", "rise" and "fall" |
Simon Horman | afc47ee | 2013-11-25 10:46:35 +0900 | [diff] [blame] | 8553 | parameters. The request method is define in the backend using the "httpchk", |
| 8554 | "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please |
| 8555 | refer to those options and parameters for more information. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8556 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8557 | Supported in default-server: No |
| 8558 | |
Willy Tarreau | 6c16adc | 2012-10-05 00:04:16 +0200 | [diff] [blame] | 8559 | check-send-proxy |
| 8560 | This option forces emission of a PROXY protocol line with outgoing health |
| 8561 | checks, regardless of whether the server uses send-proxy or not for the |
| 8562 | normal traffic. By default, the PROXY protocol is enabled for health checks |
| 8563 | if it is already enabled for normal traffic and if no "port" nor "addr" |
| 8564 | directive is present. However, if such a directive is present, the |
| 8565 | "check-send-proxy" option needs to be used to force the use of the |
| 8566 | protocol. See also the "send-proxy" option for more information. |
| 8567 | |
| 8568 | Supported in default-server: No |
| 8569 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8570 | check-ssl |
| 8571 | This option forces encryption of all health checks over SSL, regardless of |
| 8572 | whether the server uses SSL or not for the normal traffic. This is generally |
| 8573 | used when an explicit "port" or "addr" directive is specified and SSL health |
| 8574 | checks are not inherited. It is important to understand that this option |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8575 | inserts an SSL transport layer below the checks, so that a simple TCP connect |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8576 | check becomes an SSL connect, which replaces the old ssl-hello-chk. The most |
| 8577 | common use is to send HTTPS checks by combining "httpchk" with SSL checks. |
| 8578 | All SSL settings are common to health checks and traffic (eg: ciphers). |
| 8579 | See the "ssl" option for more information. |
| 8580 | |
| 8581 | Supported in default-server: No |
| 8582 | |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8583 | ciphers <ciphers> |
| 8584 | This option sets the string describing the list of cipher algorithms that is |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8585 | is negotiated during the SSL/TLS handshake with the server. The format of the |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8586 | string is defined in "man 1 ciphers". When SSL is used to communicate with |
| 8587 | servers on the local network, it is common to see a weaker set of algorithms |
| 8588 | than what is used over the internet. Doing so reduces CPU usage on both the |
| 8589 | server and haproxy while still keeping it compatible with deployed software. |
| 8590 | Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all |
| 8591 | is needed and just connectivity, using DES can be appropriate. |
| 8592 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8593 | Supported in default-server: No |
| 8594 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8595 | cookie <value> |
| 8596 | The "cookie" parameter sets the cookie value assigned to the server to |
| 8597 | <value>. This value will be checked in incoming requests, and the first |
| 8598 | operational server possessing the same value will be selected. In return, in |
| 8599 | cookie insertion or rewrite modes, this value will be assigned to the cookie |
| 8600 | sent to the client. There is nothing wrong in having several servers sharing |
| 8601 | the same cookie value, and it is in fact somewhat common between normal and |
| 8602 | backup servers. See also the "cookie" keyword in backend section. |
| 8603 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8604 | Supported in default-server: No |
| 8605 | |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 8606 | crl-file <crlfile> |
| 8607 | This setting is only available when support for OpenSSL was built in. It |
| 8608 | designates a PEM file from which to load certificate revocation list used |
| 8609 | to verify server's certificate. |
| 8610 | |
| 8611 | Supported in default-server: No |
| 8612 | |
Emeric Brun | a7aa309 | 2012-10-26 12:58:00 +0200 | [diff] [blame] | 8613 | crt <cert> |
| 8614 | This setting is only available when support for OpenSSL was built in. |
| 8615 | It designates a PEM file from which to load both a certificate and the |
| 8616 | associated private key. This file can be built by concatenating both PEM |
| 8617 | files into one. This certificate will be sent if the server send a client |
| 8618 | certificate request. |
| 8619 | |
| 8620 | Supported in default-server: No |
| 8621 | |
Willy Tarreau | 9683909 | 2010-03-29 10:02:24 +0200 | [diff] [blame] | 8622 | disabled |
| 8623 | The "disabled" keyword starts the server in the "disabled" state. That means |
| 8624 | that it is marked down in maintenance mode, and no connection other than the |
| 8625 | ones allowed by persist mode will reach it. It is very well suited to setup |
| 8626 | new servers, because normal traffic will never reach them, while it is still |
| 8627 | possible to test the service by making use of the force-persist mechanism. |
| 8628 | |
| 8629 | Supported in default-server: No |
| 8630 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8631 | error-limit <count> |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 8632 | If health observing is enabled, the "error-limit" parameter specifies the |
| 8633 | number of consecutive errors that triggers event selected by the "on-error" |
| 8634 | option. By default it is set to 10 consecutive errors. |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8635 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8636 | Supported in default-server: Yes |
| 8637 | |
| 8638 | See also the "check", "error-limit" and "on-error". |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8639 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8640 | fall <count> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8641 | The "fall" parameter states that a server will be considered as dead after |
| 8642 | <count> consecutive unsuccessful health checks. This value defaults to 3 if |
| 8643 | unspecified. See also the "check", "inter" and "rise" parameters. |
| 8644 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8645 | Supported in default-server: Yes |
| 8646 | |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8647 | force-sslv3 |
| 8648 | This option enforces use of SSLv3 only when SSL is used to communicate with |
| 8649 | the server. SSLv3 is generally less expensive than the TLS counterparts for |
| 8650 | high connection rates. See also "no-tlsv*", "no-sslv3". |
| 8651 | |
| 8652 | Supported in default-server: No |
| 8653 | |
| 8654 | force-tlsv10 |
| 8655 | This option enforces use of TLSv1.0 only when SSL is used to communicate with |
| 8656 | the server. See also "no-tlsv*", "no-sslv3". |
| 8657 | |
| 8658 | Supported in default-server: No |
| 8659 | |
| 8660 | force-tlsv11 |
| 8661 | This option enforces use of TLSv1.1 only when SSL is used to communicate with |
| 8662 | the server. See also "no-tlsv*", "no-sslv3". |
| 8663 | |
| 8664 | Supported in default-server: No |
| 8665 | |
| 8666 | force-tlsv12 |
| 8667 | This option enforces use of TLSv1.2 only when SSL is used to communicate with |
| 8668 | the server. See also "no-tlsv*", "no-sslv3". |
| 8669 | |
| 8670 | Supported in default-server: No |
| 8671 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8672 | id <value> |
Willy Tarreau | 53fb4ae | 2009-10-04 23:04:08 +0200 | [diff] [blame] | 8673 | Set a persistent ID for the server. This ID must be positive and unique for |
| 8674 | the proxy. An unused ID will automatically be assigned if unset. The first |
| 8675 | assigned value will be 1. This ID is currently only returned in statistics. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8676 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8677 | Supported in default-server: No |
| 8678 | |
| 8679 | inter <delay> |
| 8680 | fastinter <delay> |
| 8681 | downinter <delay> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8682 | The "inter" parameter sets the interval between two consecutive health checks |
| 8683 | to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms. |
| 8684 | It is also possible to use "fastinter" and "downinter" to optimize delays |
| 8685 | between checks depending on the server state : |
| 8686 | |
| 8687 | Server state | Interval used |
| 8688 | ---------------------------------+----------------------------------------- |
| 8689 | UP 100% (non-transitional) | "inter" |
| 8690 | ---------------------------------+----------------------------------------- |
| 8691 | Transitionally UP (going down), | |
| 8692 | Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise. |
| 8693 | or yet unchecked. | |
| 8694 | ---------------------------------+----------------------------------------- |
| 8695 | DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise. |
| 8696 | ---------------------------------+----------------------------------------- |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 8697 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8698 | Just as with every other time-based parameter, they can be entered in any |
| 8699 | other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also |
| 8700 | serves as a timeout for health checks sent to servers if "timeout check" is |
| 8701 | not set. In order to reduce "resonance" effects when multiple servers are |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 8702 | hosted on the same hardware, the agent and health checks of all servers |
| 8703 | are started with a small time offset between them. It is also possible to |
| 8704 | add some random noise in the agent and health checks interval using the |
| 8705 | global "spread-checks" keyword. This makes sense for instance when a lot |
| 8706 | of backends use the same servers. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8707 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8708 | Supported in default-server: Yes |
| 8709 | |
| 8710 | maxconn <maxconn> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8711 | The "maxconn" parameter specifies the maximal number of concurrent |
| 8712 | connections that will be sent to this server. If the number of incoming |
| 8713 | concurrent requests goes higher than this value, they will be queued, waiting |
| 8714 | for a connection to be released. This parameter is very important as it can |
| 8715 | save fragile servers from going down under extreme loads. If a "minconn" |
| 8716 | parameter is specified, the limit becomes dynamic. The default value is "0" |
| 8717 | which means unlimited. See also the "minconn" and "maxqueue" parameters, and |
| 8718 | the backend's "fullconn" keyword. |
| 8719 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8720 | Supported in default-server: Yes |
| 8721 | |
| 8722 | maxqueue <maxqueue> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8723 | The "maxqueue" parameter specifies the maximal number of connections which |
| 8724 | will wait in the queue for this server. If this limit is reached, next |
| 8725 | requests will be redispatched to other servers instead of indefinitely |
| 8726 | waiting to be served. This will break persistence but may allow people to |
| 8727 | quickly re-log in when the server they try to connect to is dying. The |
| 8728 | default value is "0" which means the queue is unlimited. See also the |
| 8729 | "maxconn" and "minconn" parameters. |
| 8730 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8731 | Supported in default-server: Yes |
| 8732 | |
| 8733 | minconn <minconn> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8734 | When the "minconn" parameter is set, the maxconn limit becomes a dynamic |
| 8735 | limit following the backend's load. The server will always accept at least |
| 8736 | <minconn> connections, never more than <maxconn>, and the limit will be on |
| 8737 | the ramp between both values when the backend has less than <fullconn> |
| 8738 | concurrent connections. This makes it possible to limit the load on the |
| 8739 | server during normal loads, but push it further for important loads without |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 8740 | overloading the server during exceptional loads. See also the "maxconn" |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8741 | and "maxqueue" parameters, as well as the "fullconn" backend keyword. |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8742 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8743 | Supported in default-server: Yes |
| 8744 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8745 | no-sslv3 |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8746 | This option disables support for SSLv3 when SSL is used to communicate with |
| 8747 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8748 | using any configuration option. See also "force-sslv3", "force-tlsv*". |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8749 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8750 | Supported in default-server: No |
| 8751 | |
Emeric Brun | f9c5c47 | 2012-10-11 15:28:34 +0200 | [diff] [blame] | 8752 | no-tls-tickets |
| 8753 | This setting is only available when support for OpenSSL was built in. It |
| 8754 | disables the stateless session resumption (RFC 5077 TLS Ticket |
| 8755 | extension) and force to use stateful session resumption. Stateless |
| 8756 | session resumption is more expensive in CPU usage for servers. |
| 8757 | |
| 8758 | Supported in default-server: No |
| 8759 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8760 | no-tlsv10 |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8761 | This option disables support for TLSv1.0 when SSL is used to communicate with |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8762 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 8763 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8764 | often makes sense to disable it when communicating with local servers. See |
| 8765 | also "force-sslv3", "force-tlsv*". |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8766 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8767 | Supported in default-server: No |
| 8768 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8769 | no-tlsv11 |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8770 | This option disables support for TLSv1.1 when SSL is used to communicate with |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8771 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 8772 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8773 | often makes sense to disable it when communicating with local servers. See |
| 8774 | also "force-sslv3", "force-tlsv*". |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 8775 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8776 | Supported in default-server: No |
| 8777 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 8778 | no-tlsv12 |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8779 | This option disables support for TLSv1.2 when SSL is used to communicate with |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8780 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 8781 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 8782 | often makes sense to disable it when communicating with local servers. See |
| 8783 | also "force-sslv3", "force-tlsv*". |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8784 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8785 | Supported in default-server: No |
| 8786 | |
Simon Horman | fa46168 | 2011-06-25 09:39:49 +0900 | [diff] [blame] | 8787 | non-stick |
| 8788 | Never add connections allocated to this sever to a stick-table. |
| 8789 | This may be used in conjunction with backup to ensure that |
| 8790 | stick-table persistence is disabled for backup servers. |
| 8791 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8792 | Supported in default-server: No |
| 8793 | |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8794 | observe <mode> |
| 8795 | This option enables health adjusting based on observing communication with |
| 8796 | the server. By default this functionality is disabled and enabling it also |
| 8797 | requires to enable health checks. There are two supported modes: "layer4" and |
| 8798 | "layer7". In layer4 mode, only successful/unsuccessful tcp connections are |
| 8799 | significant. In layer7, which is only allowed for http proxies, responses |
| 8800 | received from server are verified, like valid/wrong http code, unparsable |
Willy Tarreau | 150d146 | 2012-03-10 08:19:02 +0100 | [diff] [blame] | 8801 | headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505. |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8802 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8803 | Supported in default-server: No |
| 8804 | |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8805 | See also the "check", "on-error" and "error-limit". |
| 8806 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8807 | on-error <mode> |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8808 | Select what should happen when enough consecutive errors are detected. |
| 8809 | Currently, four modes are available: |
| 8810 | - fastinter: force fastinter |
| 8811 | - fail-check: simulate a failed check, also forces fastinter (default) |
| 8812 | - sudden-death: simulate a pre-fatal failed health check, one more failed |
| 8813 | check will mark a server down, forces fastinter |
| 8814 | - mark-down: mark the server immediately down and force fastinter |
| 8815 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8816 | Supported in default-server: Yes |
| 8817 | |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 8818 | See also the "check", "observe" and "error-limit". |
| 8819 | |
Simon Horman | e0d1bfb | 2011-06-21 14:34:58 +0900 | [diff] [blame] | 8820 | on-marked-down <action> |
| 8821 | Modify what occurs when a server is marked down. |
| 8822 | Currently one action is available: |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 8823 | - shutdown-sessions: Shutdown peer sessions. When this setting is enabled, |
| 8824 | all connections to the server are immediately terminated when the server |
| 8825 | goes down. It might be used if the health check detects more complex cases |
| 8826 | than a simple connection status, and long timeouts would cause the service |
| 8827 | to remain unresponsive for too long a time. For instance, a health check |
| 8828 | might detect that a database is stuck and that there's no chance to reuse |
| 8829 | existing connections anymore. Connections killed this way are logged with |
| 8830 | a 'D' termination code (for "Down"). |
Simon Horman | e0d1bfb | 2011-06-21 14:34:58 +0900 | [diff] [blame] | 8831 | |
| 8832 | Actions are disabled by default |
| 8833 | |
| 8834 | Supported in default-server: Yes |
| 8835 | |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 8836 | on-marked-up <action> |
| 8837 | Modify what occurs when a server is marked up. |
| 8838 | Currently one action is available: |
| 8839 | - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is |
| 8840 | done only if the server is not in backup state and if it is not disabled |
| 8841 | (it must have an effective weight > 0). This can be used sometimes to force |
| 8842 | an active server to take all the traffic back after recovery when dealing |
| 8843 | with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble |
| 8844 | than it tries to solve (eg: incomplete transactions), so use this feature |
| 8845 | with extreme care. Sessions killed because a server comes up are logged |
| 8846 | with an 'U' termination code (for "Up"). |
| 8847 | |
| 8848 | Actions are disabled by default |
| 8849 | |
| 8850 | Supported in default-server: Yes |
| 8851 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8852 | port <port> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8853 | Using the "port" parameter, it becomes possible to use a different port to |
| 8854 | send health-checks. On some servers, it may be desirable to dedicate a port |
| 8855 | to a specific component able to perform complex tests which are more suitable |
| 8856 | to health-checks than the application. It is common to run a simple script in |
| 8857 | inetd for instance. This parameter is ignored if the "check" parameter is not |
| 8858 | set. See also the "addr" parameter. |
| 8859 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8860 | Supported in default-server: Yes |
| 8861 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8862 | redir <prefix> |
| 8863 | The "redir" parameter enables the redirection mode for all GET and HEAD |
| 8864 | requests addressing this server. This means that instead of having HAProxy |
| 8865 | forward the request to the server, it will send an "HTTP 302" response with |
| 8866 | the "Location" header composed of this prefix immediately followed by the |
| 8867 | requested URI beginning at the leading '/' of the path component. That means |
| 8868 | that no trailing slash should be used after <prefix>. All invalid requests |
| 8869 | will be rejected, and all non-GET or HEAD requests will be normally served by |
| 8870 | the server. Note that since the response is completely forged, no header |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 8871 | mangling nor cookie insertion is possible in the response. However, cookies in |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8872 | requests are still analysed, making this solution completely usable to direct |
| 8873 | users to a remote location in case of local disaster. Main use consists in |
| 8874 | increasing bandwidth for static servers by having the clients directly |
| 8875 | connect to them. Note: never use a relative location here, it would cause a |
| 8876 | loop between the client and HAProxy! |
| 8877 | |
| 8878 | Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check |
| 8879 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8880 | Supported in default-server: No |
| 8881 | |
| 8882 | rise <count> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8883 | The "rise" parameter states that a server will be considered as operational |
| 8884 | after <count> consecutive successful health checks. This value defaults to 2 |
| 8885 | if unspecified. See also the "check", "inter" and "fall" parameters. |
| 8886 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8887 | Supported in default-server: Yes |
| 8888 | |
Willy Tarreau | 5ab04ec | 2011-03-20 10:32:26 +0100 | [diff] [blame] | 8889 | send-proxy |
| 8890 | The "send-proxy" parameter enforces use of the PROXY protocol over any |
| 8891 | connection established to this server. The PROXY protocol informs the other |
| 8892 | end about the layer 3/4 addresses of the incoming connection, so that it can |
| 8893 | know the client's address or the public address it accessed to, whatever the |
| 8894 | upper layer protocol. For connections accepted by an "accept-proxy" listener, |
| 8895 | the advertised address will be used. Only TCPv4 and TCPv6 address families |
| 8896 | are supported. Other families such as Unix sockets, will report an UNKNOWN |
| 8897 | family. Servers using this option can fully be chained to another instance of |
| 8898 | haproxy listening with an "accept-proxy" setting. This setting must not be |
Willy Tarreau | 6c16adc | 2012-10-05 00:04:16 +0200 | [diff] [blame] | 8899 | used if the server isn't aware of the protocol. When health checks are sent |
| 8900 | to the server, the PROXY protocol is automatically used when this option is |
| 8901 | set, unless there is an explicit "port" or "addr" directive, in which case an |
| 8902 | explicit "check-send-proxy" directive would also be needed to use the PROXY |
| 8903 | protocol. See also the "accept-proxy" option of the "bind" keyword. |
Willy Tarreau | 5ab04ec | 2011-03-20 10:32:26 +0100 | [diff] [blame] | 8904 | |
| 8905 | Supported in default-server: No |
| 8906 | |
David S | afb7683 | 2014-05-08 23:42:08 -0400 | [diff] [blame] | 8907 | send-proxy-v2 |
| 8908 | The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2 |
| 8909 | over any connection established to this server. The PROXY protocol informs |
| 8910 | the other end about the layer 3/4 addresses of the incoming connection, so |
| 8911 | that it can know the client's address or the public address it accessed to, |
| 8912 | whatever the upper layer protocol. This setting must not be used if the |
| 8913 | server isn't aware of this version of the protocol. See also the "send-proxy" |
| 8914 | option of the "bind" keyword. |
| 8915 | |
| 8916 | Supported in default-server: No |
| 8917 | |
| 8918 | send-proxy-v2-ssl |
| 8919 | The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version |
| 8920 | 2 over any connection established to this server. The PROXY protocol informs |
| 8921 | the other end about the layer 3/4 addresses of the incoming connection, so |
| 8922 | that it can know the client's address or the public address it accessed to, |
| 8923 | whatever the upper layer protocol. In addition, the SSL information extension |
| 8924 | of the PROXY protocol is added to the PROXY protocol header. This setting |
| 8925 | must not be used if the server isn't aware of this version of the protocol. |
| 8926 | See also the "send-proxy-v2" option of the "bind" keyword. |
| 8927 | |
| 8928 | Supported in default-server: No |
| 8929 | |
| 8930 | send-proxy-v2-ssl-cn |
| 8931 | The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version |
| 8932 | 2 over any connection established to this server. The PROXY protocol informs |
| 8933 | the other end about the layer 3/4 addresses of the incoming connection, so |
| 8934 | that it can know the client's address or the public address it accessed to, |
| 8935 | whatever the upper layer protocol. In addition, the SSL information extension |
| 8936 | of the PROXY protocol, along along with the Common Name from the subject of |
| 8937 | the client certificate (if any), is added to the PROXY protocol header. This |
| 8938 | setting must not be used if the server isn't aware of this version of the |
| 8939 | protocol. See also the "send-proxy-v2" option of the "bind" keyword. |
| 8940 | |
| 8941 | Supported in default-server: No |
| 8942 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8943 | slowstart <start_time_in_ms> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8944 | The "slowstart" parameter for a server accepts a value in milliseconds which |
| 8945 | indicates after how long a server which has just come back up will run at |
| 8946 | full speed. Just as with every other time-based parameter, it can be entered |
| 8947 | in any other explicit unit among { us, ms, s, m, h, d }. The speed grows |
| 8948 | linearly from 0 to 100% during this time. The limitation applies to two |
| 8949 | parameters : |
| 8950 | |
| 8951 | - maxconn: the number of connections accepted by the server will grow from 1 |
| 8952 | to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn). |
| 8953 | |
| 8954 | - weight: when the backend uses a dynamic weighted algorithm, the weight |
| 8955 | grows linearly from 1 to 100%. In this case, the weight is updated at every |
| 8956 | health-check. For this reason, it is important that the "inter" parameter |
| 8957 | is smaller than the "slowstart", in order to maximize the number of steps. |
| 8958 | |
| 8959 | The slowstart never applies when haproxy starts, otherwise it would cause |
| 8960 | trouble to running servers. It only applies when a server has been previously |
| 8961 | seen as failed. |
| 8962 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8963 | Supported in default-server: Yes |
| 8964 | |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 8965 | source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 8966 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ] |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 8967 | source <addr>[:<pl>[-<ph>]] [interface <name>] ... |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8968 | The "source" parameter sets the source address which will be used when |
| 8969 | connecting to the server. It follows the exact same parameters and principle |
| 8970 | as the backend "source" keyword, except that it only applies to the server |
| 8971 | referencing it. Please consult the "source" keyword for details. |
| 8972 | |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 8973 | Additionally, the "source" statement on a server line allows one to specify a |
| 8974 | source port range by indicating the lower and higher bounds delimited by a |
| 8975 | dash ('-'). Some operating systems might require a valid IP address when a |
| 8976 | source port range is specified. It is permitted to have the same IP/range for |
| 8977 | several servers. Doing so makes it possible to bypass the maximum of 64k |
| 8978 | total concurrent connections. The limit will then reach 64k connections per |
| 8979 | server. |
| 8980 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 8981 | Supported in default-server: No |
| 8982 | |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8983 | ssl |
Willy Tarreau | 44f6539 | 2013-06-25 07:56:20 +0200 | [diff] [blame] | 8984 | This option enables SSL ciphering on outgoing connections to the server. It |
| 8985 | is critical to verify server certificates using "verify" when using SSL to |
| 8986 | connect to servers, otherwise the communication is prone to trivial man in |
| 8987 | the-middle attacks rendering SSL useless. When this option is used, health |
| 8988 | checks are automatically sent in SSL too unless there is a "port" or an |
| 8989 | "addr" directive indicating the check should be sent to a different location. |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 8990 | See the "check-ssl" option to force SSL health checks. |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 8991 | |
| 8992 | Supported in default-server: No |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 8993 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8994 | track [<proxy>/]<server> |
| 8995 | This option enables ability to set the current state of the server by |
| 8996 | tracking another one. Only a server with checks enabled can be tracked |
| 8997 | so it is not possible for example to track a server that tracks another |
| 8998 | one. If <proxy> is omitted the current one is used. If disable-on-404 is |
| 8999 | used, it has to be enabled on both proxies. |
| 9000 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 9001 | Supported in default-server: No |
| 9002 | |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 9003 | verify [none|required] |
| 9004 | This setting is only available when support for OpenSSL was built in. If set |
Emeric Brun | 850efd5 | 2014-01-29 12:24:34 +0100 | [diff] [blame] | 9005 | to 'none', server certificate is not verified. In the other case, The |
| 9006 | certificate provided by the server is verified using CAs from 'ca-file' |
| 9007 | and optional CRLs from 'crl-file'. If 'ssl_server_verify' is not specified |
| 9008 | in global section, this is the default. On verify failure the handshake |
Willy Tarreau | 44f6539 | 2013-06-25 07:56:20 +0200 | [diff] [blame] | 9009 | is aborted. It is critically important to verify server certificates when |
| 9010 | using SSL to connect to servers, otherwise the communication is prone to |
| 9011 | trivial man-in-the-middle attacks rendering SSL totally useless. |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 9012 | |
| 9013 | Supported in default-server: No |
| 9014 | |
Evan Broder | be55431 | 2013-06-27 00:05:25 -0700 | [diff] [blame] | 9015 | verifyhost <hostname> |
| 9016 | This setting is only available when support for OpenSSL was built in, and |
| 9017 | only takes effect if 'verify required' is also specified. When set, the |
| 9018 | hostnames in the subject and subjectAlternateNames of the certificate |
| 9019 | provided by the server are checked. If none of the hostnames in the |
| 9020 | certificate match the specified hostname, the handshake is aborted. The |
| 9021 | hostnames in the server-provided certificate may include wildcards. |
| 9022 | |
| 9023 | Supported in default-server: No |
| 9024 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 9025 | weight <weight> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9026 | The "weight" parameter is used to adjust the server's weight relative to |
| 9027 | other servers. All servers will receive a load proportional to their weight |
| 9028 | relative to the sum of all weights, so the higher the weight, the higher the |
Willy Tarreau | 6704d67 | 2009-06-15 10:56:05 +0200 | [diff] [blame] | 9029 | load. The default weight is 1, and the maximal value is 256. A value of 0 |
| 9030 | means the server will not participate in load-balancing but will still accept |
| 9031 | persistent connections. If this parameter is used to distribute the load |
| 9032 | according to server's capacity, it is recommended to start with values which |
| 9033 | can both grow and shrink, for instance between 10 and 100 to leave enough |
| 9034 | room above and below for later adjustments. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9035 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 9036 | Supported in default-server: Yes |
| 9037 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9038 | |
| 9039 | 6. HTTP header manipulation |
| 9040 | --------------------------- |
| 9041 | |
| 9042 | In HTTP mode, it is possible to rewrite, add or delete some of the request and |
| 9043 | response headers based on regular expressions. It is also possible to block a |
| 9044 | request or a response if a particular header matches a regular expression, |
| 9045 | which is enough to stop most elementary protocol attacks, and to protect |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 9046 | against information leak from the internal network. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9047 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 9048 | If HAProxy encounters an "Informational Response" (status code 1xx), it is able |
| 9049 | to process all rsp* rules which can allow, deny, rewrite or delete a header, |
| 9050 | but it will refuse to add a header to any such messages as this is not |
| 9051 | HTTP-compliant. The reason for still processing headers in such responses is to |
| 9052 | stop and/or fix any possible information leak which may happen, for instance |
| 9053 | because another downstream equipment would unconditionally add a header, or if |
| 9054 | a server name appears there. When such messages are seen, normal processing |
| 9055 | still occurs on the next non-informational messages. |
Willy Tarreau | 816b979 | 2009-09-15 21:25:21 +0200 | [diff] [blame] | 9056 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9057 | This section covers common usage of the following keywords, described in detail |
| 9058 | in section 4.2 : |
| 9059 | |
| 9060 | - reqadd <string> |
| 9061 | - reqallow <search> |
| 9062 | - reqiallow <search> |
| 9063 | - reqdel <search> |
| 9064 | - reqidel <search> |
| 9065 | - reqdeny <search> |
| 9066 | - reqideny <search> |
| 9067 | - reqpass <search> |
| 9068 | - reqipass <search> |
| 9069 | - reqrep <search> <replace> |
| 9070 | - reqirep <search> <replace> |
| 9071 | - reqtarpit <search> |
| 9072 | - reqitarpit <search> |
| 9073 | - rspadd <string> |
| 9074 | - rspdel <search> |
| 9075 | - rspidel <search> |
| 9076 | - rspdeny <search> |
| 9077 | - rspideny <search> |
| 9078 | - rsprep <search> <replace> |
| 9079 | - rspirep <search> <replace> |
| 9080 | |
| 9081 | With all these keywords, the same conventions are used. The <search> parameter |
| 9082 | is a POSIX extended regular expression (regex) which supports grouping through |
| 9083 | parenthesis (without the backslash). Spaces and other delimiters must be |
| 9084 | prefixed with a backslash ('\') to avoid confusion with a field delimiter. |
| 9085 | Other characters may be prefixed with a backslash to change their meaning : |
| 9086 | |
| 9087 | \t for a tab |
| 9088 | \r for a carriage return (CR) |
| 9089 | \n for a new line (LF) |
| 9090 | \ to mark a space and differentiate it from a delimiter |
| 9091 | \# to mark a sharp and differentiate it from a comment |
| 9092 | \\ to use a backslash in a regex |
| 9093 | \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy) |
| 9094 | \xXX to write the ASCII hex code XX as in the C language |
| 9095 | |
| 9096 | The <replace> parameter contains the string to be used to replace the largest |
| 9097 | portion of text matching the regex. It can make use of the special characters |
| 9098 | above, and can reference a substring which is delimited by parenthesis in the |
| 9099 | regex, by writing a backslash ('\') immediately followed by one digit from 0 to |
| 9100 | 9 indicating the group position (0 designating the entire line). This practice |
| 9101 | is very common to users of the "sed" program. |
| 9102 | |
| 9103 | The <string> parameter represents the string which will systematically be added |
| 9104 | after the last header line. It can also use special character sequences above. |
| 9105 | |
| 9106 | Notes related to these keywords : |
| 9107 | --------------------------------- |
| 9108 | - these keywords are not always convenient to allow/deny based on header |
| 9109 | contents. It is strongly recommended to use ACLs with the "block" keyword |
| 9110 | instead, resulting in far more flexible and manageable rules. |
| 9111 | |
| 9112 | - lines are always considered as a whole. It is not possible to reference |
| 9113 | a header name only or a value only. This is important because of the way |
| 9114 | headers are written (notably the number of spaces after the colon). |
| 9115 | |
| 9116 | - the first line is always considered as a header, which makes it possible to |
| 9117 | rewrite or filter HTTP requests URIs or response codes, but in turn makes |
| 9118 | it harder to distinguish between headers and request line. The regex prefix |
| 9119 | ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix |
| 9120 | ^[^ \t:]*: matches any header name followed by a colon. |
| 9121 | |
| 9122 | - for performances reasons, the number of characters added to a request or to |
| 9123 | a response is limited at build time to values between 1 and 4 kB. This |
| 9124 | should normally be far more than enough for most usages. If it is too short |
| 9125 | on occasional usages, it is possible to gain some space by removing some |
| 9126 | useless headers before adding new ones. |
| 9127 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 9128 | - keywords beginning with "reqi" and "rspi" are the same as their counterpart |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9129 | without the 'i' letter except that they ignore case when matching patterns. |
| 9130 | |
| 9131 | - when a request passes through a frontend then a backend, all req* rules |
| 9132 | from the frontend will be evaluated, then all req* rules from the backend |
| 9133 | will be evaluated. The reverse path is applied to responses. |
| 9134 | |
| 9135 | - req* statements are applied after "block" statements, so that "block" is |
| 9136 | always the first one, but before "use_backend" in order to permit rewriting |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 9137 | before switching. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9138 | |
| 9139 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9140 | 7. Using ACLs and fetching samples |
| 9141 | ---------------------------------- |
| 9142 | |
| 9143 | Haproxy is capable of extracting data from request or response streams, from |
| 9144 | client or server information, from tables, environmental information etc... |
| 9145 | The action of extracting such data is called fetching a sample. Once retrieved, |
| 9146 | these samples may be used for various purposes such as a key to a stick-table, |
| 9147 | but most common usages consist in matching them against predefined constant |
| 9148 | data called patterns. |
| 9149 | |
| 9150 | |
| 9151 | 7.1. ACL basics |
| 9152 | --------------- |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9153 | |
| 9154 | The use of Access Control Lists (ACL) provides a flexible solution to perform |
| 9155 | content switching and generally to take decisions based on content extracted |
| 9156 | from the request, the response or any environmental status. The principle is |
| 9157 | simple : |
| 9158 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9159 | - extract a data sample from a stream, table or the environment |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9160 | - optionally apply some format conversion to the extracted sample |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9161 | - apply one or multiple pattern matching methods on this sample |
| 9162 | - perform actions only when a pattern matches the sample |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9163 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9164 | The actions generally consist in blocking a request, selecting a backend, or |
| 9165 | adding a header. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9166 | |
| 9167 | In order to define a test, the "acl" keyword is used. The syntax is : |
| 9168 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9169 | acl <aclname> <criterion> [flags] [operator] [<value>] ... |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9170 | |
| 9171 | This creates a new ACL <aclname> or completes an existing one with new tests. |
| 9172 | Those tests apply to the portion of request/response specified in <criterion> |
| 9173 | and may be adjusted with optional flags [flags]. Some criteria also support |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9174 | an operator which may be specified before the set of values. Optionally some |
| 9175 | conversion operators may be applied to the sample, and they will be specified |
| 9176 | as a comma-delimited list of keywords just after the first keyword. The values |
| 9177 | are of the type supported by the criterion, and are separated by spaces. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9178 | |
| 9179 | ACL names must be formed from upper and lower case letters, digits, '-' (dash), |
| 9180 | '_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive, |
| 9181 | which means that "my_acl" and "My_Acl" are two different ACLs. |
| 9182 | |
| 9183 | There is no enforced limit to the number of ACLs. The unused ones do not affect |
| 9184 | performance, they just consume a small amount of memory. |
| 9185 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9186 | The criterion generally is the name of a sample fetch method, or one of its ACL |
| 9187 | specific declinations. The default test method is implied by the output type of |
| 9188 | this sample fetch method. The ACL declinations can describe alternate matching |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9189 | methods of a same sample fetch method. The sample fetch methods are the only |
| 9190 | ones supporting a conversion. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9191 | |
| 9192 | Sample fetch methods return data which can be of the following types : |
| 9193 | - boolean |
| 9194 | - integer (signed or unsigned) |
| 9195 | - IPv4 or IPv6 address |
| 9196 | - string |
| 9197 | - data block |
| 9198 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9199 | Converters transform any of these data into any of these. For example, some |
| 9200 | converters might convert a string to a lower-case string while other ones |
| 9201 | would turn a string to an IPv4 address, or apply a netmask to an IP address. |
| 9202 | The resulting sample is of the type of the last converter applied to the list, |
| 9203 | which defaults to the type of the sample fetch method. |
| 9204 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9205 | The ACL engine can match these types against patterns of the following types : |
| 9206 | - boolean |
| 9207 | - integer or integer range |
| 9208 | - IP address / network |
| 9209 | - string (exact, substring, suffix, prefix, subdir, domain) |
| 9210 | - regular expression |
| 9211 | - hex block |
| 9212 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9213 | The following ACL flags are currently supported : |
| 9214 | |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 9215 | -i : ignore case during matching of all subsequent patterns. |
| 9216 | -f : load patterns from a file. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9217 | -m : use a specific pattern matching method |
Thierry FOURNIER | b7729c9 | 2014-02-11 16:24:41 +0100 | [diff] [blame] | 9218 | -n : forbid the DNS resolutions |
Thierry FOURNIER | 9860c41 | 2014-01-29 14:23:29 +0100 | [diff] [blame] | 9219 | -M : load the file pointed by -f like a map file. |
Thierry FOURNIER | 3534d88 | 2014-01-20 17:01:44 +0100 | [diff] [blame] | 9220 | -u : force the unique id of the ACL |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9221 | -- : force end of flags. Useful when a string looks like one of the flags. |
| 9222 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9223 | The "-f" flag is followed by the name of a file from which all lines will be |
| 9224 | read as individual values. It is even possible to pass multiple "-f" arguments |
| 9225 | if the patterns are to be loaded from multiple files. Empty lines as well as |
| 9226 | lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs |
| 9227 | will be stripped. If it is absolutely necessary to insert a valid pattern |
| 9228 | beginning with a sharp, just prefix it with a space so that it is not taken for |
| 9229 | a comment. Depending on the data type and match method, haproxy may load the |
| 9230 | lines into a binary tree, allowing very fast lookups. This is true for IPv4 and |
| 9231 | exact string matching. In this case, duplicates will automatically be removed. |
| 9232 | |
Thierry FOURNIER | 9860c41 | 2014-01-29 14:23:29 +0100 | [diff] [blame] | 9233 | The "-M" flag allows an ACL to use a map file. If this flag is set, the file is |
| 9234 | parsed as two column file. The first column contains the patterns used by the |
| 9235 | ACL, and the second column contain the samples. The sample can be used later by |
| 9236 | a map. This can be useful in some rare cases where an ACL would just be used to |
| 9237 | check for the existence of a pattern in a map before a mapping is applied. |
| 9238 | |
Thierry FOURNIER | 3534d88 | 2014-01-20 17:01:44 +0100 | [diff] [blame] | 9239 | The "-u" flag forces the unique id of the ACL. This unique id is used with the |
| 9240 | socket interface to identify ACL and dynamically change its values. Note that a |
| 9241 | file is always identified by its name even if an id is set. |
| 9242 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9243 | Also, note that the "-i" flag applies to subsequent entries and not to entries |
| 9244 | loaded from files preceding it. For instance : |
| 9245 | |
| 9246 | acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test |
| 9247 | |
| 9248 | In this example, each line of "exact-ua.lst" will be exactly matched against |
| 9249 | the "user-agent" header of the request. Then each line of "generic-ua" will be |
| 9250 | case-insensitively matched. Then the word "test" will be insensitively matched |
| 9251 | as well. |
| 9252 | |
| 9253 | The "-m" flag is used to select a specific pattern matching method on the input |
| 9254 | sample. All ACL-specific criteria imply a pattern matching method and generally |
| 9255 | do not need this flag. However, this flag is useful with generic sample fetch |
| 9256 | methods to describe how they're going to be matched against the patterns. This |
| 9257 | is required for sample fetches which return data type for which there is no |
| 9258 | obvious matching method (eg: string or binary). When "-m" is specified and |
| 9259 | followed by a pattern matching method name, this method is used instead of the |
| 9260 | default one for the criterion. This makes it possible to match contents in ways |
| 9261 | that were not initially planned, or with sample fetch methods which return a |
| 9262 | string. The matching method also affects the way the patterns are parsed. |
| 9263 | |
Thierry FOURNIER | b7729c9 | 2014-02-11 16:24:41 +0100 | [diff] [blame] | 9264 | The "-n" flag forbids the dns resolutions. It is used with the load of ip files. |
| 9265 | By default, if the parser cannot parse ip address it considers that the parsed |
| 9266 | string is maybe a domain name and try dns resolution. The flag "-n" disable this |
| 9267 | resolution. It is useful for detecting malformed ip lists. Note that if the DNS |
| 9268 | server is not reachable, the haproxy configuration parsing may last many minutes |
| 9269 | waiting fir the timeout. During this time no error messages are displayed. The |
| 9270 | flag "-n" disable this behavior. Note also that during the runtime, this |
| 9271 | function is disabled for the dynamic acl modifications. |
| 9272 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9273 | There are some restrictions however. Not all methods can be used with all |
| 9274 | sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must |
| 9275 | be placed first. The pattern matching method must be one of the following : |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9276 | |
| 9277 | - "found" : only check if the requested sample could be found in the stream, |
| 9278 | but do not compare it against any pattern. It is recommended not |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9279 | to pass any pattern to avoid confusion. This matching method is |
| 9280 | particularly useful to detect presence of certain contents such |
| 9281 | as headers, cookies, etc... even if they are empty and without |
| 9282 | comparing them to anything nor counting them. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9283 | |
| 9284 | - "bool" : check the value as a boolean. It can only be applied to fetches |
| 9285 | which return a boolean or integer value, and takes no pattern. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9286 | Value zero or false does not match, all other values do match. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9287 | |
| 9288 | - "int" : match the value as an integer. It can be used with integer and |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9289 | boolean samples. Boolean false is integer 0, true is integer 1. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9290 | |
| 9291 | - "ip" : match the value as an IPv4 or IPv6 address. It is compatible |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9292 | with IP address samples only, so it is implied and never needed. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9293 | |
| 9294 | - "bin" : match the contents against an hexadecimal string representing a |
| 9295 | binary sequence. This may be used with binary or string samples. |
| 9296 | |
| 9297 | - "len" : match the sample's length as an integer. This may be used with |
| 9298 | binary or string samples. |
| 9299 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9300 | - "str" : exact match : match the contents against a string. This may be |
| 9301 | used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9302 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9303 | - "sub" : substring match : check that the contents contain at least one of |
| 9304 | the provided string patterns. This may be used with binary or |
| 9305 | string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9306 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9307 | - "reg" : regex match : match the contents against a list of regular |
| 9308 | expressions. This may be used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9309 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9310 | - "beg" : prefix match : check that the contents begin like the provided |
| 9311 | string patterns. This may be used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9312 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9313 | - "end" : suffix match : check that the contents end like the provided |
| 9314 | string patterns. This may be used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9315 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9316 | - "dir" : subdir match : check that a slash-delimited portion of the |
| 9317 | contents exactly matches one of the provided string patterns. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9318 | This may be used with binary or string samples. |
| 9319 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9320 | - "dom" : domain match : check that a dot-delimited portion of the contents |
| 9321 | exactly match one of the provided string patterns. This may be |
| 9322 | used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 9323 | |
| 9324 | For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP |
| 9325 | request, it is possible to do : |
| 9326 | |
| 9327 | acl jsess_present cook(JSESSIONID) -m found |
| 9328 | |
| 9329 | In order to apply a regular expression on the 500 first bytes of data in the |
| 9330 | buffer, one would use the following acl : |
| 9331 | |
| 9332 | acl script_tag payload(0,500) -m reg -i <script> |
| 9333 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9334 | On systems where the regex library is much slower when using "-i", it is |
| 9335 | possible to convert the sample to lowercase before matching, like this : |
| 9336 | |
| 9337 | acl script_tag payload(0,500),lower -m reg <script> |
| 9338 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9339 | All ACL-specific criteria imply a default matching method. Most often, these |
| 9340 | criteria are composed by concatenating the name of the original sample fetch |
| 9341 | method and the matching method. For example, "hdr_beg" applies the "beg" match |
| 9342 | to samples retrieved using the "hdr" fetch method. Since all ACL-specific |
| 9343 | criteria rely on a sample fetch method, it is always possible instead to use |
| 9344 | the original sample fetch method and the explicit matching method using "-m". |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 9345 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9346 | If an alternate match is specified using "-m" on an ACL-specific criterion, |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9347 | the matching method is simply applied to the underlying sample fetch method. |
| 9348 | For example, all ACLs below are exact equivalent : |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 9349 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9350 | acl short_form hdr_beg(host) www. |
| 9351 | acl alternate1 hdr_beg(host) -m beg www. |
| 9352 | acl alternate2 hdr_dom(host) -m beg www. |
| 9353 | acl alternate3 hdr(host) -m beg www. |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 9354 | |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 9355 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9356 | The table below summarizes the compatibility matrix between sample types |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9357 | and the pattern types to fetch against. It indicates for each compatible |
| 9358 | combination the name of the matching method to be used, prefixed with "*" when |
| 9359 | the method is implicit and will work by default without "-m". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9360 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9361 | +-------------------------------------------------+ |
| 9362 | | Input sample type | |
| 9363 | +----------------------+---------+---------+---------+---------+---------+ |
| 9364 | | pattern type | boolean | integer | IP | string | binary | |
| 9365 | +----------------------+---------+---------+---------+---------+---------+ |
| 9366 | | none (presence only) | found | found | found | found | found | |
| 9367 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9368 | | none (boolean value) | *bool | bool | | bool | | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9369 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9370 | | integer (value) | int | *int | int | int | | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9371 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9372 | | integer (length) | len | len | len | len | len | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9373 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9374 | | IP address | | | *ip | ip | ip | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9375 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9376 | | exact string | str | str | str | str | str | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9377 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9378 | | prefix | beg | beg | beg | beg | beg | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9379 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9380 | | suffix | end | end | end | end | end | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9381 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9382 | | substring | sub | sub | sub | sub | sub | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9383 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9384 | | subdir | dir | dir | dir | dir | dir | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9385 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9386 | | domain | dom | dom | dom | dom | dom | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9387 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 9388 | | regex | reg | reg | reg | reg | reg | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9389 | +----------------------+---------+---------+---------+---------+---------+ |
| 9390 | | hex block | | | | bin | bin | |
| 9391 | +----------------------+---------+---------+---------+---------+---------+ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9392 | |
| 9393 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9394 | 7.1.1. Matching booleans |
| 9395 | ------------------------ |
| 9396 | |
| 9397 | In order to match a boolean, no value is needed and all values are ignored. |
| 9398 | Boolean matching is used by default for all fetch methods of type "boolean". |
| 9399 | When boolean matching is used, the fetched value is returned as-is, which means |
| 9400 | that a boolean "true" will always match and a boolean "false" will never match. |
| 9401 | |
| 9402 | Boolean matching may also be enforced using "-m bool" on fetch methods which |
| 9403 | return an integer value. Then, integer value 0 is converted to the boolean |
| 9404 | "false" and all other values are converted to "true". |
| 9405 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9406 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9407 | 7.1.2. Matching integers |
| 9408 | ------------------------ |
| 9409 | |
| 9410 | Integer matching applies by default to integer fetch methods. It can also be |
| 9411 | enforced on boolean fetches using "-m int". In this case, "false" is converted |
| 9412 | to the integer 0, and "true" is converted to the integer 1. |
| 9413 | |
| 9414 | Integer matching also supports integer ranges and operators. Note that integer |
| 9415 | matching only applies to positive values. A range is a value expressed with a |
| 9416 | lower and an upper bound separated with a colon, both of which may be omitted. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9417 | |
| 9418 | For instance, "1024:65535" is a valid range to represent a range of |
| 9419 | unprivileged ports, and "1024:" would also work. "0:1023" is a valid |
| 9420 | representation of privileged ports, and ":1023" would also work. |
| 9421 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 9422 | As a special case, some ACL functions support decimal numbers which are in fact |
| 9423 | two integers separated by a dot. This is used with some version checks for |
| 9424 | instance. All integer properties apply to those decimal numbers, including |
| 9425 | ranges and operators. |
| 9426 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9427 | For an easier usage, comparison operators are also supported. Note that using |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9428 | operators with ranges does not make much sense and is strongly discouraged. |
| 9429 | Similarly, it does not make much sense to perform order comparisons with a set |
| 9430 | of values. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9431 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9432 | Available operators for integer matching are : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9433 | |
| 9434 | eq : true if the tested value equals at least one value |
| 9435 | ge : true if the tested value is greater than or equal to at least one value |
| 9436 | gt : true if the tested value is greater than at least one value |
| 9437 | le : true if the tested value is less than or equal to at least one value |
| 9438 | lt : true if the tested value is less than at least one value |
| 9439 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9440 | For instance, the following ACL matches any negative Content-Length header : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9441 | |
| 9442 | acl negative-length hdr_val(content-length) lt 0 |
| 9443 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 9444 | This one matches SSL versions between 3.0 and 3.1 (inclusive) : |
| 9445 | |
| 9446 | acl sslv3 req_ssl_ver 3:3.1 |
| 9447 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9448 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9449 | 7.1.3. Matching strings |
| 9450 | ----------------------- |
| 9451 | |
| 9452 | String matching applies to string or binary fetch methods, and exists in 6 |
| 9453 | different forms : |
| 9454 | |
| 9455 | - exact match (-m str) : the extracted string must exactly match the |
| 9456 | patterns ; |
| 9457 | |
| 9458 | - substring match (-m sub) : the patterns are looked up inside the |
| 9459 | extracted string, and the ACL matches if any of them is found inside ; |
| 9460 | |
| 9461 | - prefix match (-m beg) : the patterns are compared with the beginning of |
| 9462 | the extracted string, and the ACL matches if any of them matches. |
| 9463 | |
| 9464 | - suffix match (-m end) : the patterns are compared with the end of the |
| 9465 | extracted string, and the ACL matches if any of them matches. |
| 9466 | |
| 9467 | - subdir match (-m sub) : the patterns are looked up inside the extracted |
| 9468 | string, delimited with slashes ("/"), and the ACL matches if any of them |
| 9469 | matches. |
| 9470 | |
| 9471 | - domain match (-m dom) : the patterns are looked up inside the extracted |
| 9472 | string, delimited with dots ("."), and the ACL matches if any of them |
| 9473 | matches. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9474 | |
| 9475 | String matching applies to verbatim strings as they are passed, with the |
| 9476 | exception of the backslash ("\") which makes it possible to escape some |
| 9477 | characters such as the space. If the "-i" flag is passed before the first |
| 9478 | string, then the matching will be performed ignoring the case. In order |
| 9479 | to match the string "-i", either set it second, or pass the "--" flag |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9480 | before the first string. Same applies of course to match the string "--". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9481 | |
| 9482 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9483 | 7.1.4. Matching regular expressions (regexes) |
| 9484 | --------------------------------------------- |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9485 | |
| 9486 | Just like with string matching, regex matching applies to verbatim strings as |
| 9487 | they are passed, with the exception of the backslash ("\") which makes it |
| 9488 | possible to escape some characters such as the space. If the "-i" flag is |
| 9489 | passed before the first regex, then the matching will be performed ignoring |
| 9490 | the case. In order to match the string "-i", either set it second, or pass |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9491 | the "--" flag before the first string. Same principle applies of course to |
| 9492 | match the string "--". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9493 | |
| 9494 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9495 | 7.1.5. Matching arbitrary data blocks |
| 9496 | ------------------------------------- |
| 9497 | |
| 9498 | It is possible to match some extracted samples against a binary block which may |
| 9499 | not safely be represented as a string. For this, the patterns must be passed as |
| 9500 | a series of hexadecimal digits in an even number, when the match method is set |
| 9501 | to binary. Each sequence of two digits will represent a byte. The hexadecimal |
| 9502 | digits may be used upper or lower case. |
| 9503 | |
| 9504 | Example : |
| 9505 | # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a) |
| 9506 | acl hello payload(0,6) -m bin 48656c6c6f0a |
| 9507 | |
| 9508 | |
| 9509 | 7.1.6. Matching IPv4 and IPv6 addresses |
| 9510 | --------------------------------------- |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9511 | |
| 9512 | IPv4 addresses values can be specified either as plain addresses or with a |
| 9513 | netmask appended, in which case the IPv4 address matches whenever it is |
| 9514 | within the network. Plain addresses may also be replaced with a resolvable |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 9515 | host name, but this practice is generally discouraged as it makes it more |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9516 | difficult to read and debug configurations. If hostnames are used, you should |
| 9517 | at least ensure that they are present in /etc/hosts so that the configuration |
| 9518 | does not depend on any random DNS match at the moment the configuration is |
| 9519 | parsed. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9520 | |
Willy Tarreau | ceb4ac9 | 2012-04-28 00:41:46 +0200 | [diff] [blame] | 9521 | IPv6 may be entered in their usual form, with or without a netmask appended. |
| 9522 | Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of |
| 9523 | trouble with randomly resolved IP addresses, host names are never allowed in |
| 9524 | IPv6 patterns. |
| 9525 | |
| 9526 | HAProxy is also able to match IPv4 addresses with IPv6 addresses in the |
| 9527 | following situations : |
| 9528 | - tested address is IPv4, pattern address is IPv4, the match applies |
| 9529 | in IPv4 using the supplied mask if any. |
| 9530 | - tested address is IPv6, pattern address is IPv6, the match applies |
| 9531 | in IPv6 using the supplied mask if any. |
| 9532 | - tested address is IPv6, pattern address is IPv4, the match applies in IPv4 |
| 9533 | using the pattern's mask if the IPv6 address matches with 2002:IPV4::, |
| 9534 | ::IPV4 or ::ffff:IPV4, otherwise it fails. |
| 9535 | - tested address is IPv4, pattern address is IPv6, the IPv4 address is first |
| 9536 | converted to IPv6 by prefixing ::ffff: in front of it, then the match is |
| 9537 | applied in IPv6 using the supplied IPv6 mask. |
| 9538 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9539 | |
| 9540 | 7.2. Using ACLs to form conditions |
| 9541 | ---------------------------------- |
| 9542 | |
| 9543 | Some actions are only performed upon a valid condition. A condition is a |
| 9544 | combination of ACLs with operators. 3 operators are supported : |
| 9545 | |
| 9546 | - AND (implicit) |
| 9547 | - OR (explicit with the "or" keyword or the "||" operator) |
| 9548 | - Negation with the exclamation mark ("!") |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9549 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9550 | A condition is formed as a disjunctive form: |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9551 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9552 | [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ... |
Willy Tarreau | bef91e7 | 2013-03-31 23:14:46 +0200 | [diff] [blame] | 9553 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9554 | Such conditions are generally used after an "if" or "unless" statement, |
| 9555 | indicating when the condition will trigger the action. |
Willy Tarreau | bef91e7 | 2013-03-31 23:14:46 +0200 | [diff] [blame] | 9556 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9557 | For instance, to block HTTP requests to the "*" URL with methods other than |
| 9558 | "OPTIONS", as well as POST requests without content-length, and GET or HEAD |
| 9559 | requests with a content-length greater than 0, and finally every request which |
| 9560 | is not either GET/HEAD/POST/OPTIONS ! |
| 9561 | |
| 9562 | acl missing_cl hdr_cnt(Content-length) eq 0 |
| 9563 | block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl |
| 9564 | block if METH_GET HTTP_CONTENT |
| 9565 | block unless METH_GET or METH_POST or METH_OPTIONS |
| 9566 | |
| 9567 | To select a different backend for requests to static contents on the "www" site |
| 9568 | and to every request on the "img", "video", "download" and "ftp" hosts : |
| 9569 | |
| 9570 | acl url_static path_beg /static /images /img /css |
| 9571 | acl url_static path_end .gif .png .jpg .css .js |
| 9572 | acl host_www hdr_beg(host) -i www |
| 9573 | acl host_static hdr_beg(host) -i img. video. download. ftp. |
| 9574 | |
| 9575 | # now use backend "static" for all static-only hosts, and for static urls |
| 9576 | # of host "www". Use backend "www" for the rest. |
| 9577 | use_backend static if host_static or host_www url_static |
| 9578 | use_backend www if host_www |
| 9579 | |
| 9580 | It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL |
| 9581 | expressions that are built on the fly without needing to be declared. They must |
| 9582 | be enclosed between braces, with a space before and after each brace (because |
| 9583 | the braces must be seen as independent words). Example : |
| 9584 | |
| 9585 | The following rule : |
| 9586 | |
| 9587 | acl missing_cl hdr_cnt(Content-length) eq 0 |
| 9588 | block if METH_POST missing_cl |
| 9589 | |
| 9590 | Can also be written that way : |
| 9591 | |
| 9592 | block if METH_POST { hdr_cnt(Content-length) eq 0 } |
| 9593 | |
| 9594 | It is generally not recommended to use this construct because it's a lot easier |
| 9595 | to leave errors in the configuration when written that way. However, for very |
| 9596 | simple rules matching only one source IP address for instance, it can make more |
| 9597 | sense to use them than to declare ACLs with random names. Another example of |
| 9598 | good use is the following : |
| 9599 | |
| 9600 | With named ACLs : |
| 9601 | |
| 9602 | acl site_dead nbsrv(dynamic) lt 2 |
| 9603 | acl site_dead nbsrv(static) lt 2 |
| 9604 | monitor fail if site_dead |
| 9605 | |
| 9606 | With anonymous ACLs : |
| 9607 | |
| 9608 | monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 } |
| 9609 | |
| 9610 | See section 4.2 for detailed help on the "block" and "use_backend" keywords. |
| 9611 | |
| 9612 | |
| 9613 | 7.3. Fetching samples |
| 9614 | --------------------- |
| 9615 | |
| 9616 | Historically, sample fetch methods were only used to retrieve data to match |
| 9617 | against patterns using ACLs. With the arrival of stick-tables, a new class of |
| 9618 | sample fetch methods was created, most often sharing the same syntax as their |
| 9619 | ACL counterpart. These sample fetch methods are also known as "fetches". As |
| 9620 | of now, ACLs and fetches have converged. All ACL fetch methods have been made |
| 9621 | available as fetch methods, and ACLs may use any sample fetch method as well. |
| 9622 | |
| 9623 | This section details all available sample fetch methods and their output type. |
| 9624 | Some sample fetch methods have deprecated aliases that are used to maintain |
| 9625 | compatibility with existing configurations. They are then explicitly marked as |
| 9626 | deprecated and should not be used in new setups. |
| 9627 | |
| 9628 | The ACL derivatives are also indicated when available, with their respective |
| 9629 | matching methods. These ones all have a well defined default pattern matching |
| 9630 | method, so it is never necessary (though allowed) to pass the "-m" option to |
| 9631 | indicate how the sample will be matched using ACLs. |
| 9632 | |
| 9633 | As indicated in the sample type versus matching compatibility matrix above, |
| 9634 | when using a generic sample fetch method in an ACL, the "-m" option is |
| 9635 | mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When |
| 9636 | the same keyword exists as an ACL keyword and as a standard fetch method, the |
| 9637 | ACL engine will automatically pick the ACL-only one by default. |
| 9638 | |
| 9639 | Some of these keywords support one or multiple mandatory arguments, and one or |
| 9640 | multiple optional arguments. These arguments are strongly typed and are checked |
| 9641 | when the configuration is parsed so that there is no risk of running with an |
| 9642 | incorrect argument (eg: an unresolved backend name). Fetch function arguments |
| 9643 | are passed between parenthesis and are delimited by commas. When an argument |
| 9644 | is optional, it will be indicated below between square brackets ('[ ]'). When |
| 9645 | all arguments are optional, the parenthesis may be omitted. |
| 9646 | |
| 9647 | Thus, the syntax of a standard sample fetch method is one of the following : |
| 9648 | - name |
| 9649 | - name(arg1) |
| 9650 | - name(arg1,arg2) |
| 9651 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9652 | |
| 9653 | 7.3.1. Converters |
| 9654 | ----------------- |
| 9655 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 9656 | Sample fetch methods may be combined with transformations to be applied on top |
| 9657 | of the fetched sample (also called "converters"). These combinations form what |
| 9658 | is called "sample expressions" and the result is a "sample". Initially this |
| 9659 | was only supported by "stick on" and "stick store-request" directives but this |
| 9660 | has now be extended to all places where samples may be used (acls, log-format, |
| 9661 | unique-id-format, add-header, ...). |
| 9662 | |
| 9663 | These transformations are enumerated as a series of specific keywords after the |
| 9664 | sample fetch method. These keywords may equally be appended immediately after |
| 9665 | the fetch keyword's argument, delimited by a comma. These keywords can also |
| 9666 | support some arguments (eg: a netmask) which must be passed in parenthesis. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9667 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9668 | The currently available list of transformation keywords include : |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9669 | |
Emeric Brun | 53d1a98 | 2014-04-30 18:21:37 +0200 | [diff] [blame] | 9670 | base64 |
| 9671 | Converts a binary input sample to a base64 string. It is used to log or |
| 9672 | transfer binary content in a way that can be reliably transferred (eg: |
| 9673 | an SSL ID can be copied in a header). |
| 9674 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9675 | lower |
| 9676 | Convert a string sample to lower case. This can only be placed after a string |
| 9677 | sample fetch function or after a transformation keyword returning a string |
| 9678 | type. The result is of type string. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9679 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9680 | upper |
| 9681 | Convert a string sample to upper case. This can only be placed after a string |
| 9682 | sample fetch function or after a transformation keyword returning a string |
| 9683 | type. The result is of type string. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9684 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9685 | hex |
| 9686 | Converts a binary input sample to an hex string containing two hex digits per |
| 9687 | input byte. It is used to log or transfer hex dumps of some binary input data |
| 9688 | in a way that can be reliably transferred (eg: an SSL ID can be copied in a |
| 9689 | header). |
Thierry FOURNIER | 2f49d6d | 2014-03-12 15:01:52 +0100 | [diff] [blame] | 9690 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9691 | ipmask(<mask>) |
| 9692 | Apply a mask to an IPv4 address, and use the result for lookups and storage. |
| 9693 | This can be used to make all hosts within a certain mask to share the same |
| 9694 | table entries and as such use the same server. The mask can be passed in |
| 9695 | dotted form (eg: 255.255.255.0) or in CIDR form (eg: 24). |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9696 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9697 | http_date([<offset>]) |
| 9698 | Converts an integer supposed to contain a date since epoch to a string |
| 9699 | representing this date in a format suitable for use in HTTP header fields. If |
| 9700 | an offset value is specified, then it is a number of seconds that is added to |
| 9701 | the date before the conversion is operated. This is particularly useful to |
| 9702 | emit Date header fields, Expires values in responses when combined with a |
| 9703 | positive offset, or Last-Modified values when the offset is negative. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9704 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9705 | language(<value>[,<default>]) |
| 9706 | Returns the value with the highest q-factor from a list as extracted from the |
| 9707 | "accept-language" header using "req.fhdr". Values with no q-factor have a |
| 9708 | q-factor of 1. Values with a q-factor of 0 are dropped. Only values which |
| 9709 | belong to the list of semi-colon delimited <values> will be considered. The |
| 9710 | argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the |
| 9711 | given list and a default value is provided, it is returned. Note that language |
| 9712 | names may have a variant after a dash ('-'). If this variant is present in the |
| 9713 | list, it will be matched, but if it is not, only the base language is checked. |
| 9714 | The match is case-sensitive, and the output string is always one of those |
| 9715 | provided in arguments. The ordering of arguments is meaningless, only the |
| 9716 | ordering of the values in the request counts, as the first value among |
| 9717 | multiple sharing the same q-factor is used. |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 9718 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9719 | Example : |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 9720 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9721 | # this configuration switches to the backend matching a |
| 9722 | # given language based on the request : |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 9723 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9724 | acl es req.fhdr(accept-language),language(es;fr;en) -m str es |
| 9725 | acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr |
| 9726 | acl en req.fhdr(accept-language),language(es;fr;en) -m str en |
| 9727 | use_backend spanish if es |
| 9728 | use_backend french if fr |
| 9729 | use_backend english if en |
| 9730 | default_backend choose_your_language |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 9731 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9732 | map(<map_file>[,<default_value>]) |
| 9733 | map_<match_type>(<map_file>[,<default_value>]) |
| 9734 | map_<match_type>_<output_type>(<map_file>[,<default_value>]) |
| 9735 | Search the input value from <map_file> using the <match_type> matching method, |
| 9736 | and return the associated value converted to the type <output_type>. If the |
| 9737 | input value cannot be found in the <map_file>, the converter returns the |
| 9738 | <default_value>. If the <default_value> is not set, the converter fails and |
| 9739 | acts as if no input value could be fetched. If the <match_type> is not set, it |
| 9740 | defaults to "str". Likewise, if the <output_type> is not set, it defaults to |
| 9741 | "str". For convenience, the "map" keyword is an alias for "map_str" and maps a |
| 9742 | string to another string. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 9743 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9744 | It is important to avoid overlapping between the keys : IP addresses and |
| 9745 | strings are stored in trees, so the first of the finest match will be used. |
| 9746 | Other keys are stored in lists, so the first matching occurrence will be used. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 9747 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9748 | The following array contains the list of all map functions avalaible sorted by |
| 9749 | input type, match type and output type. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 9750 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9751 | input type | match method | output type str | output type int | output type ip |
| 9752 | -----------+--------------+-----------------+-----------------+--------------- |
| 9753 | str | str | map_str | map_str_int | map_str_ip |
| 9754 | -----------+--------------+-----------------+-----------------+--------------- |
Willy Tarreau | 787a4c0 | 2014-05-10 07:55:30 +0200 | [diff] [blame] | 9755 | str | beg | map_beg | map_beg_int | map_end_ip |
| 9756 | -----------+--------------+-----------------+-----------------+--------------- |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9757 | str | sub | map_sub | map_sub_int | map_sub_ip |
| 9758 | -----------+--------------+-----------------+-----------------+--------------- |
| 9759 | str | dir | map_dir | map_dir_int | map_dir_ip |
| 9760 | -----------+--------------+-----------------+-----------------+--------------- |
| 9761 | str | dom | map_dom | map_dom_int | map_dom_ip |
| 9762 | -----------+--------------+-----------------+-----------------+--------------- |
| 9763 | str | end | map_end | map_end_int | map_end_ip |
| 9764 | -----------+--------------+-----------------+-----------------+--------------- |
| 9765 | str | reg | map_reg | map_reg_int | map_reg_ip |
| 9766 | -----------+--------------+-----------------+-----------------+--------------- |
| 9767 | int | int | map_int | map_int_int | map_int_ip |
| 9768 | -----------+--------------+-----------------+-----------------+--------------- |
| 9769 | ip | ip | map_ip | map_ip_int | map_ip_ip |
| 9770 | -----------+--------------+-----------------+-----------------+--------------- |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 9771 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9772 | The file contains one key + value per line. Lines which start with '#' are |
| 9773 | ignored, just like empty lines. Leading tabs and spaces are stripped. The key |
| 9774 | is then the first "word" (series of non-space/tabs characters), and the value |
| 9775 | is what follows this series of space/tab till the end of the line excluding |
| 9776 | trailing spaces/tabs. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 9777 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9778 | Example : |
| 9779 | |
| 9780 | # this is a comment and is ignored |
| 9781 | 2.22.246.0/23 United Kingdom \n |
| 9782 | <-><-----------><--><------------><----> |
| 9783 | | | | | `- trailing spaces ignored |
| 9784 | | | | `---------- value |
| 9785 | | | `-------------------- middle spaces ignored |
| 9786 | | `---------------------------- key |
| 9787 | `------------------------------------ leading spaces ignored |
| 9788 | |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 9789 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9790 | 7.3.2. Fetching samples from internal states |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9791 | -------------------------------------------- |
| 9792 | |
| 9793 | A first set of sample fetch methods applies to internal information which does |
| 9794 | not even relate to any client information. These ones are sometimes used with |
| 9795 | "monitor-fail" directives to report an internal status to external watchers. |
| 9796 | The sample fetch methods described in this section are usable anywhere. |
| 9797 | |
| 9798 | always_false : boolean |
| 9799 | Always returns the boolean "false" value. It may be used with ACLs as a |
| 9800 | temporary replacement for another one when adjusting configurations. |
| 9801 | |
| 9802 | always_true : boolean |
| 9803 | Always returns the boolean "true" value. It may be used with ACLs as a |
| 9804 | temporary replacement for another one when adjusting configurations. |
| 9805 | |
| 9806 | avg_queue([<backend>]) : integer |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 9807 | Returns the total number of queued connections of the designated backend |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9808 | divided by the number of active servers. The current backend is used if no |
| 9809 | backend is specified. This is very similar to "queue" except that the size of |
| 9810 | the farm is considered, in order to give a more accurate measurement of the |
| 9811 | time it may take for a new connection to be processed. The main usage is with |
| 9812 | ACL to return a sorry page to new users when it becomes certain they will get |
| 9813 | a degraded service, or to pass to the backend servers in a header so that |
| 9814 | they decide to work in degraded mode or to disable some functions to speed up |
| 9815 | the processing a bit. Note that in the event there would not be any active |
| 9816 | server anymore, twice the number of queued connections would be considered as |
| 9817 | the measured value. This is a fair estimate, as we expect one server to get |
| 9818 | back soon anyway, but we still prefer to send new traffic to another backend |
| 9819 | if in better shape. See also the "queue", "be_conn", and "be_sess_rate" |
| 9820 | sample fetches. |
Krzysztof Piotr Oledzki | 346f76d | 2010-01-12 21:59:30 +0100 | [diff] [blame] | 9821 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9822 | be_conn([<backend>]) : integer |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 9823 | Applies to the number of currently established connections on the backend, |
| 9824 | possibly including the connection being evaluated. If no backend name is |
| 9825 | specified, the current one is used. But it is also possible to check another |
| 9826 | backend. It can be used to use a specific farm when the nominal one is full. |
| 9827 | See also the "fe_conn", "queue" and "be_sess_rate" criteria. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 9828 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9829 | be_sess_rate([<backend>]) : integer |
| 9830 | Returns an integer value corresponding to the sessions creation rate on the |
| 9831 | backend, in number of new sessions per second. This is used with ACLs to |
| 9832 | switch to an alternate backend when an expensive or fragile one reaches too |
| 9833 | high a session rate, or to limit abuse of service (eg. prevent sucking of an |
| 9834 | online dictionary). It can also be useful to add this element to logs using a |
| 9835 | log-format directive. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 9836 | |
| 9837 | Example : |
| 9838 | # Redirect to an error page if the dictionary is requested too often |
| 9839 | backend dynamic |
| 9840 | mode http |
| 9841 | acl being_scanned be_sess_rate gt 100 |
| 9842 | redirect location /denied.html if being_scanned |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 9843 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9844 | connslots([<backend>]) : integer |
| 9845 | Returns an integer value corresponding to the number of connection slots |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9846 | still available in the backend, by totaling the maximum amount of |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9847 | connections on all servers and the maximum queue size. This is probably only |
| 9848 | used with ACLs. |
Tait Clarridge | 7896d52 | 2012-12-05 21:39:31 -0500 | [diff] [blame] | 9849 | |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 9850 | The basic idea here is to be able to measure the number of connection "slots" |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9851 | still available (connection + queue), so that anything beyond that (intended |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 9852 | usage; see "use_backend" keyword) can be redirected to a different backend. |
| 9853 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9854 | 'connslots' = number of available server connection slots, + number of |
| 9855 | available server queue slots. |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 9856 | |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 9857 | Note that while "fe_conn" may be used, "connslots" comes in especially |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9858 | useful when you have a case of traffic going to one single ip, splitting into |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9859 | multiple backends (perhaps using ACLs to do name-based load balancing) and |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9860 | you want to be able to differentiate between different backends, and their |
| 9861 | available "connslots". Also, whereas "nbsrv" only measures servers that are |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9862 | actually *down*, this fetch is more fine-grained and looks into the number of |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 9863 | available connection slots as well. See also "queue" and "avg_queue". |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 9864 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9865 | OTHER CAVEATS AND NOTES: at this point in time, the code does not take care |
| 9866 | of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0, |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9867 | then this fetch clearly does not make sense, in which case the value returned |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9868 | will be -1. |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 9869 | |
Willy Tarreau | 6236d3a | 2013-07-25 14:28:25 +0200 | [diff] [blame] | 9870 | date([<offset>]) : integer |
| 9871 | Returns the current date as the epoch (number of seconds since 01/01/1970). |
| 9872 | If an offset value is specified, then it is a number of seconds that is added |
| 9873 | to the current date before returning the value. This is particularly useful |
| 9874 | to compute relative dates, as both positive and negative offsets are allowed. |
Willy Tarreau | 276fae9 | 2013-07-25 14:36:01 +0200 | [diff] [blame] | 9875 | It is useful combined with the http_date converter. |
| 9876 | |
| 9877 | Example : |
| 9878 | |
| 9879 | # set an expires header to now+1 hour in every response |
| 9880 | http-response set-header Expires %[date(3600),http_date] |
Willy Tarreau | 6236d3a | 2013-07-25 14:28:25 +0200 | [diff] [blame] | 9881 | |
Willy Tarreau | 595ec54 | 2013-06-12 21:34:28 +0200 | [diff] [blame] | 9882 | env(<name>) : string |
| 9883 | Returns a string containing the value of environment variable <name>. As a |
| 9884 | reminder, environment variables are per-process and are sampled when the |
| 9885 | process starts. This can be useful to pass some information to a next hop |
| 9886 | server, or with ACLs to take specific action when the process is started a |
| 9887 | certain way. |
| 9888 | |
| 9889 | Examples : |
| 9890 | # Pass the Via header to next hop with the local hostname in it |
| 9891 | http-request add-header Via 1.1\ %[env(HOSTNAME)] |
| 9892 | |
| 9893 | # reject cookie-less requests when the STOP environment variable is set |
| 9894 | http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found } |
| 9895 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9896 | fe_conn([<frontend>]) : integer |
| 9897 | Returns the number of currently established connections on the frontend, |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 9898 | possibly including the connection being evaluated. If no frontend name is |
| 9899 | specified, the current one is used. But it is also possible to check another |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9900 | frontend. It can be used to return a sorry page before hard-blocking, or to |
| 9901 | use a specific backend to drain new requests when the farm is considered |
| 9902 | full. This is mostly used with ACLs but can also be used to pass some |
| 9903 | statistics to servers in HTTP headers. See also the "dst_conn", "be_conn", |
| 9904 | "fe_sess_rate" fetches. |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 9905 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9906 | fe_sess_rate([<frontend>]) : integer |
| 9907 | Returns an integer value corresponding to the sessions creation rate on the |
| 9908 | frontend, in number of new sessions per second. This is used with ACLs to |
| 9909 | limit the incoming session rate to an acceptable range in order to prevent |
| 9910 | abuse of service at the earliest moment, for example when combined with other |
| 9911 | layer 4 ACLs in order to force the clients to wait a bit for the rate to go |
| 9912 | down below the limit. It can also be useful to add this element to logs using |
| 9913 | a log-format directive. See also the "rate-limit sessions" directive for use |
| 9914 | in frontends. |
Willy Tarreau | 079ff0a | 2009-03-05 21:34:28 +0100 | [diff] [blame] | 9915 | |
| 9916 | Example : |
| 9917 | # This frontend limits incoming mails to 10/s with a max of 100 |
| 9918 | # concurrent connections. We accept any connection below 10/s, and |
| 9919 | # force excess clients to wait for 100 ms. Since clients are limited to |
| 9920 | # 100 max, there cannot be more than 10 incoming mails per second. |
| 9921 | frontend mail |
| 9922 | bind :25 |
| 9923 | mode tcp |
| 9924 | maxconn 100 |
| 9925 | acl too_fast fe_sess_rate ge 10 |
| 9926 | tcp-request inspect-delay 100ms |
| 9927 | tcp-request content accept if ! too_fast |
| 9928 | tcp-request content accept if WAIT_END |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 9929 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9930 | nbsrv([<backend>]) : integer |
| 9931 | Returns an integer value corresponding to the number of usable servers of |
| 9932 | either the current backend or the named backend. This is mostly used with |
| 9933 | ACLs but can also be useful when added to logs. This is normally used to |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 9934 | switch to an alternate backend when the number of servers is too low to |
| 9935 | to handle some load. It is useful to report a failure when combined with |
| 9936 | "monitor fail". |
Willy Tarreau | 079ff0a | 2009-03-05 21:34:28 +0100 | [diff] [blame] | 9937 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9938 | queue([<backend>]) : integer |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 9939 | Returns the total number of queued connections of the designated backend, |
| 9940 | including all the connections in server queues. If no backend name is |
| 9941 | specified, the current one is used, but it is also possible to check another |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9942 | one. This is useful with ACLs or to pass statistics to backend servers. This |
| 9943 | can be used to take actions when queuing goes above a known level, generally |
| 9944 | indicating a surge of traffic or a massive slowdown on the servers. One |
| 9945 | possible action could be to reject new users but still accept old ones. See |
| 9946 | also the "avg_queue", "be_conn", and "be_sess_rate" fetches. |
| 9947 | |
Willy Tarreau | 84310e2 | 2014-02-14 11:59:04 +0100 | [diff] [blame] | 9948 | rand([<range>]) : integer |
| 9949 | Returns a random integer value within a range of <range> possible values, |
| 9950 | starting at zero. If the range is not specified, it defaults to 2^32, which |
| 9951 | gives numbers between 0 and 4294967295. It can be useful to pass some values |
| 9952 | needed to take some routing decisions for example, or just for debugging |
| 9953 | purposes. This random must not be used for security purposes. |
| 9954 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9955 | srv_conn([<backend>/]<server>) : integer |
| 9956 | Returns an integer value corresponding to the number of currently established |
| 9957 | connections on the designated server, possibly including the connection being |
| 9958 | evaluated. If <backend> is omitted, then the server is looked up in the |
| 9959 | current backend. It can be used to use a specific farm when one server is |
| 9960 | full, or to inform the server about our view of the number of active |
| 9961 | connections with it. See also the "fe_conn", "be_conn" and "queue" fetch |
| 9962 | methods. |
| 9963 | |
| 9964 | srv_is_up([<backend>/]<server>) : boolean |
| 9965 | Returns true when the designated server is UP, and false when it is either |
| 9966 | DOWN or in maintenance mode. If <backend> is omitted, then the server is |
| 9967 | looked up in the current backend. It is mainly used to take action based on |
| 9968 | an external status reported via a health check (eg: a geographical site's |
| 9969 | availability). Another possible use which is more of a hack consists in |
| 9970 | using dummy servers as boolean variables that can be enabled or disabled from |
| 9971 | the CLI, so that rules depending on those ACLs can be tweaked in realtime. |
| 9972 | |
| 9973 | srv_sess_rate([<backend>/]<server>) : integer |
| 9974 | Returns an integer corresponding to the sessions creation rate on the |
| 9975 | designated server, in number of new sessions per second. If <backend> is |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9976 | omitted, then the server is looked up in the current backend. This is mostly |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9977 | used with ACLs but can make sense with logs too. This is used to switch to an |
| 9978 | alternate backend when an expensive or fragile one reaches too high a session |
| 9979 | rate, or to limit abuse of service (eg. prevent latent requests from |
| 9980 | overloading servers). |
| 9981 | |
| 9982 | Example : |
| 9983 | # Redirect to a separate back |
| 9984 | acl srv1_full srv_sess_rate(be1/srv1) gt 50 |
| 9985 | acl srv2_full srv_sess_rate(be1/srv2) gt 50 |
| 9986 | use_backend be2 if srv1_full or srv2_full |
| 9987 | |
| 9988 | table_avl([<table>]) : integer |
| 9989 | Returns the total number of available entries in the current proxy's |
| 9990 | stick-table or in the designated stick-table. See also table_cnt. |
| 9991 | |
| 9992 | table_cnt([<table>]) : integer |
| 9993 | Returns the total number of entries currently in use in the current proxy's |
| 9994 | stick-table or in the designated stick-table. See also src_conn_cnt and |
| 9995 | table_avl for other entry counting methods. |
| 9996 | |
| 9997 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 9998 | 7.3.3. Fetching samples at Layer 4 |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 9999 | ---------------------------------- |
| 10000 | |
| 10001 | The layer 4 usually describes just the transport layer which in haproxy is |
| 10002 | closest to the connection, where no content is yet made available. The fetch |
| 10003 | methods described here are usable as low as the "tcp-request connection" rule |
| 10004 | sets unless they require some future information. Those generally include |
| 10005 | TCP/IP addresses and ports, as well as elements from stick-tables related to |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10006 | the incoming connection. For retrieving a value from a sticky counters, the |
| 10007 | counter number can be explicitly set as 0, 1, or 2 using the pre-defined |
| 10008 | "sc0_", "sc1_", or "sc2_" prefix, or it can be specified as the first integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10009 | argument when using the "sc_" prefix. An optional table may be specified with |
| 10010 | the "sc*" form, in which case the currently tracked key will be looked up into |
| 10011 | this alternate table instead of the table currently being tracked. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10012 | |
| 10013 | be_id : integer |
| 10014 | Returns an integer containing the current backend's id. It can be used in |
| 10015 | frontends with responses to check which backend processed the request. |
| 10016 | |
| 10017 | dst : ip |
| 10018 | This is the destination IPv4 address of the connection on the client side, |
| 10019 | which is the address the client connected to. It can be useful when running |
| 10020 | in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables. |
| 10021 | On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to |
| 10022 | RFC 4291. |
| 10023 | |
| 10024 | dst_conn : integer |
| 10025 | Returns an integer value corresponding to the number of currently established |
| 10026 | connections on the same socket including the one being evaluated. It is |
| 10027 | normally used with ACLs but can as well be used to pass the information to |
| 10028 | servers in an HTTP header or in logs. It can be used to either return a sorry |
| 10029 | page before hard-blocking, or to use a specific backend to drain new requests |
| 10030 | when the socket is considered saturated. This offers the ability to assign |
| 10031 | different limits to different listening ports or addresses. See also the |
| 10032 | "fe_conn" and "be_conn" fetches. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10033 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10034 | dst_port : integer |
| 10035 | Returns an integer value corresponding to the destination TCP port of the |
| 10036 | connection on the client side, which is the port the client connected to. |
| 10037 | This might be used when running in transparent mode, when assigning dynamic |
| 10038 | ports to some clients for a whole application session, to stick all users to |
| 10039 | a same server, or to pass the destination port information to a server using |
| 10040 | an HTTP header. |
| 10041 | |
| 10042 | fe_id : integer |
| 10043 | Returns an integer containing the current frontend's id. It can be used in |
| 10044 | backends to check from which backend it was called, or to stick all users |
| 10045 | coming via a same frontend to the same server. |
| 10046 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10047 | sc_bytes_in_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10048 | sc0_bytes_in_rate([<table>]) : integer |
| 10049 | sc1_bytes_in_rate([<table>]) : integer |
| 10050 | sc2_bytes_in_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10051 | Returns the average client-to-server bytes rate from the currently tracked |
| 10052 | counters, measured in amount of bytes over the period configured in the |
| 10053 | table. See also src_bytes_in_rate. |
| 10054 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10055 | sc_bytes_out_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10056 | sc0_bytes_out_rate([<table>]) : integer |
| 10057 | sc1_bytes_out_rate([<table>]) : integer |
| 10058 | sc2_bytes_out_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10059 | Returns the average server-to-client bytes rate from the currently tracked |
| 10060 | counters, measured in amount of bytes over the period configured in the |
| 10061 | table. See also src_bytes_out_rate. |
| 10062 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10063 | sc_clr_gpc0(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10064 | sc0_clr_gpc0([<table>]) : integer |
| 10065 | sc1_clr_gpc0([<table>]) : integer |
| 10066 | sc2_clr_gpc0([<table>]) : integer |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 10067 | Clears the first General Purpose Counter associated to the currently tracked |
| 10068 | counters, and returns its previous value. Before the first invocation, the |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 10069 | stored value is zero, so first invocation will always return zero. This is |
| 10070 | typically used as a second ACL in an expression in order to mark a connection |
| 10071 | when a first ACL was verified : |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 10072 | |
| 10073 | # block if 5 consecutive requests continue to come faster than 10 sess |
| 10074 | # per second, and reset the counter as soon as the traffic slows down. |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 10075 | acl abuse sc0_http_req_rate gt 10 |
| 10076 | acl kill sc0_inc_gpc0 gt 5 |
| 10077 | acl save sc0_clr_gpc0 ge 0 |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 10078 | tcp-request connection accept if !abuse save |
| 10079 | tcp-request connection reject if abuse kill |
| 10080 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10081 | sc_conn_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10082 | sc0_conn_cnt([<table>]) : integer |
| 10083 | sc1_conn_cnt([<table>]) : integer |
| 10084 | sc2_conn_cnt([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10085 | Returns the cumulated number of incoming connections from currently tracked |
| 10086 | counters. See also src_conn_cnt. |
| 10087 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10088 | sc_conn_cur(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10089 | sc0_conn_cur([<table>]) : integer |
| 10090 | sc1_conn_cur([<table>]) : integer |
| 10091 | sc2_conn_cur([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10092 | Returns the current amount of concurrent connections tracking the same |
| 10093 | tracked counters. This number is automatically incremented when tracking |
| 10094 | begins and decremented when tracking stops. See also src_conn_cur. |
| 10095 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10096 | sc_conn_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10097 | sc0_conn_rate([<table>]) : integer |
| 10098 | sc1_conn_rate([<table>]) : integer |
| 10099 | sc2_conn_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10100 | Returns the average connection rate from the currently tracked counters, |
| 10101 | measured in amount of connections over the period configured in the table. |
| 10102 | See also src_conn_rate. |
| 10103 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10104 | sc_get_gpc0(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10105 | sc0_get_gpc0([<table>]) : integer |
| 10106 | sc1_get_gpc0([<table>]) : integer |
| 10107 | sc2_get_gpc0([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10108 | Returns the value of the first General Purpose Counter associated to the |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10109 | currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0. |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 10110 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10111 | sc_gpc0_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10112 | sc0_gpc0_rate([<table>]) : integer |
| 10113 | sc1_gpc0_rate([<table>]) : integer |
| 10114 | sc2_gpc0_rate([<table>]) : integer |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 10115 | Returns the average increment rate of the first General Purpose Counter |
| 10116 | associated to the currently tracked counters. It reports the frequency |
| 10117 | which the gpc0 counter was incremented over the configured period. See also |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10118 | src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note |
| 10119 | that the "gpc0_rate" counter must be stored in the stick-table for a value to |
| 10120 | be returned, as "gpc0" only holds the event count. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10121 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10122 | sc_http_err_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10123 | sc0_http_err_cnt([<table>]) : integer |
| 10124 | sc1_http_err_cnt([<table>]) : integer |
| 10125 | sc2_http_err_cnt([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10126 | Returns the cumulated number of HTTP errors from the currently tracked |
| 10127 | counters. This includes the both request errors and 4xx error responses. |
| 10128 | See also src_http_err_cnt. |
| 10129 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10130 | sc_http_err_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10131 | sc0_http_err_rate([<table>]) : integer |
| 10132 | sc1_http_err_rate([<table>]) : integer |
| 10133 | sc2_http_err_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10134 | Returns the average rate of HTTP errors from the currently tracked counters, |
| 10135 | measured in amount of errors over the period configured in the table. This |
| 10136 | includes the both request errors and 4xx error responses. See also |
| 10137 | src_http_err_rate. |
| 10138 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10139 | sc_http_req_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10140 | sc0_http_req_cnt([<table>]) : integer |
| 10141 | sc1_http_req_cnt([<table>]) : integer |
| 10142 | sc2_http_req_cnt([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10143 | Returns the cumulated number of HTTP requests from the currently tracked |
| 10144 | counters. This includes every started request, valid or not. See also |
| 10145 | src_http_req_cnt. |
| 10146 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10147 | sc_http_req_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10148 | sc0_http_req_rate([<table>]) : integer |
| 10149 | sc1_http_req_rate([<table>]) : integer |
| 10150 | sc2_http_req_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10151 | Returns the average rate of HTTP requests from the currently tracked |
| 10152 | counters, measured in amount of requests over the period configured in |
| 10153 | the table. This includes every started request, valid or not. See also |
| 10154 | src_http_req_rate. |
| 10155 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10156 | sc_inc_gpc0(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10157 | sc0_inc_gpc0([<table>]) : integer |
| 10158 | sc1_inc_gpc0([<table>]) : integer |
| 10159 | sc2_inc_gpc0([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10160 | Increments the first General Purpose Counter associated to the currently |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 10161 | tracked counters, and returns its new value. Before the first invocation, |
| 10162 | the stored value is zero, so first invocation will increase it to 1 and will |
| 10163 | return 1. This is typically used as a second ACL in an expression in order |
| 10164 | to mark a connection when a first ACL was verified : |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10165 | |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 10166 | acl abuse sc0_http_req_rate gt 10 |
| 10167 | acl kill sc0_inc_gpc0 gt 0 |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10168 | tcp-request connection reject if abuse kill |
| 10169 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10170 | sc_kbytes_in(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10171 | sc0_kbytes_in([<table>]) : integer |
| 10172 | sc1_kbytes_in([<table>]) : integer |
| 10173 | sc2_kbytes_in([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10174 | Returns the amount of client-to-server data from the currently tracked |
| 10175 | counters, measured in kilobytes over the period configured in the table. The |
| 10176 | test is currently performed on 32-bit integers, which limits values to 4 |
| 10177 | terabytes. See also src_kbytes_in. |
| 10178 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10179 | sc_kbytes_out(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10180 | sc0_kbytes_out([<table>]) : integer |
| 10181 | sc1_kbytes_out([<table>]) : integer |
| 10182 | sc2_kbytes_out([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10183 | Returns the amount of server-to-client data from the currently tracked |
| 10184 | counters, measured in kilobytes over the period configured in the table. The |
| 10185 | test is currently performed on 32-bit integers, which limits values to 4 |
| 10186 | terabytes. See also src_kbytes_out. |
| 10187 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10188 | sc_sess_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10189 | sc0_sess_cnt([<table>]) : integer |
| 10190 | sc1_sess_cnt([<table>]) : integer |
| 10191 | sc2_sess_cnt([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10192 | Returns the cumulated number of incoming connections that were transformed |
| 10193 | into sessions, which means that they were accepted by a "tcp-request |
| 10194 | connection" rule, from the currently tracked counters. A backend may count |
| 10195 | more sessions than connections because each connection could result in many |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 10196 | backend sessions if some HTTP keep-alive is performed over the connection |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10197 | with the client. See also src_sess_cnt. |
| 10198 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10199 | sc_sess_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10200 | sc0_sess_rate([<table>]) : integer |
| 10201 | sc1_sess_rate([<table>]) : integer |
| 10202 | sc2_sess_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10203 | Returns the average session rate from the currently tracked counters, |
| 10204 | measured in amount of sessions over the period configured in the table. A |
| 10205 | session is a connection that got past the early "tcp-request connection" |
| 10206 | rules. A backend may count more sessions than connections because each |
| 10207 | connection could result in many backend sessions if some HTTP keep-alive is |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 10208 | performed over the connection with the client. See also src_sess_rate. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10209 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10210 | sc_tracked(<ctr>[,<table>]) : boolean |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10211 | sc0_tracked([<table>]) : boolean |
| 10212 | sc1_tracked([<table>]) : boolean |
| 10213 | sc2_tracked([<table>]) : boolean |
Willy Tarreau | 6f1615f | 2013-06-03 15:15:22 +0200 | [diff] [blame] | 10214 | Returns true if the designated session counter is currently being tracked by |
| 10215 | the current session. This can be useful when deciding whether or not we want |
| 10216 | to set some values in a header passed to the server. |
| 10217 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 10218 | sc_trackers(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 10219 | sc0_trackers([<table>]) : integer |
| 10220 | sc1_trackers([<table>]) : integer |
| 10221 | sc2_trackers([<table>]) : integer |
Willy Tarreau | 2406db4 | 2012-12-09 12:16:43 +0100 | [diff] [blame] | 10222 | Returns the current amount of concurrent connections tracking the same |
| 10223 | tracked counters. This number is automatically incremented when tracking |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 10224 | begins and decremented when tracking stops. It differs from sc0_conn_cur in |
Willy Tarreau | 2406db4 | 2012-12-09 12:16:43 +0100 | [diff] [blame] | 10225 | that it does not rely on any stored information but on the table's reference |
| 10226 | count (the "use" value which is returned by "show table" on the CLI). This |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10227 | may sometimes be more suited for layer7 tracking. It can be used to tell a |
| 10228 | server how many concurrent connections there are from a given address for |
| 10229 | example. |
Willy Tarreau | 2406db4 | 2012-12-09 12:16:43 +0100 | [diff] [blame] | 10230 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10231 | so_id : integer |
| 10232 | Returns an integer containing the current listening socket's id. It is useful |
| 10233 | in frontends involving many "bind" lines, or to stick all users coming via a |
| 10234 | same socket to the same server. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10235 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10236 | src : ip |
| 10237 | This is the source IPv4 address of the client of the session. It is of type |
| 10238 | IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are |
| 10239 | mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the |
| 10240 | TCP-level source address which is used, and not the address of a client |
| 10241 | behind a proxy. However if the "accept-proxy" bind directive is used, it can |
| 10242 | be the address of a client behind another PROXY-protocol compatible component |
| 10243 | for all rule sets except "tcp-request connection" which sees the real address. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10244 | |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 10245 | Example: |
| 10246 | # add an HTTP header in requests with the originating address' country |
| 10247 | http-request set-header X-Country %[src,map_ip(geoip.lst)] |
| 10248 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10249 | src_bytes_in_rate([<table>]) : integer |
| 10250 | Returns the average bytes rate from the incoming connection's source address |
| 10251 | in the current proxy's stick-table or in the designated stick-table, measured |
| 10252 | in amount of bytes over the period configured in the table. If the address is |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10253 | not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10254 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10255 | src_bytes_out_rate([<table>]) : integer |
| 10256 | Returns the average bytes rate to the incoming connection's source address in |
| 10257 | the current proxy's stick-table or in the designated stick-table, measured in |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10258 | amount of bytes over the period configured in the table. If the address is |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10259 | not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10260 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10261 | src_clr_gpc0([<table>]) : integer |
| 10262 | Clears the first General Purpose Counter associated to the incoming |
| 10263 | connection's source address in the current proxy's stick-table or in the |
| 10264 | designated stick-table, and returns its previous value. If the address is not |
| 10265 | found, an entry is created and 0 is returned. This is typically used as a |
| 10266 | second ACL in an expression in order to mark a connection when a first ACL |
| 10267 | was verified : |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 10268 | |
| 10269 | # block if 5 consecutive requests continue to come faster than 10 sess |
| 10270 | # per second, and reset the counter as soon as the traffic slows down. |
| 10271 | acl abuse src_http_req_rate gt 10 |
| 10272 | acl kill src_inc_gpc0 gt 5 |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 10273 | acl save src_clr_gpc0 ge 0 |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 10274 | tcp-request connection accept if !abuse save |
| 10275 | tcp-request connection reject if abuse kill |
| 10276 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10277 | src_conn_cnt([<table>]) : integer |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10278 | Returns the cumulated number of connections initiated from the current |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10279 | incoming connection's source address in the current proxy's stick-table or in |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10280 | the designated stick-table. If the address is not found, zero is returned. |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10281 | See also sc/sc0/sc1/sc2_conn_cnt. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10282 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10283 | src_conn_cur([<table>]) : integer |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10284 | Returns the current amount of concurrent connections initiated from the |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10285 | current incoming connection's source address in the current proxy's |
| 10286 | stick-table or in the designated stick-table. If the address is not found, |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10287 | zero is returned. See also sc/sc0/sc1/sc2_conn_cur. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10288 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10289 | src_conn_rate([<table>]) : integer |
| 10290 | Returns the average connection rate from the incoming connection's source |
| 10291 | address in the current proxy's stick-table or in the designated stick-table, |
| 10292 | measured in amount of connections over the period configured in the table. If |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10293 | the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10294 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10295 | src_get_gpc0([<table>]) : integer |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10296 | Returns the value of the first General Purpose Counter associated to the |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10297 | incoming connection's source address in the current proxy's stick-table or in |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10298 | the designated stick-table. If the address is not found, zero is returned. |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10299 | See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10300 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10301 | src_gpc0_rate([<table>]) : integer |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 10302 | Returns the average increment rate of the first General Purpose Counter |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10303 | associated to the incoming connection's source address in the current proxy's |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 10304 | stick-table or in the designated stick-table. It reports the frequency |
| 10305 | which the gpc0 counter was incremented over the configured period. See also |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10306 | sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note |
| 10307 | that the "gpc0_rate" counter must be stored in the stick-table for a value to |
| 10308 | be returned, as "gpc0" only holds the event count. |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 10309 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10310 | src_http_err_cnt([<table>]) : integer |
| 10311 | Returns the cumulated number of HTTP errors from the incoming connection's |
| 10312 | source address in the current proxy's stick-table or in the designated |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10313 | stick-table. This includes the both request errors and 4xx error responses. |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10314 | See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10315 | returned. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10316 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10317 | src_http_err_rate([<table>]) : integer |
| 10318 | Returns the average rate of HTTP errors from the incoming connection's source |
| 10319 | address in the current proxy's stick-table or in the designated stick-table, |
| 10320 | measured in amount of errors over the period configured in the table. This |
| 10321 | includes the both request errors and 4xx error responses. If the address is |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10322 | not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10323 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10324 | src_http_req_cnt([<table>]) : integer |
| 10325 | Returns the cumulated number of HTTP requests from the incoming connection's |
| 10326 | source address in the current proxy's stick-table or in the designated stick- |
| 10327 | table. This includes every started request, valid or not. If the address is |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10328 | not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10329 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10330 | src_http_req_rate([<table>]) : integer |
| 10331 | Returns the average rate of HTTP requests from the incoming connection's |
| 10332 | source address in the current proxy's stick-table or in the designated stick- |
| 10333 | table, measured in amount of requests over the period configured in the |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10334 | table. This includes every started request, valid or not. If the address is |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10335 | not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10336 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10337 | src_inc_gpc0([<table>]) : integer |
| 10338 | Increments the first General Purpose Counter associated to the incoming |
| 10339 | connection's source address in the current proxy's stick-table or in the |
| 10340 | designated stick-table, and returns its new value. If the address is not |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 10341 | found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10342 | This is typically used as a second ACL in an expression in order to mark a |
| 10343 | connection when a first ACL was verified : |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10344 | |
| 10345 | acl abuse src_http_req_rate gt 10 |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 10346 | acl kill src_inc_gpc0 gt 0 |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 10347 | tcp-request connection reject if abuse kill |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10348 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10349 | src_kbytes_in([<table>]) : integer |
| 10350 | Returns the amount of data received from the incoming connection's source |
| 10351 | address in the current proxy's stick-table or in the designated stick-table, |
| 10352 | measured in kilobytes over the period configured in the table. If the address |
| 10353 | is not found, zero is returned. The test is currently performed on 32-bit |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10354 | integers, which limits values to 4 terabytes. See also |
| 10355 | sc/sc0/sc1/sc2_kbytes_in. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10356 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10357 | src_kbytes_out([<table>]) : integer |
| 10358 | Returns the amount of data sent to the incoming connection's source address |
| 10359 | in the current proxy's stick-table or in the designated stick-table, measured |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10360 | in kilobytes over the period configured in the table. If the address is not |
| 10361 | found, zero is returned. The test is currently performed on 32-bit integers, |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10362 | which limits values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_out. |
Willy Tarreau | a975b8f | 2010-06-05 19:13:27 +0200 | [diff] [blame] | 10363 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10364 | src_port : integer |
| 10365 | Returns an integer value corresponding to the TCP source port of the |
| 10366 | connection on the client side, which is the port the client connected from. |
| 10367 | Usage of this function is very limited as modern protocols do not care much |
| 10368 | about source ports nowadays. |
Willy Tarreau | 079ff0a | 2009-03-05 21:34:28 +0100 | [diff] [blame] | 10369 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10370 | src_sess_cnt([<table>]) : integer |
| 10371 | Returns the cumulated number of connections initiated from the incoming |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10372 | connection's source IPv4 address in the current proxy's stick-table or in the |
| 10373 | designated stick-table, that were transformed into sessions, which means that |
| 10374 | they were accepted by "tcp-request" rules. If the address is not found, zero |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10375 | is returned. See also sc/sc0/sc1/sc2_sess_cnt. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10376 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10377 | src_sess_rate([<table>]) : integer |
| 10378 | Returns the average session rate from the incoming connection's source |
| 10379 | address in the current proxy's stick-table or in the designated stick-table, |
| 10380 | measured in amount of sessions over the period configured in the table. A |
| 10381 | session is a connection that went past the early "tcp-request" rules. If the |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 10382 | address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10383 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10384 | src_updt_conn_cnt([<table>]) : integer |
| 10385 | Creates or updates the entry associated to the incoming connection's source |
| 10386 | address in the current proxy's stick-table or in the designated stick-table. |
| 10387 | This table must be configured to store the "conn_cnt" data type, otherwise |
| 10388 | the match will be ignored. The current count is incremented by one, and the |
| 10389 | expiration timer refreshed. The updated count is returned, so this match |
| 10390 | can't return zero. This was used to reject service abusers based on their |
| 10391 | source address. Note: it is recommended to use the more complete "track-sc*" |
| 10392 | actions in "tcp-request" rules instead. |
Willy Tarreau | a975b8f | 2010-06-05 19:13:27 +0200 | [diff] [blame] | 10393 | |
| 10394 | Example : |
| 10395 | # This frontend limits incoming SSH connections to 3 per 10 second for |
| 10396 | # each source address, and rejects excess connections until a 10 second |
| 10397 | # silence is observed. At most 20 addresses are tracked. |
| 10398 | listen ssh |
| 10399 | bind :22 |
| 10400 | mode tcp |
| 10401 | maxconn 100 |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10402 | stick-table type ip size 20 expire 10s store conn_cnt |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10403 | tcp-request content reject if { src_updt_conn_cnt gt 3 } |
Willy Tarreau | a975b8f | 2010-06-05 19:13:27 +0200 | [diff] [blame] | 10404 | server local 127.0.0.1:22 |
| 10405 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10406 | srv_id : integer |
| 10407 | Returns an integer containing the server's id when processing the response. |
| 10408 | While it's almost only used with ACLs, it may be used for logging or |
| 10409 | debugging. |
Hervé COMMOWICK | daa824e | 2011-08-05 12:09:44 +0200 | [diff] [blame] | 10410 | |
Hervé COMMOWICK | 35ed801 | 2010-12-15 14:04:51 +0100 | [diff] [blame] | 10411 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 10412 | 7.3.4. Fetching samples at Layer 5 |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10413 | ---------------------------------- |
Willy Tarreau | 0b1cd94 | 2010-05-16 22:18:27 +0200 | [diff] [blame] | 10414 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10415 | The layer 5 usually describes just the session layer which in haproxy is |
| 10416 | closest to the session once all the connection handshakes are finished, but |
| 10417 | when no content is yet made available. The fetch methods described here are |
| 10418 | usable as low as the "tcp-request content" rule sets unless they require some |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 10419 | future information. Those generally include the results of SSL negotiations. |
Willy Tarreau | c735a07 | 2011-03-29 00:57:02 +0200 | [diff] [blame] | 10420 | |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 10421 | ssl_bc : boolean |
| 10422 | Returns true when the back connection was made via an SSL/TLS transport |
| 10423 | layer and is locally deciphered. This means the outgoing connection was made |
| 10424 | other a server with the "ssl" option. |
| 10425 | |
| 10426 | ssl_bc_alg_keysize : integer |
| 10427 | Returns the symmetric cipher key size supported in bits when the outgoing |
| 10428 | connection was made over an SSL/TLS transport layer. |
| 10429 | |
| 10430 | ssl_bc_cipher : string |
| 10431 | Returns the name of the used cipher when the outgoing connection was made |
| 10432 | over an SSL/TLS transport layer. |
| 10433 | |
| 10434 | ssl_bc_protocol : string |
| 10435 | Returns the name of the used protocol when the outgoing connection was made |
| 10436 | over an SSL/TLS transport layer. |
| 10437 | |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 10438 | ssl_bc_unique_id : binary |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 10439 | When the outgoing connection was made over an SSL/TLS transport layer, |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 10440 | returns the TLS unique ID as defined in RFC5929 section 3. The unique id |
| 10441 | can be encoded to base64 using the converter: "ssl_bc_unique_id,base64". |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 10442 | |
| 10443 | ssl_bc_session_id : binary |
| 10444 | Returns the SSL ID of the back connection when the outgoing connection was |
| 10445 | made over an SSL/TLS transport layer. It is useful to log if we want to know |
| 10446 | if session was reused or not. |
| 10447 | |
| 10448 | ssl_bc_use_keysize : integer |
| 10449 | Returns the symmetric cipher key size used in bits when the outgoing |
| 10450 | connection was made over an SSL/TLS transport layer. |
| 10451 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10452 | ssl_c_ca_err : integer |
| 10453 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10454 | returns the ID of the first error detected during verification of the client |
| 10455 | certificate at depth > 0, or 0 if no error was encountered during this |
| 10456 | verification process. Please refer to your SSL library's documentation to |
| 10457 | find the exhaustive list of error codes. |
Willy Tarreau | c735a07 | 2011-03-29 00:57:02 +0200 | [diff] [blame] | 10458 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10459 | ssl_c_ca_err_depth : integer |
| 10460 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10461 | returns the depth in the CA chain of the first error detected during the |
| 10462 | verification of the client certificate. If no error is encountered, 0 is |
| 10463 | returned. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 10464 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10465 | ssl_c_err : integer |
| 10466 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10467 | returns the ID of the first error detected during verification at depth 0, or |
| 10468 | 0 if no error was encountered during this verification process. Please refer |
| 10469 | to your SSL library's documentation to find the exhaustive list of error |
| 10470 | codes. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 10471 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10472 | ssl_c_i_dn([<entry>[,<occ>]]) : string |
| 10473 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10474 | returns the full distinguished name of the issuer of the certificate |
| 10475 | presented by the client when no <entry> is specified, or the value of the |
| 10476 | first given entry found from the beginning of the DN. If a positive/negative |
| 10477 | occurrence number is specified as the optional second argument, it returns |
| 10478 | the value of the nth given entry value from the beginning/end of the DN. |
| 10479 | For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and |
| 10480 | "ssl_c_i_dn(CN)" retrieves the common name. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 10481 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10482 | ssl_c_key_alg : string |
| 10483 | Returns the name of the algorithm used to generate the key of the certificate |
| 10484 | presented by the client when the incoming connection was made over an SSL/TLS |
| 10485 | transport layer. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 10486 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10487 | ssl_c_notafter : string |
| 10488 | Returns the end date presented by the client as a formatted string |
| 10489 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 10490 | transport layer. |
Emeric Brun | bede3d0 | 2009-06-30 17:54:00 +0200 | [diff] [blame] | 10491 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10492 | ssl_c_notbefore : string |
| 10493 | Returns the start date presented by the client as a formatted string |
| 10494 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 10495 | transport layer. |
Willy Tarreau | b6672b5 | 2011-12-12 17:23:41 +0100 | [diff] [blame] | 10496 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10497 | ssl_c_s_dn([<entry>[,<occ>]]) : string |
| 10498 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10499 | returns the full distinguished name of the subject of the certificate |
| 10500 | presented by the client when no <entry> is specified, or the value of the |
| 10501 | first given entry found from the beginning of the DN. If a positive/negative |
| 10502 | occurrence number is specified as the optional second argument, it returns |
| 10503 | the value of the nth given entry value from the beginning/end of the DN. |
| 10504 | For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and |
| 10505 | "ssl_c_s_dn(CN)" retrieves the common name. |
Willy Tarreau | b6672b5 | 2011-12-12 17:23:41 +0100 | [diff] [blame] | 10506 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10507 | ssl_c_serial : binary |
| 10508 | Returns the serial of the certificate presented by the client when the |
| 10509 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 10510 | an ACL, the value(s) to match against can be passed in hexadecimal form. |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 10511 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10512 | ssl_c_sha1 : binary |
| 10513 | Returns the SHA-1 fingerprint of the certificate presented by the client when |
| 10514 | the incoming connection was made over an SSL/TLS transport layer. This can be |
| 10515 | used to stick a client to a server, or to pass this information to a server. |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 10516 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10517 | ssl_c_sig_alg : string |
| 10518 | Returns the name of the algorithm used to sign the certificate presented by |
| 10519 | the client when the incoming connection was made over an SSL/TLS transport |
| 10520 | layer. |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 10521 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10522 | ssl_c_used : boolean |
| 10523 | Returns true if current SSL session uses a client certificate even if current |
| 10524 | connection uses SSL session resumption. See also "ssl_fc_has_crt". |
Emeric Brun | 7f56e74 | 2012-10-19 18:15:40 +0200 | [diff] [blame] | 10525 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10526 | ssl_c_verify : integer |
| 10527 | Returns the verify result error ID when the incoming connection was made over |
| 10528 | an SSL/TLS transport layer, otherwise zero if no error is encountered. Please |
| 10529 | refer to your SSL library's documentation for an exhaustive list of error |
| 10530 | codes. |
Emeric Brun | ce5ad80 | 2012-10-22 14:11:22 +0200 | [diff] [blame] | 10531 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10532 | ssl_c_version : integer |
| 10533 | Returns the version of the certificate presented by the client when the |
| 10534 | incoming connection was made over an SSL/TLS transport layer. |
Emeric Brun | ce5ad80 | 2012-10-22 14:11:22 +0200 | [diff] [blame] | 10535 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10536 | ssl_f_i_dn([<entry>[,<occ>]]) : string |
| 10537 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10538 | returns the full distinguished name of the issuer of the certificate |
| 10539 | presented by the frontend when no <entry> is specified, or the value of the |
| 10540 | first given entry found from the beginning of the DN. If a positive/negative |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 10541 | occurrence number is specified as the optional second argument, it returns |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10542 | the value of the nth given entry value from the beginning/end of the DN. |
| 10543 | For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and |
| 10544 | "ssl_f_i_dn(CN)" retrieves the common name. |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 10545 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10546 | ssl_f_key_alg : string |
| 10547 | Returns the name of the algorithm used to generate the key of the certificate |
| 10548 | presented by the frontend when the incoming connection was made over an |
| 10549 | SSL/TLS transport layer. |
Emeric Brun | 7f56e74 | 2012-10-19 18:15:40 +0200 | [diff] [blame] | 10550 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10551 | ssl_f_notafter : string |
| 10552 | Returns the end date presented by the frontend as a formatted string |
| 10553 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 10554 | transport layer. |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 10555 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10556 | ssl_f_notbefore : string |
| 10557 | Returns the start date presented by the frontend as a formatted string |
| 10558 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 10559 | transport layer. |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 10560 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10561 | ssl_f_s_dn([<entry>[,<occ>]]) : string |
| 10562 | When the incoming connection was made over an SSL/TLS transport layer, |
| 10563 | returns the full distinguished name of the subject of the certificate |
| 10564 | presented by the frontend when no <entry> is specified, or the value of the |
| 10565 | first given entry found from the beginning of the DN. If a positive/negative |
| 10566 | occurrence number is specified as the optional second argument, it returns |
| 10567 | the value of the nth given entry value from the beginning/end of the DN. |
| 10568 | For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and |
| 10569 | "ssl_f_s_dn(CN)" retrieves the common name. |
Emeric Brun | ce5ad80 | 2012-10-22 14:11:22 +0200 | [diff] [blame] | 10570 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10571 | ssl_f_serial : binary |
| 10572 | Returns the serial of the certificate presented by the frontend when the |
| 10573 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 10574 | an ACL, the value(s) to match against can be passed in hexadecimal form. |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 10575 | |
Emeric Brun | 55f4fa8 | 2014-04-30 17:11:25 +0200 | [diff] [blame] | 10576 | ssl_f_sha1 : binary |
| 10577 | Returns the SHA-1 fingerprint of the certificate presented by the frontend |
| 10578 | when the incoming connection was made over an SSL/TLS transport layer. This |
| 10579 | can be used to know which certificate was chosen using SNI. |
| 10580 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10581 | ssl_f_sig_alg : string |
| 10582 | Returns the name of the algorithm used to sign the certificate presented by |
| 10583 | the frontend when the incoming connection was made over an SSL/TLS transport |
| 10584 | layer. |
Emeric Brun | 7f56e74 | 2012-10-19 18:15:40 +0200 | [diff] [blame] | 10585 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10586 | ssl_f_version : integer |
| 10587 | Returns the version of the certificate presented by the frontend when the |
| 10588 | incoming connection was made over an SSL/TLS transport layer. |
| 10589 | |
| 10590 | ssl_fc : boolean |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 10591 | Returns true when the front connection was made via an SSL/TLS transport |
| 10592 | layer and is locally deciphered. This means it has matched a socket declared |
| 10593 | with a "bind" line having the "ssl" option. |
| 10594 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10595 | Example : |
| 10596 | # This passes "X-Proto: https" to servers when client connects over SSL |
| 10597 | listen http-https |
| 10598 | bind :80 |
| 10599 | bind :443 ssl crt /etc/haproxy.pem |
| 10600 | http-request add-header X-Proto https if { ssl_fc } |
| 10601 | |
| 10602 | ssl_fc_alg_keysize : integer |
| 10603 | Returns the symmetric cipher key size supported in bits when the incoming |
| 10604 | connection was made over an SSL/TLS transport layer. |
| 10605 | |
| 10606 | ssl_fc_alpn : string |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 10607 | This extracts the Application Layer Protocol Negotiation field from an |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10608 | incoming connection made via a TLS transport layer and locally deciphered by |
| 10609 | haproxy. The result is a string containing the protocol name advertised by |
| 10610 | the client. The SSL library must have been built with support for TLS |
| 10611 | extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is |
| 10612 | not advertised unless the "alpn" keyword on the "bind" line specifies a |
| 10613 | protocol list. Also, nothing forces the client to pick a protocol from this |
| 10614 | list, any other one may be requested. The TLS ALPN extension is meant to |
| 10615 | replace the TLS NPN extension. See also "ssl_fc_npn". |
| 10616 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10617 | ssl_fc_cipher : string |
| 10618 | Returns the name of the used cipher when the incoming connection was made |
| 10619 | over an SSL/TLS transport layer. |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 10620 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10621 | ssl_fc_has_crt : boolean |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 10622 | Returns true if a client certificate is present in an incoming connection over |
| 10623 | SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'. |
Emeric Brun | 9143d37 | 2012-12-20 15:44:16 +0100 | [diff] [blame] | 10624 | Note: on SSL session resumption with Session ID or TLS ticket, client |
| 10625 | certificate is not present in the current connection but may be retrieved |
| 10626 | from the cache or the ticket. So prefer "ssl_c_used" if you want to check if |
| 10627 | current SSL session uses a client certificate. |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 10628 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10629 | ssl_fc_has_sni : boolean |
| 10630 | This checks for the presence of a Server Name Indication TLS extension (SNI) |
Willy Tarreau | f7bc57c | 2012-10-03 00:19:48 +0200 | [diff] [blame] | 10631 | in an incoming connection was made over an SSL/TLS transport layer. Returns |
| 10632 | true when the incoming connection presents a TLS SNI field. This requires |
| 10633 | that the SSL library is build with support for TLS extensions enabled (check |
| 10634 | haproxy -vv). |
Willy Tarreau | 7875d09 | 2012-09-10 08:20:03 +0200 | [diff] [blame] | 10635 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10636 | ssl_fc_npn : string |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 10637 | This extracts the Next Protocol Negotiation field from an incoming connection |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10638 | made via a TLS transport layer and locally deciphered by haproxy. The result |
| 10639 | is a string containing the protocol name advertised by the client. The SSL |
| 10640 | library must have been built with support for TLS extensions enabled (check |
| 10641 | haproxy -vv). Note that the TLS NPN extension is not advertised unless the |
| 10642 | "npn" keyword on the "bind" line specifies a protocol list. Also, nothing |
| 10643 | forces the client to pick a protocol from this list, any other one may be |
| 10644 | requested. Please note that the TLS NPN extension was replaced with ALPN. |
Willy Tarreau | a33c654 | 2012-10-15 13:19:06 +0200 | [diff] [blame] | 10645 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10646 | ssl_fc_protocol : string |
| 10647 | Returns the name of the used protocol when the incoming connection was made |
| 10648 | over an SSL/TLS transport layer. |
Willy Tarreau | 7875d09 | 2012-09-10 08:20:03 +0200 | [diff] [blame] | 10649 | |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 10650 | ssl_fc_unique_id : binary |
David S | c1ad52e | 2014-04-08 18:48:47 -0400 | [diff] [blame] | 10651 | When the incoming connection was made over an SSL/TLS transport layer, |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 10652 | returns the TLS unique ID as defined in RFC5929 section 3. The unique id |
| 10653 | can be encoded to base64 using the converter: "ssl_bc_unique_id,base64". |
David S | c1ad52e | 2014-04-08 18:48:47 -0400 | [diff] [blame] | 10654 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10655 | ssl_fc_session_id : binary |
| 10656 | Returns the SSL ID of the front connection when the incoming connection was |
| 10657 | made over an SSL/TLS transport layer. It is useful to stick a given client to |
| 10658 | a server. It is important to note that some browsers refresh their session ID |
| 10659 | every few minutes. |
Willy Tarreau | 7875d09 | 2012-09-10 08:20:03 +0200 | [diff] [blame] | 10660 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10661 | ssl_fc_sni : string |
| 10662 | This extracts the Server Name Indication TLS extension (SNI) field from an |
| 10663 | incoming connection made via an SSL/TLS transport layer and locally |
| 10664 | deciphered by haproxy. The result (when present) typically is a string |
| 10665 | matching the HTTPS host name (253 chars or less). The SSL library must have |
| 10666 | been built with support for TLS extensions enabled (check haproxy -vv). |
| 10667 | |
| 10668 | This fetch is different from "req_ssl_sni" above in that it applies to the |
| 10669 | connection being deciphered by haproxy and not to SSL contents being blindly |
| 10670 | forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This |
Cyril Bonté | 9c1eb1e | 2012-10-09 22:45:34 +0200 | [diff] [blame] | 10671 | requires that the SSL library is build with support for TLS extensions |
| 10672 | enabled (check haproxy -vv). |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 10673 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10674 | ACL derivatives : |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10675 | ssl_fc_sni_end : suffix match |
| 10676 | ssl_fc_sni_reg : regex match |
Emeric Brun | 589fcad | 2012-10-16 14:13:26 +0200 | [diff] [blame] | 10677 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10678 | ssl_fc_use_keysize : integer |
| 10679 | Returns the symmetric cipher key size used in bits when the incoming |
| 10680 | connection was made over an SSL/TLS transport layer. |
Willy Tarreau | b6fb420 | 2008-07-20 11:18:28 +0200 | [diff] [blame] | 10681 | |
Willy Tarreau | b6fb420 | 2008-07-20 11:18:28 +0200 | [diff] [blame] | 10682 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 10683 | 7.3.5. Fetching samples from buffer contents (Layer 6) |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10684 | ------------------------------------------------------ |
Willy Tarreau | b6fb420 | 2008-07-20 11:18:28 +0200 | [diff] [blame] | 10685 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10686 | Fetching samples from buffer contents is a bit different from the previous |
| 10687 | sample fetches above because the sampled data are ephemeral. These data can |
| 10688 | only be used when they're available and will be lost when they're forwarded. |
| 10689 | For this reason, samples fetched from buffer contents during a request cannot |
| 10690 | be used in a response for example. Even while the data are being fetched, they |
| 10691 | can change. Sometimes it is necessary to set some delays or combine multiple |
| 10692 | sample fetch methods to ensure that the expected data are complete and usable, |
| 10693 | for example through TCP request content inspection. Please see the "tcp-request |
| 10694 | content" keyword for more detailed information on the subject. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 10695 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10696 | payload(<offset>,<length>) : binary (deprecated) |
| 10697 | This is an alias for "req.payload" when used in the context of a request (eg: |
| 10698 | "stick on", "stick match"), and for "res.payload" when used in the context of |
| 10699 | a response such as in "stick store response". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 10700 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10701 | payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated) |
| 10702 | This is an alias for "req.payload_lv" when used in the context of a request |
| 10703 | (eg: "stick on", "stick match"), and for "res.payload_lv" when used in the |
| 10704 | context of a response such as in "stick store response". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 10705 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10706 | req.len : integer |
| 10707 | req_len : integer (deprecated) |
| 10708 | Returns an integer value corresponding to the number of bytes present in the |
| 10709 | request buffer. This is mostly used in ACL. It is important to understand |
| 10710 | that this test does not return false as long as the buffer is changing. This |
| 10711 | means that a check with equality to zero will almost always immediately match |
| 10712 | at the beginning of the session, while a test for more data will wait for |
| 10713 | that data to come in and return false only when haproxy is certain that no |
| 10714 | more data will come in. This test was designed to be used with TCP request |
| 10715 | content inspection. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10716 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10717 | req.payload(<offset>,<length>) : binary |
| 10718 | This extracts a binary block of <length> bytes and starting at byte <offset> |
Willy Tarreau | 00f0084 | 2013-08-02 11:07:32 +0200 | [diff] [blame] | 10719 | in the request buffer. As a special case, if the <length> argument is zero, |
| 10720 | the the whole buffer from <offset> to the end is extracted. This can be used |
| 10721 | with ACLs in order to check for the presence of some content in a buffer at |
| 10722 | any location. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10723 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10724 | ACL alternatives : |
| 10725 | payload(<offset>,<length>) : hex binary match |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10726 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10727 | req.payload_lv(<offset1>,<length>[,<offset2>]) : binary |
| 10728 | This extracts a binary block whose size is specified at <offset1> for <length> |
| 10729 | bytes, and which starts at <offset2> if specified or just after the length in |
| 10730 | the request buffer. The <offset2> parameter also supports relative offsets if |
| 10731 | prepended with a '+' or '-' sign. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10732 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10733 | ACL alternatives : |
| 10734 | payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10735 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10736 | Example : please consult the example from the "stick store-response" keyword. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10737 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10738 | req.proto_http : boolean |
| 10739 | req_proto_http : boolean (deprecated) |
| 10740 | Returns true when data in the request buffer look like HTTP and correctly |
| 10741 | parses as such. It is the same parser as the common HTTP request parser which |
| 10742 | is used so there should be no surprises. The test does not match until the |
| 10743 | request is complete, failed or timed out. This test may be used to report the |
| 10744 | protocol in TCP logs, but the biggest use is to block TCP request analysis |
| 10745 | until a complete HTTP request is present in the buffer, for example to track |
| 10746 | a header. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10747 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10748 | Example: |
| 10749 | # track request counts per "base" (concatenation of Host+URL) |
| 10750 | tcp-request inspect-delay 10s |
| 10751 | tcp-request content reject if !HTTP |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 10752 | tcp-request content track-sc0 base table req-rate |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 10753 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10754 | req.rdp_cookie([<name>]) : string |
| 10755 | rdp_cookie([<name>]) : string (deprecated) |
| 10756 | When the request buffer looks like the RDP protocol, extracts the RDP cookie |
| 10757 | <name>, or any cookie if unspecified. The parser only checks for the first |
| 10758 | cookie, as illustrated in the RDP protocol specification. The cookie name is |
| 10759 | case insensitive. Generally the "MSTS" cookie name will be used, as it can |
| 10760 | contain the user name of the client connecting to the server if properly |
| 10761 | configured on the client. The "MSTSHASH" cookie is often used as well for |
| 10762 | session stickiness to servers. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10763 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10764 | This differs from "balance rdp-cookie" in that any balancing algorithm may be |
| 10765 | used and thus the distribution of clients to backend servers is not linked to |
| 10766 | a hash of the RDP cookie. It is envisaged that using a balancing algorithm |
| 10767 | such as "balance roundrobin" or "balance leastconn" will lead to a more even |
| 10768 | distribution of clients to backend servers than the hash used by "balance |
| 10769 | rdp-cookie". |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10770 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10771 | ACL derivatives : |
| 10772 | req_rdp_cookie([<name>]) : exact string match |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10773 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10774 | Example : |
| 10775 | listen tse-farm |
| 10776 | bind 0.0.0.0:3389 |
| 10777 | # wait up to 5s for an RDP cookie in the request |
| 10778 | tcp-request inspect-delay 5s |
| 10779 | tcp-request content accept if RDP_COOKIE |
| 10780 | # apply RDP cookie persistence |
| 10781 | persist rdp-cookie |
| 10782 | # Persist based on the mstshash cookie |
| 10783 | # This is only useful makes sense if |
| 10784 | # balance rdp-cookie is not used |
| 10785 | stick-table type string size 204800 |
| 10786 | stick on req.rdp_cookie(mstshash) |
| 10787 | server srv1 1.1.1.1:3389 |
| 10788 | server srv1 1.1.1.2:3389 |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10789 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10790 | See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the |
| 10791 | "req_rdp_cookie" ACL. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10792 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10793 | req.rdp_cookie_cnt([name]) : integer |
| 10794 | rdp_cookie_cnt([name]) : integer (deprecated) |
| 10795 | Tries to parse the request buffer as RDP protocol, then returns an integer |
| 10796 | corresponding to the number of RDP cookies found. If an optional cookie name |
| 10797 | is passed, only cookies matching this name are considered. This is mostly |
| 10798 | used in ACL. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10799 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10800 | ACL derivatives : |
| 10801 | req_rdp_cookie_cnt([<name>]) : integer match |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10802 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10803 | req.ssl_hello_type : integer |
| 10804 | req_ssl_hello_type : integer (deprecated) |
| 10805 | Returns an integer value containing the type of the SSL hello message found |
| 10806 | in the request buffer if the buffer contains data that parse as a complete |
| 10807 | SSL (v3 or superior) client hello message. Note that this only applies to raw |
| 10808 | contents found in the request buffer and not to contents deciphered via an |
| 10809 | SSL data layer, so this will not work with "bind" lines having the "ssl" |
| 10810 | option. This is mostly used in ACL to detect presence of an SSL hello message |
| 10811 | that is supposed to contain an SSL session ID usable for stickiness. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10812 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10813 | req.ssl_sni : string |
| 10814 | req_ssl_sni : string (deprecated) |
| 10815 | Returns a string containing the value of the Server Name TLS extension sent |
| 10816 | by a client in a TLS stream passing through the request buffer if the buffer |
| 10817 | contains data that parse as a complete SSL (v3 or superior) client hello |
| 10818 | message. Note that this only applies to raw contents found in the request |
| 10819 | buffer and not to contents deciphered via an SSL data layer, so this will not |
| 10820 | work with "bind" lines having the "ssl" option. SNI normally contains the |
| 10821 | name of the host the client tries to connect to (for recent browsers). SNI is |
| 10822 | useful for allowing or denying access to certain hosts when SSL/TLS is used |
| 10823 | by the client. This test was designed to be used with TCP request content |
| 10824 | inspection. If content switching is needed, it is recommended to first wait |
| 10825 | for a complete client hello (type 1), like in the example below. See also |
| 10826 | "ssl_fc_sni". |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10827 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10828 | ACL derivatives : |
| 10829 | req_ssl_sni : exact string match |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10830 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10831 | Examples : |
| 10832 | # Wait for a client hello for at most 5 seconds |
| 10833 | tcp-request inspect-delay 5s |
| 10834 | tcp-request content accept if { req_ssl_hello_type 1 } |
| 10835 | use_backend bk_allow if { req_ssl_sni -f allowed_sites } |
| 10836 | default_backend bk_sorry_page |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 10837 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10838 | res.ssl_hello_type : integer |
| 10839 | rep_ssl_hello_type : integer (deprecated) |
| 10840 | Returns an integer value containing the type of the SSL hello message found |
| 10841 | in the response buffer if the buffer contains data that parses as a complete |
| 10842 | SSL (v3 or superior) hello message. Note that this only applies to raw |
| 10843 | contents found in the response buffer and not to contents deciphered via an |
| 10844 | SSL data layer, so this will not work with "server" lines having the "ssl" |
| 10845 | option. This is mostly used in ACL to detect presence of an SSL hello message |
| 10846 | that is supposed to contain an SSL session ID usable for stickiness. |
Willy Tarreau | 5153936 | 2012-05-08 12:46:28 +0200 | [diff] [blame] | 10847 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10848 | req.ssl_ver : integer |
| 10849 | req_ssl_ver : integer (deprecated) |
| 10850 | Returns an integer value containing the version of the SSL/TLS protocol of a |
| 10851 | stream present in the request buffer. Both SSLv2 hello messages and SSLv3 |
| 10852 | messages are supported. TLSv1 is announced as SSL version 3.1. The value is |
| 10853 | composed of the major version multiplied by 65536, added to the minor |
| 10854 | version. Note that this only applies to raw contents found in the request |
| 10855 | buffer and not to contents deciphered via an SSL data layer, so this will not |
| 10856 | work with "bind" lines having the "ssl" option. The ACL version of the test |
| 10857 | matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). This |
| 10858 | fetch is mostly used in ACL. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10859 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10860 | ACL derivatives : |
| 10861 | req_ssl_ver : decimal match |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10862 | |
Willy Tarreau | 47e8eba | 2013-09-11 23:28:46 +0200 | [diff] [blame] | 10863 | res.len : integer |
| 10864 | Returns an integer value corresponding to the number of bytes present in the |
| 10865 | response buffer. This is mostly used in ACL. It is important to understand |
| 10866 | that this test does not return false as long as the buffer is changing. This |
| 10867 | means that a check with equality to zero will almost always immediately match |
| 10868 | at the beginning of the session, while a test for more data will wait for |
| 10869 | that data to come in and return false only when haproxy is certain that no |
| 10870 | more data will come in. This test was designed to be used with TCP response |
| 10871 | content inspection. |
| 10872 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10873 | res.payload(<offset>,<length>) : binary |
| 10874 | This extracts a binary block of <length> bytes and starting at byte <offset> |
Willy Tarreau | 00f0084 | 2013-08-02 11:07:32 +0200 | [diff] [blame] | 10875 | in the response buffer. As a special case, if the <length> argument is zero, |
| 10876 | the the whole buffer from <offset> to the end is extracted. This can be used |
| 10877 | with ACLs in order to check for the presence of some content in a buffer at |
| 10878 | any location. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10879 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10880 | res.payload_lv(<offset1>,<length>[,<offset2>]) : binary |
| 10881 | This extracts a binary block whose size is specified at <offset1> for <length> |
| 10882 | bytes, and which starts at <offset2> if specified or just after the length in |
| 10883 | the response buffer. The <offset2> parameter also supports relative offsets |
| 10884 | if prepended with a '+' or '-' sign. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10885 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10886 | Example : please consult the example from the "stick store-response" keyword. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10887 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10888 | wait_end : boolean |
| 10889 | This fetch either returns true when the inspection period is over, or does |
| 10890 | not fetch. It is only used in ACLs, in conjunction with content analysis to |
| 10891 | avoid returning a wrong verdict early. It may also be used to delay some |
| 10892 | actions, such as a delayed reject for some special addresses. Since it either |
| 10893 | stops the rules evaluation or immediately returns true, it is recommended to |
| 10894 | use this acl as the last one in a rule. Please note that the default ACL |
| 10895 | "WAIT_END" is always usable without prior declaration. This test was designed |
| 10896 | to be used with TCP request content inspection. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10897 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10898 | Examples : |
| 10899 | # delay every incoming request by 2 seconds |
| 10900 | tcp-request inspect-delay 2s |
| 10901 | tcp-request content accept if WAIT_END |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10902 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10903 | # don't immediately tell bad guys they are rejected |
| 10904 | tcp-request inspect-delay 10s |
| 10905 | acl goodguys src 10.0.0.0/24 |
| 10906 | acl badguys src 10.0.1.0/24 |
| 10907 | tcp-request content accept if goodguys |
| 10908 | tcp-request content reject if badguys WAIT_END |
| 10909 | tcp-request content reject |
| 10910 | |
| 10911 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 10912 | 7.3.6. Fetching HTTP samples (Layer 7) |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10913 | -------------------------------------- |
| 10914 | |
| 10915 | It is possible to fetch samples from HTTP contents, requests and responses. |
| 10916 | This application layer is also called layer 7. It is only possible to fetch the |
| 10917 | data in this section when a full HTTP request or response has been parsed from |
| 10918 | its respective request or response buffer. This is always the case with all |
| 10919 | HTTP specific rules and for sections running with "mode http". When using TCP |
| 10920 | content inspection, it may be necessary to support an inspection delay in order |
| 10921 | to let the request or response come in first. These fetches may require a bit |
| 10922 | more CPU resources than the layer 4 ones, but not much since the request and |
| 10923 | response are indexed. |
| 10924 | |
| 10925 | base : string |
| 10926 | This returns the concatenation of the first Host header and the path part of |
| 10927 | the request, which starts at the first slash and ends before the question |
| 10928 | mark. It can be useful in virtual hosted environments to detect URL abuses as |
| 10929 | well as to improve shared caches efficiency. Using this with a limited size |
| 10930 | stick table also allows one to collect statistics about most commonly |
| 10931 | requested objects by host/path. With ACLs it can allow simple content |
| 10932 | switching rules involving the host and the path at the same time, such as |
| 10933 | "www.example.com/favicon.ico". See also "path" and "uri". |
| 10934 | |
| 10935 | ACL derivatives : |
| 10936 | base : exact string match |
| 10937 | base_beg : prefix match |
| 10938 | base_dir : subdir match |
| 10939 | base_dom : domain match |
| 10940 | base_end : suffix match |
| 10941 | base_len : length match |
| 10942 | base_reg : regex match |
| 10943 | base_sub : substring match |
| 10944 | |
| 10945 | base32 : integer |
| 10946 | This returns a 32-bit hash of the value returned by the "base" fetch method |
| 10947 | above. This is useful to track per-URL activity on high traffic sites without |
| 10948 | having to store all URLs. Instead a shorter hash is stored, saving a lot of |
| 10949 | memory. The output type is an unsigned integer. |
| 10950 | |
| 10951 | base32+src : binary |
| 10952 | This returns the concatenation of the base32 fetch above and the src fetch |
| 10953 | below. The resulting type is of type binary, with a size of 8 or 20 bytes |
| 10954 | depending on the source address family. This can be used to track per-IP, |
| 10955 | per-URL counters. |
| 10956 | |
William Lallemand | 65ad6e1 | 2014-01-31 15:08:02 +0100 | [diff] [blame] | 10957 | capture.req.hdr(<idx>) : string |
| 10958 | This extracts the content of the header captured by the "capture request |
| 10959 | header", idx is the position of the capture keyword in the configuration. |
| 10960 | The first entry is an index of 0. See also: "capture request header". |
| 10961 | |
| 10962 | capture.req.method : string |
| 10963 | This extracts the METHOD of an HTTP request. It can be used in both request |
| 10964 | and response. Unlike "method", it can be used in both request and response |
| 10965 | because it's allocated. |
| 10966 | |
| 10967 | capture.req.uri : string |
| 10968 | This extracts the request's URI, which starts at the first slash and ends |
| 10969 | before the first space in the request (without the host part). Unlike "path" |
| 10970 | and "url", it can be used in both request and response because it's |
| 10971 | allocated. |
| 10972 | |
Willy Tarreau | 3c1b5ec | 2014-04-24 23:41:57 +0200 | [diff] [blame] | 10973 | capture.req.ver : string |
| 10974 | This extracts the request's HTTP version and returns either "HTTP/1.0" or |
| 10975 | "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and |
| 10976 | logs because it relies on a persistent flag. |
| 10977 | |
William Lallemand | 65ad6e1 | 2014-01-31 15:08:02 +0100 | [diff] [blame] | 10978 | capture.res.hdr(<idx>) : string |
| 10979 | This extracts the content of the header captured by the "capture response |
| 10980 | header", idx is the position of the capture keyword in the configuration. |
| 10981 | The first entry is an index of 0. |
| 10982 | See also: "capture response header" |
| 10983 | |
Willy Tarreau | 3c1b5ec | 2014-04-24 23:41:57 +0200 | [diff] [blame] | 10984 | capture.res.ver : string |
| 10985 | This extracts the response's HTTP version and returns either "HTTP/1.0" or |
| 10986 | "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a |
| 10987 | persistent flag. |
| 10988 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 10989 | req.cook([<name>]) : string |
| 10990 | cook([<name>]) : string (deprecated) |
| 10991 | This extracts the last occurrence of the cookie name <name> on a "Cookie" |
| 10992 | header line from the request, and returns its value as string. If no name is |
| 10993 | specified, the first cookie value is returned. When used with ACLs, all |
| 10994 | matching cookies are evaluated. Spaces around the name and the value are |
| 10995 | ignored as requested by the Cookie header specification (RFC6265). The cookie |
| 10996 | name is case-sensitive. Empty cookies are valid, so an empty cookie may very |
| 10997 | well return an empty value if it is present. Use the "found" match to detect |
| 10998 | presence. Use the res.cook() variant for response cookies sent by the server. |
| 10999 | |
| 11000 | ACL derivatives : |
| 11001 | cook([<name>]) : exact string match |
| 11002 | cook_beg([<name>]) : prefix match |
| 11003 | cook_dir([<name>]) : subdir match |
| 11004 | cook_dom([<name>]) : domain match |
| 11005 | cook_end([<name>]) : suffix match |
| 11006 | cook_len([<name>]) : length match |
| 11007 | cook_reg([<name>]) : regex match |
| 11008 | cook_sub([<name>]) : substring match |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11009 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11010 | req.cook_cnt([<name>]) : integer |
| 11011 | cook_cnt([<name>]) : integer (deprecated) |
| 11012 | Returns an integer value representing the number of occurrences of the cookie |
| 11013 | <name> in the request, or all cookies if <name> is not specified. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11014 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11015 | req.cook_val([<name>]) : integer |
| 11016 | cook_val([<name>]) : integer (deprecated) |
| 11017 | This extracts the last occurrence of the cookie name <name> on a "Cookie" |
| 11018 | header line from the request, and converts its value to an integer which is |
| 11019 | returned. If no name is specified, the first cookie value is returned. When |
| 11020 | used in ACLs, all matching names are iterated over until a value matches. |
Willy Tarreau | 0e69854 | 2011-09-16 08:32:32 +0200 | [diff] [blame] | 11021 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11022 | cookie([<name>]) : string (deprecated) |
| 11023 | This extracts the last occurrence of the cookie name <name> on a "Cookie" |
| 11024 | header line from the request, or a "Set-Cookie" header from the response, and |
| 11025 | returns its value as a string. A typical use is to get multiple clients |
| 11026 | sharing a same profile use the same server. This can be similar to what |
| 11027 | "appsession" does with the "request-learn" statement, but with support for |
| 11028 | multi-peer synchronization and state keeping across restarts. If no name is |
| 11029 | specified, the first cookie value is returned. This fetch should not be used |
| 11030 | anymore and should be replaced by req.cook() or res.cook() instead as it |
| 11031 | ambiguously uses the direction based on the context where it is used. |
| 11032 | See also : "appsession". |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11033 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11034 | hdr([<name>[,<occ>]]) : string |
| 11035 | This is equivalent to req.hdr() when used on requests, and to res.hdr() when |
| 11036 | used on responses. Please refer to these respective fetches for more details. |
| 11037 | In case of doubt about the fetch direction, please use the explicit ones. |
| 11038 | Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 11039 | unambiguously apply to the request headers. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11040 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11041 | req.fhdr(<name>[,<occ>]) : string |
| 11042 | This extracts the last occurrence of header <name> in an HTTP request. When |
| 11043 | used from an ACL, all occurrences are iterated over until a match is found. |
| 11044 | Optionally, a specific occurrence might be specified as a position number. |
| 11045 | Positive values indicate a position from the first occurrence, with 1 being |
| 11046 | the first one. Negative values indicate positions relative to the last one, |
| 11047 | with -1 being the last one. It differs from req.hdr() in that any commas |
| 11048 | present in the value are returned and are not used as delimiters. This is |
| 11049 | sometimes useful with headers such as User-Agent. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11050 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11051 | req.fhdr_cnt([<name>]) : integer |
| 11052 | Returns an integer value representing the number of occurrences of request |
| 11053 | header field name <name>, or the total number of header fields if <name> is |
| 11054 | not specified. Contrary to its req.hdr_cnt() cousin, this function returns |
| 11055 | the number of full line headers and does not stop on commas. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11056 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11057 | req.hdr([<name>[,<occ>]]) : string |
| 11058 | This extracts the last occurrence of header <name> in an HTTP request. When |
| 11059 | used from an ACL, all occurrences are iterated over until a match is found. |
| 11060 | Optionally, a specific occurrence might be specified as a position number. |
| 11061 | Positive values indicate a position from the first occurrence, with 1 being |
| 11062 | the first one. Negative values indicate positions relative to the last one, |
| 11063 | with -1 being the last one. A typical use is with the X-Forwarded-For header |
| 11064 | once converted to IP, associated with an IP stick-table. The function |
| 11065 | considers any comma as a delimiter for distinct values. If full-line headers |
| 11066 | are desired instead, use req.fhdr(). Please carefully check RFC2616 to know |
| 11067 | how certain headers are supposed to be parsed. Also, some of them are case |
| 11068 | insensitive (eg: Connection). |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11069 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11070 | ACL derivatives : |
| 11071 | hdr([<name>[,<occ>]]) : exact string match |
| 11072 | hdr_beg([<name>[,<occ>]]) : prefix match |
| 11073 | hdr_dir([<name>[,<occ>]]) : subdir match |
| 11074 | hdr_dom([<name>[,<occ>]]) : domain match |
| 11075 | hdr_end([<name>[,<occ>]]) : suffix match |
| 11076 | hdr_len([<name>[,<occ>]]) : length match |
| 11077 | hdr_reg([<name>[,<occ>]]) : regex match |
| 11078 | hdr_sub([<name>[,<occ>]]) : substring match |
| 11079 | |
| 11080 | req.hdr_cnt([<name>]) : integer |
| 11081 | hdr_cnt([<header>]) : integer (deprecated) |
| 11082 | Returns an integer value representing the number of occurrences of request |
| 11083 | header field name <name>, or the total number of header field values if |
| 11084 | <name> is not specified. It is important to remember that one header line may |
| 11085 | count as several headers if it has several values. The function considers any |
| 11086 | comma as a delimiter for distinct values. If full-line headers are desired |
| 11087 | instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to |
| 11088 | detect presence, absence or abuse of a specific header, as well as to block |
| 11089 | request smuggling attacks by rejecting requests which contain more than one |
| 11090 | of certain headers. See "req.hdr" for more information on header matching. |
| 11091 | |
| 11092 | req.hdr_ip([<name>[,<occ>]]) : ip |
| 11093 | hdr_ip([<name>[,<occ>]]) : ip (deprecated) |
| 11094 | This extracts the last occurrence of header <name> in an HTTP request, |
| 11095 | converts it to an IPv4 or IPv6 address and returns this address. When used |
| 11096 | with ACLs, all occurrences are checked, and if <name> is omitted, every value |
| 11097 | of every header is checked. Optionally, a specific occurrence might be |
| 11098 | specified as a position number. Positive values indicate a position from the |
| 11099 | first occurrence, with 1 being the first one. Negative values indicate |
| 11100 | positions relative to the last one, with -1 being the last one. A typical use |
| 11101 | is with the X-Forwarded-For and X-Client-IP headers. |
| 11102 | |
| 11103 | req.hdr_val([<name>[,<occ>]]) : integer |
| 11104 | hdr_val([<name>[,<occ>]]) : integer (deprecated) |
| 11105 | This extracts the last occurrence of header <name> in an HTTP request, and |
| 11106 | converts it to an integer value. When used with ACLs, all occurrences are |
| 11107 | checked, and if <name> is omitted, every value of every header is checked. |
| 11108 | Optionally, a specific occurrence might be specified as a position number. |
| 11109 | Positive values indicate a position from the first occurrence, with 1 being |
| 11110 | the first one. Negative values indicate positions relative to the last one, |
| 11111 | with -1 being the last one. A typical use is with the X-Forwarded-For header. |
| 11112 | |
| 11113 | http_auth(<userlist>) : boolean |
| 11114 | Returns a boolean indicating whether the authentication data received from |
| 11115 | the client match a username & password stored in the specified userlist. This |
| 11116 | fetch function is not really useful outside of ACLs. Currently only http |
| 11117 | basic auth is supported. |
| 11118 | |
Thierry FOURNIER | 9eec0a6 | 2014-01-22 18:38:02 +0100 | [diff] [blame] | 11119 | http_auth_group(<userlist>) : string |
| 11120 | Returns a string corresponding to the user name found in the authentication |
| 11121 | data received from the client if both the user name and password are valid |
| 11122 | according to the specified userlist. The main purpose is to use it in ACLs |
| 11123 | where it is then checked whether the user belongs to any group within a list. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11124 | This fetch function is not really useful outside of ACLs. Currently only http |
| 11125 | basic auth is supported. |
| 11126 | |
| 11127 | ACL derivatives : |
Thierry FOURNIER | 9eec0a6 | 2014-01-22 18:38:02 +0100 | [diff] [blame] | 11128 | http_auth_group(<userlist>) : group ... |
| 11129 | Returns true when the user extracted from the request and whose password is |
| 11130 | valid according to the specified userlist belongs to at least one of the |
| 11131 | groups. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11132 | |
| 11133 | http_first_req : boolean |
Willy Tarreau | 7f18e52 | 2010-10-22 20:04:13 +0200 | [diff] [blame] | 11134 | Returns true when the request being processed is the first one of the |
| 11135 | connection. This can be used to add or remove headers that may be missing |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11136 | from some requests when a request is not the first one, or to help grouping |
| 11137 | requests in the logs. |
Willy Tarreau | 7f18e52 | 2010-10-22 20:04:13 +0200 | [diff] [blame] | 11138 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11139 | method : integer + string |
| 11140 | Returns an integer value corresponding to the method in the HTTP request. For |
| 11141 | example, "GET" equals 1 (check sources to establish the matching). Value 9 |
| 11142 | means "other method" and may be converted to a string extracted from the |
| 11143 | stream. This should not be used directly as a sample, this is only meant to |
| 11144 | be used from ACLs, which transparently convert methods from patterns to these |
| 11145 | integer + string values. Some predefined ACL already check for most common |
| 11146 | methods. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11147 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11148 | ACL derivatives : |
| 11149 | method : case insensitive method match |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11150 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11151 | Example : |
| 11152 | # only accept GET and HEAD requests |
| 11153 | acl valid_method method GET HEAD |
| 11154 | http-request deny if ! valid_method |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11155 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11156 | path : string |
| 11157 | This extracts the request's URL path, which starts at the first slash and |
| 11158 | ends before the question mark (without the host part). A typical use is with |
| 11159 | prefetch-capable caches, and with portals which need to aggregate multiple |
| 11160 | information from databases and keep them in caches. Note that with outgoing |
| 11161 | caches, it would be wiser to use "url" instead. With ACLs, it's typically |
| 11162 | used to match exact file names (eg: "/login.php"), or directory parts using |
| 11163 | the derivative forms. See also the "url" and "base" fetch methods. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11164 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11165 | ACL derivatives : |
| 11166 | path : exact string match |
| 11167 | path_beg : prefix match |
| 11168 | path_dir : subdir match |
| 11169 | path_dom : domain match |
| 11170 | path_end : suffix match |
| 11171 | path_len : length match |
| 11172 | path_reg : regex match |
| 11173 | path_sub : substring match |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11174 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11175 | req.ver : string |
| 11176 | req_ver : string (deprecated) |
| 11177 | Returns the version string from the HTTP request, for example "1.1". This can |
| 11178 | be useful for logs, but is mostly there for ACL. Some predefined ACL already |
| 11179 | check for versions 1.0 and 1.1. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11180 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11181 | ACL derivatives : |
| 11182 | req_ver : exact string match |
Willy Tarreau | 0e69854 | 2011-09-16 08:32:32 +0200 | [diff] [blame] | 11183 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11184 | res.comp : boolean |
| 11185 | Returns the boolean "true" value if the response has been compressed by |
| 11186 | HAProxy, otherwise returns boolean "false". This may be used to add |
| 11187 | information in the logs. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11188 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11189 | res.comp_algo : string |
| 11190 | Returns a string containing the name of the algorithm used if the response |
| 11191 | was compressed by HAProxy, for example : "deflate". This may be used to add |
| 11192 | some information in the logs. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11193 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11194 | res.cook([<name>]) : string |
| 11195 | scook([<name>]) : string (deprecated) |
| 11196 | This extracts the last occurrence of the cookie name <name> on a "Set-Cookie" |
| 11197 | header line from the response, and returns its value as string. If no name is |
| 11198 | specified, the first cookie value is returned. |
Willy Tarreau | 0ce3aa0 | 2012-04-25 18:46:33 +0200 | [diff] [blame] | 11199 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11200 | ACL derivatives : |
| 11201 | scook([<name>] : exact string match |
Willy Tarreau | 0ce3aa0 | 2012-04-25 18:46:33 +0200 | [diff] [blame] | 11202 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11203 | res.cook_cnt([<name>]) : integer |
| 11204 | scook_cnt([<name>]) : integer (deprecated) |
| 11205 | Returns an integer value representing the number of occurrences of the cookie |
| 11206 | <name> in the response, or all cookies if <name> is not specified. This is |
| 11207 | mostly useful when combined with ACLs to detect suspicious responses. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11208 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11209 | res.cook_val([<name>]) : integer |
| 11210 | scook_val([<name>]) : integer (deprecated) |
| 11211 | This extracts the last occurrence of the cookie name <name> on a "Set-Cookie" |
| 11212 | header line from the response, and converts its value to an integer which is |
| 11213 | returned. If no name is specified, the first cookie value is returned. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11214 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11215 | res.fhdr([<name>[,<occ>]]) : string |
| 11216 | This extracts the last occurrence of header <name> in an HTTP response, or of |
| 11217 | the last header if no <name> is specified. Optionally, a specific occurrence |
| 11218 | might be specified as a position number. Positive values indicate a position |
| 11219 | from the first occurrence, with 1 being the first one. Negative values |
| 11220 | indicate positions relative to the last one, with -1 being the last one. It |
| 11221 | differs from res.hdr() in that any commas present in the value are returned |
| 11222 | and are not used as delimiters. If this is not desired, the res.hdr() fetch |
| 11223 | should be used instead. This is sometimes useful with headers such as Date or |
| 11224 | Expires. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11225 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11226 | res.fhdr_cnt([<name>]) : integer |
| 11227 | Returns an integer value representing the number of occurrences of response |
| 11228 | header field name <name>, or the total number of header fields if <name> is |
| 11229 | not specified. Contrary to its res.hdr_cnt() cousin, this function returns |
| 11230 | the number of full line headers and does not stop on commas. If this is not |
| 11231 | desired, the res.hdr_cnt() fetch should be used instead. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11232 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11233 | res.hdr([<name>[,<occ>]]) : string |
| 11234 | shdr([<name>[,<occ>]]) : string (deprecated) |
| 11235 | This extracts the last occurrence of header <name> in an HTTP response, or of |
| 11236 | the last header if no <name> is specified. Optionally, a specific occurrence |
| 11237 | might be specified as a position number. Positive values indicate a position |
| 11238 | from the first occurrence, with 1 being the first one. Negative values |
| 11239 | indicate positions relative to the last one, with -1 being the last one. This |
| 11240 | can be useful to learn some data into a stick-table. The function considers |
| 11241 | any comma as a delimiter for distinct values. If this is not desired, the |
| 11242 | res.fhdr() fetch should be used instead. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11243 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11244 | ACL derivatives : |
| 11245 | shdr([<name>[,<occ>]]) : exact string match |
| 11246 | shdr_beg([<name>[,<occ>]]) : prefix match |
| 11247 | shdr_dir([<name>[,<occ>]]) : subdir match |
| 11248 | shdr_dom([<name>[,<occ>]]) : domain match |
| 11249 | shdr_end([<name>[,<occ>]]) : suffix match |
| 11250 | shdr_len([<name>[,<occ>]]) : length match |
| 11251 | shdr_reg([<name>[,<occ>]]) : regex match |
| 11252 | shdr_sub([<name>[,<occ>]]) : substring match |
| 11253 | |
| 11254 | res.hdr_cnt([<name>]) : integer |
| 11255 | shdr_cnt([<name>]) : integer (deprecated) |
| 11256 | Returns an integer value representing the number of occurrences of response |
| 11257 | header field name <name>, or the total number of header fields if <name> is |
| 11258 | not specified. The function considers any comma as a delimiter for distinct |
| 11259 | values. If this is not desired, the res.fhdr_cnt() fetch should be used |
| 11260 | instead. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11261 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11262 | res.hdr_ip([<name>[,<occ>]]) : ip |
| 11263 | shdr_ip([<name>[,<occ>]]) : ip (deprecated) |
| 11264 | This extracts the last occurrence of header <name> in an HTTP response, |
| 11265 | convert it to an IPv4 or IPv6 address and returns this address. Optionally, a |
| 11266 | specific occurrence might be specified as a position number. Positive values |
| 11267 | indicate a position from the first occurrence, with 1 being the first one. |
| 11268 | Negative values indicate positions relative to the last one, with -1 being |
| 11269 | the last one. This can be useful to learn some data into a stick table. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 11270 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11271 | res.hdr_val([<name>[,<occ>]]) : integer |
| 11272 | shdr_val([<name>[,<occ>]]) : integer (deprecated) |
| 11273 | This extracts the last occurrence of header <name> in an HTTP response, and |
| 11274 | converts it to an integer value. Optionally, a specific occurrence might be |
| 11275 | specified as a position number. Positive values indicate a position from the |
| 11276 | first occurrence, with 1 being the first one. Negative values indicate |
| 11277 | positions relative to the last one, with -1 being the last one. This can be |
| 11278 | useful to learn some data into a stick table. |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 11279 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11280 | res.ver : string |
| 11281 | resp_ver : string (deprecated) |
| 11282 | Returns the version string from the HTTP response, for example "1.1". This |
| 11283 | can be useful for logs, but is mostly there for ACL. |
Willy Tarreau | 0e69854 | 2011-09-16 08:32:32 +0200 | [diff] [blame] | 11284 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11285 | ACL derivatives : |
| 11286 | resp_ver : exact string match |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 11287 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11288 | set-cookie([<name>]) : string (deprecated) |
| 11289 | This extracts the last occurrence of the cookie name <name> on a "Set-Cookie" |
| 11290 | header line from the response and uses the corresponding value to match. This |
| 11291 | can be comparable to what "appsession" does with default options, but with |
| 11292 | support for multi-peer synchronization and state keeping across restarts. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 11293 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11294 | This fetch function is deprecated and has been superseded by the "res.cook" |
| 11295 | fetch. This keyword will disappear soon. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 11296 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11297 | See also : "appsession" |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11298 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11299 | status : integer |
| 11300 | Returns an integer containing the HTTP status code in the HTTP response, for |
| 11301 | example, 302. It is mostly used within ACLs and integer ranges, for example, |
| 11302 | to remove any Location header if the response is not a 3xx. |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11303 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11304 | url : string |
| 11305 | This extracts the request's URL as presented in the request. A typical use is |
| 11306 | with prefetch-capable caches, and with portals which need to aggregate |
| 11307 | multiple information from databases and keep them in caches. With ACLs, using |
| 11308 | "path" is preferred over using "url", because clients may send a full URL as |
| 11309 | is normally done with proxies. The only real use is to match "*" which does |
| 11310 | not match in "path", and for which there is already a predefined ACL. See |
| 11311 | also "path" and "base". |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11312 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11313 | ACL derivatives : |
| 11314 | url : exact string match |
| 11315 | url_beg : prefix match |
| 11316 | url_dir : subdir match |
| 11317 | url_dom : domain match |
| 11318 | url_end : suffix match |
| 11319 | url_len : length match |
| 11320 | url_reg : regex match |
| 11321 | url_sub : substring match |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11322 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11323 | url_ip : ip |
| 11324 | This extracts the IP address from the request's URL when the host part is |
| 11325 | presented as an IP address. Its use is very limited. For instance, a |
| 11326 | monitoring system might use this field as an alternative for the source IP in |
| 11327 | order to test what path a given source address would follow, or to force an |
| 11328 | entry in a table for a given source address. With ACLs it can be used to |
| 11329 | restrict access to certain systems through a proxy, for example when combined |
| 11330 | with option "http_proxy". |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11331 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11332 | url_port : integer |
| 11333 | This extracts the port part from the request's URL. Note that if the port is |
| 11334 | not specified in the request, port 80 is assumed. With ACLs it can be used to |
| 11335 | restrict access to certain systems through a proxy, for example when combined |
| 11336 | with option "http_proxy". |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11337 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11338 | urlp(<name>[,<delim>]) : string |
| 11339 | url_param(<name>[,<delim>]) : string |
| 11340 | This extracts the first occurrence of the parameter <name> in the query |
| 11341 | string, which begins after either '?' or <delim>, and which ends before '&', |
| 11342 | ';' or <delim>. The parameter name is case-sensitive. The result is a string |
| 11343 | corresponding to the value of the parameter <name> as presented in the |
| 11344 | request (no URL decoding is performed). This can be used for session |
| 11345 | stickiness based on a client ID, to extract an application cookie passed as a |
| 11346 | URL parameter, or in ACLs to apply some checks. Note that the ACL version of |
| 11347 | this fetch do not iterate over multiple parameters and stop at the first one |
| 11348 | as well. |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11349 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11350 | ACL derivatives : |
| 11351 | urlp(<name>[,<delim>]) : exact string match |
| 11352 | urlp_beg(<name>[,<delim>]) : prefix match |
| 11353 | urlp_dir(<name>[,<delim>]) : subdir match |
| 11354 | urlp_dom(<name>[,<delim>]) : domain match |
| 11355 | urlp_end(<name>[,<delim>]) : suffix match |
| 11356 | urlp_len(<name>[,<delim>]) : length match |
| 11357 | urlp_reg(<name>[,<delim>]) : regex match |
| 11358 | urlp_sub(<name>[,<delim>]) : substring match |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11359 | |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11360 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11361 | Example : |
| 11362 | # match http://example.com/foo?PHPSESSIONID=some_id |
| 11363 | stick on urlp(PHPSESSIONID) |
| 11364 | # match http://example.com/foo;JSESSIONID=some_id |
| 11365 | stick on urlp(JSESSIONID,;) |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 11366 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11367 | urlp_val(<name>[,<delim>]) : integer |
| 11368 | See "urlp" above. This one extracts the URL parameter <name> in the request |
| 11369 | and converts it to an integer value. This can be used for session stickiness |
| 11370 | based on a user ID for example, or with ACLs to match a page number or price. |
Willy Tarreau | a9fddca | 2012-07-31 07:51:48 +0200 | [diff] [blame] | 11371 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 11372 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11373 | 7.4. Pre-defined ACLs |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11374 | --------------------- |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 11375 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11376 | Some predefined ACLs are hard-coded so that they do not have to be declared in |
| 11377 | every frontend which needs them. They all have their names in upper case in |
Patrick Mézard | 2382ad6 | 2010-05-09 10:43:32 +0200 | [diff] [blame] | 11378 | order to avoid confusion. Their equivalence is provided below. |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 11379 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11380 | ACL name Equivalent to Usage |
| 11381 | ---------------+-----------------------------+--------------------------------- |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11382 | FALSE always_false never match |
Willy Tarreau | 2492d5b | 2009-07-11 00:06:00 +0200 | [diff] [blame] | 11383 | HTTP req_proto_http match if protocol is valid HTTP |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11384 | HTTP_1.0 req_ver 1.0 match HTTP version 1.0 |
| 11385 | HTTP_1.1 req_ver 1.1 match HTTP version 1.1 |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11386 | HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length |
| 11387 | HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme |
| 11388 | HTTP_URL_SLASH url_beg / match URL beginning with "/" |
| 11389 | HTTP_URL_STAR url * match URL equal to "*" |
| 11390 | LOCALHOST src 127.0.0.1/8 match connection from local host |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11391 | METH_CONNECT method CONNECT match HTTP CONNECT method |
| 11392 | METH_GET method GET HEAD match HTTP GET or HEAD method |
| 11393 | METH_HEAD method HEAD match HTTP HEAD method |
| 11394 | METH_OPTIONS method OPTIONS match HTTP OPTIONS method |
| 11395 | METH_POST method POST match HTTP POST method |
| 11396 | METH_TRACE method TRACE match HTTP TRACE method |
Emeric Brun | bede3d0 | 2009-06-30 17:54:00 +0200 | [diff] [blame] | 11397 | RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11398 | REQ_CONTENT req_len gt 0 match data in the request buffer |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 11399 | TRUE always_true always match |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11400 | WAIT_END wait_end wait for end of content analysis |
| 11401 | ---------------+-----------------------------+--------------------------------- |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 11402 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11403 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11404 | 8. Logging |
| 11405 | ---------- |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 11406 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11407 | One of HAProxy's strong points certainly lies is its precise logs. It probably |
| 11408 | provides the finest level of information available for such a product, which is |
| 11409 | very important for troubleshooting complex environments. Standard information |
| 11410 | provided in logs include client ports, TCP/HTTP state timers, precise session |
| 11411 | state at termination and precise termination cause, information about decisions |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 11412 | to direct traffic to a server, and of course the ability to capture arbitrary |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11413 | headers. |
| 11414 | |
| 11415 | In order to improve administrators reactivity, it offers a great transparency |
| 11416 | about encountered problems, both internal and external, and it is possible to |
| 11417 | send logs to different sources at the same time with different level filters : |
| 11418 | |
| 11419 | - global process-level logs (system errors, start/stop, etc..) |
| 11420 | - per-instance system and internal errors (lack of resource, bugs, ...) |
| 11421 | - per-instance external troubles (servers up/down, max connections) |
| 11422 | - per-instance activity (client connections), either at the establishment or |
| 11423 | at the termination. |
| 11424 | |
| 11425 | The ability to distribute different levels of logs to different log servers |
| 11426 | allow several production teams to interact and to fix their problems as soon |
| 11427 | as possible. For example, the system team might monitor system-wide errors, |
| 11428 | while the application team might be monitoring the up/down for their servers in |
| 11429 | real time, and the security team might analyze the activity logs with one hour |
| 11430 | delay. |
| 11431 | |
| 11432 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11433 | 8.1. Log levels |
| 11434 | --------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11435 | |
Simon Horman | df791f5 | 2011-05-29 15:01:10 +0900 | [diff] [blame] | 11436 | TCP and HTTP connections can be logged with information such as the date, time, |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11437 | source IP address, destination address, connection duration, response times, |
Simon Horman | df791f5 | 2011-05-29 15:01:10 +0900 | [diff] [blame] | 11438 | HTTP request, HTTP return code, number of bytes transmitted, conditions |
| 11439 | in which the session ended, and even exchanged cookies values. For example |
| 11440 | track a particular user's problems. All messages may be sent to up to two |
| 11441 | syslog servers. Check the "log" keyword in section 4.2 for more information |
| 11442 | about log facilities. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11443 | |
| 11444 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11445 | 8.2. Log formats |
| 11446 | ---------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11447 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11448 | HAProxy supports 5 log formats. Several fields are common between these formats |
Simon Horman | df791f5 | 2011-05-29 15:01:10 +0900 | [diff] [blame] | 11449 | and will be detailed in the following sections. A few of them may vary |
| 11450 | slightly with the configuration, due to indicators specific to certain |
| 11451 | options. The supported formats are as follows : |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11452 | |
| 11453 | - the default format, which is very basic and very rarely used. It only |
| 11454 | provides very basic information about the incoming connection at the moment |
| 11455 | it is accepted : source IP:port, destination IP:port, and frontend-name. |
| 11456 | This mode will eventually disappear so it will not be described to great |
| 11457 | extents. |
| 11458 | |
| 11459 | - the TCP format, which is more advanced. This format is enabled when "option |
| 11460 | tcplog" is set on the frontend. HAProxy will then usually wait for the |
| 11461 | connection to terminate before logging. This format provides much richer |
| 11462 | information, such as timers, connection counts, queue size, etc... This |
| 11463 | format is recommended for pure TCP proxies. |
| 11464 | |
| 11465 | - the HTTP format, which is the most advanced for HTTP proxying. This format |
| 11466 | is enabled when "option httplog" is set on the frontend. It provides the |
| 11467 | same information as the TCP format with some HTTP-specific fields such as |
| 11468 | the request, the status code, and captures of headers and cookies. This |
| 11469 | format is recommended for HTTP proxies. |
| 11470 | |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 11471 | - the CLF HTTP format, which is equivalent to the HTTP format, but with the |
| 11472 | fields arranged in the same order as the CLF format. In this mode, all |
| 11473 | timers, captures, flags, etc... appear one per field after the end of the |
| 11474 | common fields, in the same order they appear in the standard HTTP format. |
| 11475 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11476 | - the custom log format, allows you to make your own log line. |
| 11477 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11478 | Next sections will go deeper into details for each of these formats. Format |
| 11479 | specification will be performed on a "field" basis. Unless stated otherwise, a |
| 11480 | field is a portion of text delimited by any number of spaces. Since syslog |
| 11481 | servers are susceptible of inserting fields at the beginning of a line, it is |
| 11482 | always assumed that the first field is the one containing the process name and |
| 11483 | identifier. |
| 11484 | |
| 11485 | Note : Since log lines may be quite long, the log examples in sections below |
| 11486 | might be broken into multiple lines. The example log lines will be |
| 11487 | prefixed with 3 closing angle brackets ('>>>') and each time a log is |
| 11488 | broken into multiple lines, each non-final line will end with a |
| 11489 | backslash ('\') and the next line will start indented by two characters. |
| 11490 | |
| 11491 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11492 | 8.2.1. Default log format |
| 11493 | ------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11494 | |
| 11495 | This format is used when no specific option is set. The log is emitted as soon |
| 11496 | as the connection is accepted. One should note that this currently is the only |
| 11497 | format which logs the request's destination IP and ports. |
| 11498 | |
| 11499 | Example : |
| 11500 | listen www |
| 11501 | mode http |
| 11502 | log global |
| 11503 | server srv1 127.0.0.1:8000 |
| 11504 | |
| 11505 | >>> Feb 6 12:12:09 localhost \ |
| 11506 | haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \ |
| 11507 | (www/HTTP) |
| 11508 | |
| 11509 | Field Format Extract from the example above |
| 11510 | 1 process_name '[' pid ']:' haproxy[14385]: |
| 11511 | 2 'Connect from' Connect from |
| 11512 | 3 source_ip ':' source_port 10.0.1.2:33312 |
| 11513 | 4 'to' to |
| 11514 | 5 destination_ip ':' destination_port 10.0.3.31:8012 |
| 11515 | 6 '(' frontend_name '/' mode ')' (www/HTTP) |
| 11516 | |
| 11517 | Detailed fields description : |
| 11518 | - "source_ip" is the IP address of the client which initiated the connection. |
| 11519 | - "source_port" is the TCP port of the client which initiated the connection. |
| 11520 | - "destination_ip" is the IP address the client connected to. |
| 11521 | - "destination_port" is the TCP port the client connected to. |
| 11522 | - "frontend_name" is the name of the frontend (or listener) which received |
| 11523 | and processed the connection. |
| 11524 | - "mode is the mode the frontend is operating (TCP or HTTP). |
| 11525 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 11526 | In case of a UNIX socket, the source and destination addresses are marked as |
| 11527 | "unix:" and the ports reflect the internal ID of the socket which accepted the |
| 11528 | connection (the same ID as reported in the stats). |
| 11529 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11530 | It is advised not to use this deprecated format for newer installations as it |
| 11531 | will eventually disappear. |
| 11532 | |
| 11533 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11534 | 8.2.2. TCP log format |
| 11535 | --------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11536 | |
| 11537 | The TCP format is used when "option tcplog" is specified in the frontend, and |
| 11538 | is the recommended format for pure TCP proxies. It provides a lot of precious |
| 11539 | information for troubleshooting. Since this format includes timers and byte |
| 11540 | counts, the log is normally emitted at the end of the session. It can be |
| 11541 | emitted earlier if "option logasap" is specified, which makes sense in most |
| 11542 | environments with long sessions such as remote terminals. Sessions which match |
| 11543 | the "monitor" rules are never logged. It is also possible not to emit logs for |
| 11544 | sessions for which no data were exchanged between the client and the server, by |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 11545 | specifying "option dontlognull" in the frontend. Successful connections will |
| 11546 | not be logged if "option dontlog-normal" is specified in the frontend. A few |
| 11547 | fields may slightly vary depending on some configuration options, those are |
| 11548 | marked with a star ('*') after the field name below. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11549 | |
| 11550 | Example : |
| 11551 | frontend fnt |
| 11552 | mode tcp |
| 11553 | option tcplog |
| 11554 | log global |
| 11555 | default_backend bck |
| 11556 | |
| 11557 | backend bck |
| 11558 | server srv1 127.0.0.1:8000 |
| 11559 | |
| 11560 | >>> Feb 6 12:12:56 localhost \ |
| 11561 | haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \ |
| 11562 | bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0 |
| 11563 | |
| 11564 | Field Format Extract from the example above |
| 11565 | 1 process_name '[' pid ']:' haproxy[14387]: |
| 11566 | 2 client_ip ':' client_port 10.0.1.2:33313 |
| 11567 | 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443] |
| 11568 | 4 frontend_name fnt |
| 11569 | 5 backend_name '/' server_name bck/srv1 |
| 11570 | 6 Tw '/' Tc '/' Tt* 0/0/5007 |
| 11571 | 7 bytes_read* 212 |
| 11572 | 8 termination_state -- |
| 11573 | 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3 |
| 11574 | 10 srv_queue '/' backend_queue 0/0 |
| 11575 | |
| 11576 | Detailed fields description : |
| 11577 | - "client_ip" is the IP address of the client which initiated the TCP |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 11578 | connection to haproxy. If the connection was accepted on a UNIX socket |
| 11579 | instead, the IP address would be replaced with the word "unix". Note that |
| 11580 | when the connection is accepted on a socket configured with "accept-proxy" |
| 11581 | and the PROXY protocol is correctly used, then the logs will reflect the |
| 11582 | forwarded connection's information. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11583 | |
| 11584 | - "client_port" is the TCP port of the client which initiated the connection. |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 11585 | If the connection was accepted on a UNIX socket instead, the port would be |
| 11586 | replaced with the ID of the accepting socket, which is also reported in the |
| 11587 | stats interface. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11588 | |
| 11589 | - "accept_date" is the exact date when the connection was received by haproxy |
| 11590 | (which might be very slightly different from the date observed on the |
| 11591 | network if there was some queuing in the system's backlog). This is usually |
| 11592 | the same date which may appear in any upstream firewall's log. |
| 11593 | |
| 11594 | - "frontend_name" is the name of the frontend (or listener) which received |
| 11595 | and processed the connection. |
| 11596 | |
| 11597 | - "backend_name" is the name of the backend (or listener) which was selected |
| 11598 | to manage the connection to the server. This will be the same as the |
| 11599 | frontend if no switching rule has been applied, which is common for TCP |
| 11600 | applications. |
| 11601 | |
| 11602 | - "server_name" is the name of the last server to which the connection was |
| 11603 | sent, which might differ from the first one if there were connection errors |
| 11604 | and a redispatch occurred. Note that this server belongs to the backend |
| 11605 | which processed the request. If the connection was aborted before reaching |
| 11606 | a server, "<NOSRV>" is indicated instead of a server name. |
| 11607 | |
| 11608 | - "Tw" is the total time in milliseconds spent waiting in the various queues. |
| 11609 | It can be "-1" if the connection was aborted before reaching the queue. |
| 11610 | See "Timers" below for more details. |
| 11611 | |
| 11612 | - "Tc" is the total time in milliseconds spent waiting for the connection to |
| 11613 | establish to the final server, including retries. It can be "-1" if the |
| 11614 | connection was aborted before a connection could be established. See |
| 11615 | "Timers" below for more details. |
| 11616 | |
| 11617 | - "Tt" is the total time in milliseconds elapsed between the accept and the |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 11618 | last close. It covers all possible processing. There is one exception, if |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11619 | "option logasap" was specified, then the time counting stops at the moment |
| 11620 | the log is emitted. In this case, a '+' sign is prepended before the value, |
| 11621 | indicating that the final one will be larger. See "Timers" below for more |
| 11622 | details. |
| 11623 | |
| 11624 | - "bytes_read" is the total number of bytes transmitted from the server to |
| 11625 | the client when the log is emitted. If "option logasap" is specified, the |
| 11626 | this value will be prefixed with a '+' sign indicating that the final one |
| 11627 | may be larger. Please note that this value is a 64-bit counter, so log |
| 11628 | analysis tools must be able to handle it without overflowing. |
| 11629 | |
| 11630 | - "termination_state" is the condition the session was in when the session |
| 11631 | ended. This indicates the session state, which side caused the end of |
| 11632 | session to happen, and for what reason (timeout, error, ...). The normal |
| 11633 | flags should be "--", indicating the session was closed by either end with |
| 11634 | no data remaining in buffers. See below "Session state at disconnection" |
| 11635 | for more details. |
| 11636 | |
| 11637 | - "actconn" is the total number of concurrent connections on the process when |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 11638 | the session was logged. It is useful to detect when some per-process system |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11639 | limits have been reached. For instance, if actconn is close to 512 when |
| 11640 | multiple connection errors occur, chances are high that the system limits |
| 11641 | the process to use a maximum of 1024 file descriptors and that all of them |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11642 | are used. See section 3 "Global parameters" to find how to tune the system. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11643 | |
| 11644 | - "feconn" is the total number of concurrent connections on the frontend when |
| 11645 | the session was logged. It is useful to estimate the amount of resource |
| 11646 | required to sustain high loads, and to detect when the frontend's "maxconn" |
| 11647 | has been reached. Most often when this value increases by huge jumps, it is |
| 11648 | because there is congestion on the backend servers, but sometimes it can be |
| 11649 | caused by a denial of service attack. |
| 11650 | |
| 11651 | - "beconn" is the total number of concurrent connections handled by the |
| 11652 | backend when the session was logged. It includes the total number of |
| 11653 | concurrent connections active on servers as well as the number of |
| 11654 | connections pending in queues. It is useful to estimate the amount of |
| 11655 | additional servers needed to support high loads for a given application. |
| 11656 | Most often when this value increases by huge jumps, it is because there is |
| 11657 | congestion on the backend servers, but sometimes it can be caused by a |
| 11658 | denial of service attack. |
| 11659 | |
| 11660 | - "srv_conn" is the total number of concurrent connections still active on |
| 11661 | the server when the session was logged. It can never exceed the server's |
| 11662 | configured "maxconn" parameter. If this value is very often close or equal |
| 11663 | to the server's "maxconn", it means that traffic regulation is involved a |
| 11664 | lot, meaning that either the server's maxconn value is too low, or that |
| 11665 | there aren't enough servers to process the load with an optimal response |
| 11666 | time. When only one of the server's "srv_conn" is high, it usually means |
| 11667 | that this server has some trouble causing the connections to take longer to |
| 11668 | be processed than on other servers. |
| 11669 | |
| 11670 | - "retries" is the number of connection retries experienced by this session |
| 11671 | when trying to connect to the server. It must normally be zero, unless a |
| 11672 | server is being stopped at the same moment the connection was attempted. |
| 11673 | Frequent retries generally indicate either a network problem between |
| 11674 | haproxy and the server, or a misconfigured system backlog on the server |
| 11675 | preventing new connections from being queued. This field may optionally be |
| 11676 | prefixed with a '+' sign, indicating that the session has experienced a |
| 11677 | redispatch after the maximal retry count has been reached on the initial |
| 11678 | server. In this case, the server name appearing in the log is the one the |
| 11679 | connection was redispatched to, and not the first one, though both may |
| 11680 | sometimes be the same in case of hashing for instance. So as a general rule |
| 11681 | of thumb, when a '+' is present in front of the retry count, this count |
| 11682 | should not be attributed to the logged server. |
| 11683 | |
| 11684 | - "srv_queue" is the total number of requests which were processed before |
| 11685 | this one in the server queue. It is zero when the request has not gone |
| 11686 | through the server queue. It makes it possible to estimate the approximate |
| 11687 | server's response time by dividing the time spent in queue by the number of |
| 11688 | requests in the queue. It is worth noting that if a session experiences a |
| 11689 | redispatch and passes through two server queues, their positions will be |
| 11690 | cumulated. A request should not pass through both the server queue and the |
| 11691 | backend queue unless a redispatch occurs. |
| 11692 | |
| 11693 | - "backend_queue" is the total number of requests which were processed before |
| 11694 | this one in the backend's global queue. It is zero when the request has not |
| 11695 | gone through the global queue. It makes it possible to estimate the average |
| 11696 | queue length, which easily translates into a number of missing servers when |
| 11697 | divided by a server's "maxconn" parameter. It is worth noting that if a |
| 11698 | session experiences a redispatch, it may pass twice in the backend's queue, |
| 11699 | and then both positions will be cumulated. A request should not pass |
| 11700 | through both the server queue and the backend queue unless a redispatch |
| 11701 | occurs. |
| 11702 | |
| 11703 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11704 | 8.2.3. HTTP log format |
| 11705 | ---------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11706 | |
| 11707 | The HTTP format is the most complete and the best suited for HTTP proxies. It |
| 11708 | is enabled by when "option httplog" is specified in the frontend. It provides |
| 11709 | the same level of information as the TCP format with additional features which |
| 11710 | are specific to the HTTP protocol. Just like the TCP format, the log is usually |
| 11711 | emitted at the end of the session, unless "option logasap" is specified, which |
| 11712 | generally only makes sense for download sites. A session which matches the |
| 11713 | "monitor" rules will never logged. It is also possible not to log sessions for |
| 11714 | which no data were sent by the client by specifying "option dontlognull" in the |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 11715 | frontend. Successful connections will not be logged if "option dontlog-normal" |
| 11716 | is specified in the frontend. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11717 | |
| 11718 | Most fields are shared with the TCP log, some being different. A few fields may |
| 11719 | slightly vary depending on some configuration options. Those ones are marked |
| 11720 | with a star ('*') after the field name below. |
| 11721 | |
| 11722 | Example : |
| 11723 | frontend http-in |
| 11724 | mode http |
| 11725 | option httplog |
| 11726 | log global |
| 11727 | default_backend bck |
| 11728 | |
| 11729 | backend static |
| 11730 | server srv1 127.0.0.1:8000 |
| 11731 | |
| 11732 | >>> Feb 6 12:14:14 localhost \ |
| 11733 | haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ |
| 11734 | static/srv1 10/0/30/69/109 200 2750 - - ---- 1/1/1/1/0 0/0 {1wt.eu} \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 11735 | {} "GET /index.html HTTP/1.1" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11736 | |
| 11737 | Field Format Extract from the example above |
| 11738 | 1 process_name '[' pid ']:' haproxy[14389]: |
| 11739 | 2 client_ip ':' client_port 10.0.1.2:33317 |
| 11740 | 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655] |
| 11741 | 4 frontend_name http-in |
| 11742 | 5 backend_name '/' server_name static/srv1 |
| 11743 | 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109 |
| 11744 | 7 status_code 200 |
| 11745 | 8 bytes_read* 2750 |
| 11746 | 9 captured_request_cookie - |
| 11747 | 10 captured_response_cookie - |
| 11748 | 11 termination_state ---- |
| 11749 | 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0 |
| 11750 | 13 srv_queue '/' backend_queue 0/0 |
| 11751 | 14 '{' captured_request_headers* '}' {haproxy.1wt.eu} |
| 11752 | 15 '{' captured_response_headers* '}' {} |
| 11753 | 16 '"' http_request '"' "GET /index.html HTTP/1.1" |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 11754 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11755 | |
| 11756 | Detailed fields description : |
| 11757 | - "client_ip" is the IP address of the client which initiated the TCP |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 11758 | connection to haproxy. If the connection was accepted on a UNIX socket |
| 11759 | instead, the IP address would be replaced with the word "unix". Note that |
| 11760 | when the connection is accepted on a socket configured with "accept-proxy" |
| 11761 | and the PROXY protocol is correctly used, then the logs will reflect the |
| 11762 | forwarded connection's information. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11763 | |
| 11764 | - "client_port" is the TCP port of the client which initiated the connection. |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 11765 | If the connection was accepted on a UNIX socket instead, the port would be |
| 11766 | replaced with the ID of the accepting socket, which is also reported in the |
| 11767 | stats interface. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11768 | |
| 11769 | - "accept_date" is the exact date when the TCP connection was received by |
| 11770 | haproxy (which might be very slightly different from the date observed on |
| 11771 | the network if there was some queuing in the system's backlog). This is |
| 11772 | usually the same date which may appear in any upstream firewall's log. This |
| 11773 | does not depend on the fact that the client has sent the request or not. |
| 11774 | |
| 11775 | - "frontend_name" is the name of the frontend (or listener) which received |
| 11776 | and processed the connection. |
| 11777 | |
| 11778 | - "backend_name" is the name of the backend (or listener) which was selected |
| 11779 | to manage the connection to the server. This will be the same as the |
| 11780 | frontend if no switching rule has been applied. |
| 11781 | |
| 11782 | - "server_name" is the name of the last server to which the connection was |
| 11783 | sent, which might differ from the first one if there were connection errors |
| 11784 | and a redispatch occurred. Note that this server belongs to the backend |
| 11785 | which processed the request. If the request was aborted before reaching a |
| 11786 | server, "<NOSRV>" is indicated instead of a server name. If the request was |
| 11787 | intercepted by the stats subsystem, "<STATS>" is indicated instead. |
| 11788 | |
| 11789 | - "Tq" is the total time in milliseconds spent waiting for the client to send |
| 11790 | a full HTTP request, not counting data. It can be "-1" if the connection |
| 11791 | was aborted before a complete request could be received. It should always |
| 11792 | be very small because a request generally fits in one single packet. Large |
| 11793 | times here generally indicate network trouble between the client and |
| 11794 | haproxy. See "Timers" below for more details. |
| 11795 | |
| 11796 | - "Tw" is the total time in milliseconds spent waiting in the various queues. |
| 11797 | It can be "-1" if the connection was aborted before reaching the queue. |
| 11798 | See "Timers" below for more details. |
| 11799 | |
| 11800 | - "Tc" is the total time in milliseconds spent waiting for the connection to |
| 11801 | establish to the final server, including retries. It can be "-1" if the |
| 11802 | request was aborted before a connection could be established. See "Timers" |
| 11803 | below for more details. |
| 11804 | |
| 11805 | - "Tr" is the total time in milliseconds spent waiting for the server to send |
| 11806 | a full HTTP response, not counting data. It can be "-1" if the request was |
| 11807 | aborted before a complete response could be received. It generally matches |
| 11808 | the server's processing time for the request, though it may be altered by |
| 11809 | the amount of data sent by the client to the server. Large times here on |
| 11810 | "GET" requests generally indicate an overloaded server. See "Timers" below |
| 11811 | for more details. |
| 11812 | |
| 11813 | - "Tt" is the total time in milliseconds elapsed between the accept and the |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 11814 | last close. It covers all possible processing. There is one exception, if |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11815 | "option logasap" was specified, then the time counting stops at the moment |
| 11816 | the log is emitted. In this case, a '+' sign is prepended before the value, |
| 11817 | indicating that the final one will be larger. See "Timers" below for more |
| 11818 | details. |
| 11819 | |
| 11820 | - "status_code" is the HTTP status code returned to the client. This status |
| 11821 | is generally set by the server, but it might also be set by haproxy when |
| 11822 | the server cannot be reached or when its response is blocked by haproxy. |
| 11823 | |
| 11824 | - "bytes_read" is the total number of bytes transmitted to the client when |
| 11825 | the log is emitted. This does include HTTP headers. If "option logasap" is |
| 11826 | specified, the this value will be prefixed with a '+' sign indicating that |
| 11827 | the final one may be larger. Please note that this value is a 64-bit |
| 11828 | counter, so log analysis tools must be able to handle it without |
| 11829 | overflowing. |
| 11830 | |
| 11831 | - "captured_request_cookie" is an optional "name=value" entry indicating that |
| 11832 | the client had this cookie in the request. The cookie name and its maximum |
| 11833 | length are defined by the "capture cookie" statement in the frontend |
| 11834 | configuration. The field is a single dash ('-') when the option is not |
| 11835 | set. Only one cookie may be captured, it is generally used to track session |
| 11836 | ID exchanges between a client and a server to detect session crossing |
| 11837 | between clients due to application bugs. For more details, please consult |
| 11838 | the section "Capturing HTTP headers and cookies" below. |
| 11839 | |
| 11840 | - "captured_response_cookie" is an optional "name=value" entry indicating |
| 11841 | that the server has returned a cookie with its response. The cookie name |
| 11842 | and its maximum length are defined by the "capture cookie" statement in the |
| 11843 | frontend configuration. The field is a single dash ('-') when the option is |
| 11844 | not set. Only one cookie may be captured, it is generally used to track |
| 11845 | session ID exchanges between a client and a server to detect session |
| 11846 | crossing between clients due to application bugs. For more details, please |
| 11847 | consult the section "Capturing HTTP headers and cookies" below. |
| 11848 | |
| 11849 | - "termination_state" is the condition the session was in when the session |
| 11850 | ended. This indicates the session state, which side caused the end of |
| 11851 | session to happen, for what reason (timeout, error, ...), just like in TCP |
| 11852 | logs, and information about persistence operations on cookies in the last |
| 11853 | two characters. The normal flags should begin with "--", indicating the |
| 11854 | session was closed by either end with no data remaining in buffers. See |
| 11855 | below "Session state at disconnection" for more details. |
| 11856 | |
| 11857 | - "actconn" is the total number of concurrent connections on the process when |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 11858 | the session was logged. It is useful to detect when some per-process system |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11859 | limits have been reached. For instance, if actconn is close to 512 or 1024 |
| 11860 | when multiple connection errors occur, chances are high that the system |
| 11861 | limits the process to use a maximum of 1024 file descriptors and that all |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 11862 | of them are used. See section 3 "Global parameters" to find how to tune the |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 11863 | system. |
| 11864 | |
| 11865 | - "feconn" is the total number of concurrent connections on the frontend when |
| 11866 | the session was logged. It is useful to estimate the amount of resource |
| 11867 | required to sustain high loads, and to detect when the frontend's "maxconn" |
| 11868 | has been reached. Most often when this value increases by huge jumps, it is |
| 11869 | because there is congestion on the backend servers, but sometimes it can be |
| 11870 | caused by a denial of service attack. |
| 11871 | |
| 11872 | - "beconn" is the total number of concurrent connections handled by the |
| 11873 | backend when the session was logged. It includes the total number of |
| 11874 | concurrent connections active on servers as well as the number of |
| 11875 | connections pending in queues. It is useful to estimate the amount of |
| 11876 | additional servers needed to support high loads for a given application. |
| 11877 | Most often when this value increases by huge jumps, it is because there is |
| 11878 | congestion on the backend servers, but sometimes it can be caused by a |
| 11879 | denial of service attack. |
| 11880 | |
| 11881 | - "srv_conn" is the total number of concurrent connections still active on |
| 11882 | the server when the session was logged. It can never exceed the server's |
| 11883 | configured "maxconn" parameter. If this value is very often close or equal |
| 11884 | to the server's "maxconn", it means that traffic regulation is involved a |
| 11885 | lot, meaning that either the server's maxconn value is too low, or that |
| 11886 | there aren't enough servers to process the load with an optimal response |
| 11887 | time. When only one of the server's "srv_conn" is high, it usually means |
| 11888 | that this server has some trouble causing the requests to take longer to be |
| 11889 | processed than on other servers. |
| 11890 | |
| 11891 | - "retries" is the number of connection retries experienced by this session |
| 11892 | when trying to connect to the server. It must normally be zero, unless a |
| 11893 | server is being stopped at the same moment the connection was attempted. |
| 11894 | Frequent retries generally indicate either a network problem between |
| 11895 | haproxy and the server, or a misconfigured system backlog on the server |
| 11896 | preventing new connections from being queued. This field may optionally be |
| 11897 | prefixed with a '+' sign, indicating that the session has experienced a |
| 11898 | redispatch after the maximal retry count has been reached on the initial |
| 11899 | server. In this case, the server name appearing in the log is the one the |
| 11900 | connection was redispatched to, and not the first one, though both may |
| 11901 | sometimes be the same in case of hashing for instance. So as a general rule |
| 11902 | of thumb, when a '+' is present in front of the retry count, this count |
| 11903 | should not be attributed to the logged server. |
| 11904 | |
| 11905 | - "srv_queue" is the total number of requests which were processed before |
| 11906 | this one in the server queue. It is zero when the request has not gone |
| 11907 | through the server queue. It makes it possible to estimate the approximate |
| 11908 | server's response time by dividing the time spent in queue by the number of |
| 11909 | requests in the queue. It is worth noting that if a session experiences a |
| 11910 | redispatch and passes through two server queues, their positions will be |
| 11911 | cumulated. A request should not pass through both the server queue and the |
| 11912 | backend queue unless a redispatch occurs. |
| 11913 | |
| 11914 | - "backend_queue" is the total number of requests which were processed before |
| 11915 | this one in the backend's global queue. It is zero when the request has not |
| 11916 | gone through the global queue. It makes it possible to estimate the average |
| 11917 | queue length, which easily translates into a number of missing servers when |
| 11918 | divided by a server's "maxconn" parameter. It is worth noting that if a |
| 11919 | session experiences a redispatch, it may pass twice in the backend's queue, |
| 11920 | and then both positions will be cumulated. A request should not pass |
| 11921 | through both the server queue and the backend queue unless a redispatch |
| 11922 | occurs. |
| 11923 | |
| 11924 | - "captured_request_headers" is a list of headers captured in the request due |
| 11925 | to the presence of the "capture request header" statement in the frontend. |
| 11926 | Multiple headers can be captured, they will be delimited by a vertical bar |
| 11927 | ('|'). When no capture is enabled, the braces do not appear, causing a |
| 11928 | shift of remaining fields. It is important to note that this field may |
| 11929 | contain spaces, and that using it requires a smarter log parser than when |
| 11930 | it's not used. Please consult the section "Capturing HTTP headers and |
| 11931 | cookies" below for more details. |
| 11932 | |
| 11933 | - "captured_response_headers" is a list of headers captured in the response |
| 11934 | due to the presence of the "capture response header" statement in the |
| 11935 | frontend. Multiple headers can be captured, they will be delimited by a |
| 11936 | vertical bar ('|'). When no capture is enabled, the braces do not appear, |
| 11937 | causing a shift of remaining fields. It is important to note that this |
| 11938 | field may contain spaces, and that using it requires a smarter log parser |
| 11939 | than when it's not used. Please consult the section "Capturing HTTP headers |
| 11940 | and cookies" below for more details. |
| 11941 | |
| 11942 | - "http_request" is the complete HTTP request line, including the method, |
| 11943 | request and HTTP version string. Non-printable characters are encoded (see |
| 11944 | below the section "Non-printable characters"). This is always the last |
| 11945 | field, and it is always delimited by quotes and is the only one which can |
| 11946 | contain quotes. If new fields are added to the log format, they will be |
| 11947 | added before this field. This field might be truncated if the request is |
| 11948 | huge and does not fit in the standard syslog buffer (1024 characters). This |
| 11949 | is the reason why this field must always remain the last one. |
| 11950 | |
| 11951 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 11952 | 8.2.4. Custom log format |
| 11953 | ------------------------ |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11954 | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 11955 | The directive log-format allows you to customize the logs in http mode and tcp |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 11956 | mode. It takes a string as argument. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11957 | |
| 11958 | HAproxy understands some log format variables. % precedes log format variables. |
| 11959 | Variables can take arguments using braces ('{}'), and multiple arguments are |
| 11960 | separated by commas within the braces. Flags may be added or removed by |
| 11961 | prefixing them with a '+' or '-' sign. |
| 11962 | |
| 11963 | Special variable "%o" may be used to propagate its flags to all other |
| 11964 | variables on the same format string. This is particularly handy with quoted |
| 11965 | string formats ("Q"). |
| 11966 | |
Willy Tarreau | c836845 | 2012-12-21 00:09:23 +0100 | [diff] [blame] | 11967 | If a variable is named between square brackets ('[' .. ']') then it is used |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11968 | as a pattern extraction rule (see section 7.3). This it useful to add some |
Willy Tarreau | c836845 | 2012-12-21 00:09:23 +0100 | [diff] [blame] | 11969 | less common information such as the client's SSL certificate's DN, or to log |
| 11970 | the key that would be used to store an entry into a stick table. |
| 11971 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11972 | Note: spaces must be escaped. A space character is considered as a separator. |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 11973 | In order to emit a verbatim '%', it must be preceded by another '%' resulting |
Willy Tarreau | 06d97f9 | 2013-12-02 17:45:48 +0100 | [diff] [blame] | 11974 | in '%%'. HAProxy will automatically merge consecutive separators. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11975 | |
| 11976 | Flags are : |
| 11977 | * Q: quote a string |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 11978 | * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid) |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11979 | |
| 11980 | Example: |
| 11981 | |
| 11982 | log-format %T\ %t\ Some\ Text |
| 11983 | log-format %{+Q}o\ %t\ %s\ %{-Q}r |
| 11984 | |
| 11985 | At the moment, the default HTTP format is defined this way : |
| 11986 | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 11987 | log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tq/%Tw/%Tc/%Tr/%Tt\ %ST\ %B\ %CC\ \ |
| 11988 | %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11989 | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 11990 | the default CLF format is defined this way : |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11991 | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 11992 | log-format %{+Q}o\ %{-Q}ci\ -\ -\ [%T]\ %r\ %ST\ %B\ \"\"\ \"\"\ %cp\ \ |
Willy Tarreau | 773d65f | 2012-10-12 14:56:11 +0200 | [diff] [blame] | 11993 | %ms\ %ft\ %b\ %s\ \%Tq\ %Tw\ %Tc\ %Tr\ %Tt\ %tsc\ %ac\ %fc\ \ |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 11994 | %bc\ %sc\ %rc\ %sq\ %bq\ %CC\ %CS\ \%hrl\ %hsl |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 11995 | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 11996 | and the default TCP format is defined this way : |
| 11997 | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 11998 | log-format %ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ \ |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 11999 | %ac/%fc/%bc/%sc/%rc\ %sq/%bq |
| 12000 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 12001 | Please refer to the table below for currently defined variables : |
| 12002 | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12003 | +---+------+-----------------------------------------------+-------------+ |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12004 | | R | var | field name (8.2.2 and 8.2.3 for description) | type | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12005 | +---+------+-----------------------------------------------+-------------+ |
| 12006 | | | %o | special variable, apply flags on all next var | | |
| 12007 | +---+------+-----------------------------------------------+-------------+ |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12008 | | | %B | bytes_read (from server to client) | numeric | |
| 12009 | | H | %CC | captured_request_cookie | string | |
| 12010 | | H | %CS | captured_response_cookie | string | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 12011 | | | %H | hostname | string | |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12012 | | | %ID | unique-id | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12013 | | H | %ST | status_code | numeric | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 12014 | | | %T | gmt_date_time | date | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12015 | | | %Tc | Tc | numeric | |
Yuxans Yao | 4e25b01 | 2012-10-19 10:36:09 +0800 | [diff] [blame] | 12016 | | | %Tl | local_date_time | date | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12017 | | H | %Tq | Tq | numeric | |
| 12018 | | H | %Tr | Tr | numeric | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 12019 | | | %Ts | timestamp | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12020 | | | %Tt | Tt | numeric | |
| 12021 | | | %Tw | Tw | numeric | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12022 | | | %U | bytes_uploaded (from client to server) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12023 | | | %ac | actconn | numeric | |
| 12024 | | | %b | backend_name | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12025 | | | %bc | beconn (backend concurrent connections) | numeric | |
| 12026 | | | %bi | backend_source_ip (connecting address) | IP | |
| 12027 | | | %bp | backend_source_port (connecting address) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12028 | | | %bq | backend_queue | numeric | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12029 | | | %ci | client_ip (accepted address) | IP | |
| 12030 | | | %cp | client_port (accepted address) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12031 | | | %f | frontend_name | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12032 | | | %fc | feconn (frontend concurrent connections) | numeric | |
| 12033 | | | %fi | frontend_ip (accepting address) | IP | |
| 12034 | | | %fp | frontend_port (accepting address) | numeric | |
Willy Tarreau | 773d65f | 2012-10-12 14:56:11 +0200 | [diff] [blame] | 12035 | | | %ft | frontend_name_transport ('~' suffix for SSL) | string | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12036 | | H | %hr | captured_request_headers default style | string | |
| 12037 | | H | %hrl | captured_request_headers CLF style | string list | |
| 12038 | | H | %hs | captured_response_headers default style | string | |
| 12039 | | H | %hsl | captured_response_headers CLF style | string list | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12040 | | | %ms | accept date milliseconds | numeric | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 12041 | | | %pid | PID | numeric | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12042 | | H | %r | http_request | string | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12043 | | | %rc | retries | numeric | |
Willy Tarreau | 1f0da24 | 2014-01-25 11:01:50 +0100 | [diff] [blame] | 12044 | | | %rt | request_counter (HTTP req or TCP session) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12045 | | | %s | server_name | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12046 | | | %sc | srv_conn (server concurrent connections) | numeric | |
| 12047 | | | %si | server_IP (target address) | IP | |
| 12048 | | | %sp | server_port (target address) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12049 | | | %sq | srv_queue | numeric | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12050 | | S | %sslc| ssl_ciphers (ex: AES-SHA) | string | |
| 12051 | | S | %sslv| ssl_version (ex: TLSv1) | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 12052 | | | %t | date_time (with millisecond resolution) | date | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12053 | | | %ts | termination_state | string | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12054 | | H | %tsc | termination_state with cookie status | string | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 12055 | +---+------+-----------------------------------------------+-------------+ |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 12056 | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 12057 | R = Restrictions : H = mode http only ; S = SSL only |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 12058 | |
Willy Tarreau | 5f51e1a | 2012-12-03 18:40:10 +0100 | [diff] [blame] | 12059 | |
| 12060 | 8.2.5. Error log format |
| 12061 | ----------------------- |
| 12062 | |
| 12063 | When an incoming connection fails due to an SSL handshake or an invalid PROXY |
| 12064 | protocol header, haproxy will log the event using a shorter, fixed line format. |
| 12065 | By default, logs are emitted at the LOG_INFO level, unless the option |
| 12066 | "log-separate-errors" is set in the backend, in which case the LOG_ERR level |
| 12067 | will be used. Connections on which no data are exchanged (eg: probes) are not |
| 12068 | logged if the "dontlognull" option is set. |
| 12069 | |
| 12070 | The format looks like this : |
| 12071 | |
| 12072 | >>> Dec 3 18:27:14 localhost \ |
| 12073 | haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \ |
| 12074 | Connection error during SSL handshake |
| 12075 | |
| 12076 | Field Format Extract from the example above |
| 12077 | 1 process_name '[' pid ']:' haproxy[6103]: |
| 12078 | 2 client_ip ':' client_port 127.0.0.1:56059 |
| 12079 | 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380] |
| 12080 | 4 frontend_name "/" bind_name ":" frt/f1: |
| 12081 | 5 message Connection error during SSL handshake |
| 12082 | |
| 12083 | These fields just provide minimal information to help debugging connection |
| 12084 | failures. |
| 12085 | |
| 12086 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12087 | 8.3. Advanced logging options |
| 12088 | ----------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12089 | |
| 12090 | Some advanced logging options are often looked for but are not easy to find out |
| 12091 | just by looking at the various options. Here is an entry point for the few |
| 12092 | options which can enable better logging. Please refer to the keywords reference |
| 12093 | for more information about their usage. |
| 12094 | |
| 12095 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12096 | 8.3.1. Disabling logging of external tests |
| 12097 | ------------------------------------------ |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12098 | |
| 12099 | It is quite common to have some monitoring tools perform health checks on |
| 12100 | haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any |
| 12101 | commercial load-balancer, and sometimes it will simply be a more complete |
| 12102 | monitoring system such as Nagios. When the tests are very frequent, users often |
| 12103 | ask how to disable logging for those checks. There are three possibilities : |
| 12104 | |
| 12105 | - if connections come from everywhere and are just TCP probes, it is often |
| 12106 | desired to simply disable logging of connections without data exchange, by |
| 12107 | setting "option dontlognull" in the frontend. It also disables logging of |
| 12108 | port scans, which may or may not be desired. |
| 12109 | |
| 12110 | - if the connection come from a known source network, use "monitor-net" to |
| 12111 | declare this network as monitoring only. Any host in this network will then |
| 12112 | only be able to perform health checks, and their requests will not be |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 12113 | logged. This is generally appropriate to designate a list of equipment |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12114 | such as other load-balancers. |
| 12115 | |
| 12116 | - if the tests are performed on a known URI, use "monitor-uri" to declare |
| 12117 | this URI as dedicated to monitoring. Any host sending this request will |
| 12118 | only get the result of a health-check, and the request will not be logged. |
| 12119 | |
| 12120 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12121 | 8.3.2. Logging before waiting for the session to terminate |
| 12122 | ---------------------------------------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12123 | |
| 12124 | The problem with logging at end of connection is that you have no clue about |
| 12125 | what is happening during very long sessions, such as remote terminal sessions |
| 12126 | or large file downloads. This problem can be worked around by specifying |
| 12127 | "option logasap" in the frontend. Haproxy will then log as soon as possible, |
| 12128 | just before data transfer begins. This means that in case of TCP, it will still |
| 12129 | log the connection status to the server, and in case of HTTP, it will log just |
| 12130 | after processing the server headers. In this case, the number of bytes reported |
| 12131 | is the number of header bytes sent to the client. In order to avoid confusion |
| 12132 | with normal logs, the total time field and the number of bytes are prefixed |
| 12133 | with a '+' sign which means that real numbers are certainly larger. |
| 12134 | |
| 12135 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12136 | 8.3.3. Raising log level upon errors |
| 12137 | ------------------------------------ |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 12138 | |
| 12139 | Sometimes it is more convenient to separate normal traffic from errors logs, |
| 12140 | for instance in order to ease error monitoring from log files. When the option |
| 12141 | "log-separate-errors" is used, connections which experience errors, timeouts, |
| 12142 | retries, redispatches or HTTP status codes 5xx will see their syslog level |
| 12143 | raised from "info" to "err". This will help a syslog daemon store the log in |
| 12144 | a separate file. It is very important to keep the errors in the normal traffic |
| 12145 | file too, so that log ordering is not altered. You should also be careful if |
| 12146 | you already have configured your syslog daemon to store all logs higher than |
| 12147 | "notice" in an "admin" file, because the "err" level is higher than "notice". |
| 12148 | |
| 12149 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12150 | 8.3.4. Disabling logging of successful connections |
| 12151 | -------------------------------------------------- |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 12152 | |
| 12153 | Although this may sound strange at first, some large sites have to deal with |
| 12154 | multiple thousands of logs per second and are experiencing difficulties keeping |
| 12155 | them intact for a long time or detecting errors within them. If the option |
| 12156 | "dontlog-normal" is set on the frontend, all normal connections will not be |
| 12157 | logged. In this regard, a normal connection is defined as one without any |
| 12158 | error, timeout, retry nor redispatch. In HTTP, the status code is checked too, |
| 12159 | and a response with a status 5xx is not considered normal and will be logged |
| 12160 | too. Of course, doing is is really discouraged as it will remove most of the |
| 12161 | useful information from the logs. Do this only if you have no other |
| 12162 | alternative. |
| 12163 | |
| 12164 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12165 | 8.4. Timing events |
| 12166 | ------------------ |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12167 | |
| 12168 | Timers provide a great help in troubleshooting network problems. All values are |
| 12169 | reported in milliseconds (ms). These timers should be used in conjunction with |
| 12170 | the session termination flags. In TCP mode with "option tcplog" set on the |
| 12171 | frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP |
| 12172 | mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" : |
| 12173 | |
| 12174 | - Tq: total time to get the client request (HTTP mode only). It's the time |
| 12175 | elapsed between the moment the client connection was accepted and the |
| 12176 | moment the proxy received the last HTTP header. The value "-1" indicates |
| 12177 | that the end of headers (empty line) has never been seen. This happens when |
| 12178 | the client closes prematurely or times out. |
| 12179 | |
| 12180 | - Tw: total time spent in the queues waiting for a connection slot. It |
| 12181 | accounts for backend queue as well as the server queues, and depends on the |
| 12182 | queue size, and the time needed for the server to complete previous |
| 12183 | requests. The value "-1" means that the request was killed before reaching |
| 12184 | the queue, which is generally what happens with invalid or denied requests. |
| 12185 | |
| 12186 | - Tc: total time to establish the TCP connection to the server. It's the time |
| 12187 | elapsed between the moment the proxy sent the connection request, and the |
| 12188 | moment it was acknowledged by the server, or between the TCP SYN packet and |
| 12189 | the matching SYN/ACK packet in return. The value "-1" means that the |
| 12190 | connection never established. |
| 12191 | |
| 12192 | - Tr: server response time (HTTP mode only). It's the time elapsed between |
| 12193 | the moment the TCP connection was established to the server and the moment |
| 12194 | the server sent its complete response headers. It purely shows its request |
| 12195 | processing time, without the network overhead due to the data transmission. |
| 12196 | It is worth noting that when the client has data to send to the server, for |
| 12197 | instance during a POST request, the time already runs, and this can distort |
| 12198 | apparent response time. For this reason, it's generally wise not to trust |
| 12199 | too much this field for POST requests initiated from clients behind an |
| 12200 | untrusted network. A value of "-1" here means that the last the response |
| 12201 | header (empty line) was never seen, most likely because the server timeout |
| 12202 | stroke before the server managed to process the request. |
| 12203 | |
| 12204 | - Tt: total session duration time, between the moment the proxy accepted it |
| 12205 | and the moment both ends were closed. The exception is when the "logasap" |
| 12206 | option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is |
| 12207 | prefixed with a '+' sign. From this field, we can deduce "Td", the data |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 12208 | transmission time, by subtracting other timers when valid : |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12209 | |
| 12210 | Td = Tt - (Tq + Tw + Tc + Tr) |
| 12211 | |
| 12212 | Timers with "-1" values have to be excluded from this equation. In TCP |
| 12213 | mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be |
| 12214 | negative. |
| 12215 | |
| 12216 | These timers provide precious indications on trouble causes. Since the TCP |
| 12217 | protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure |
| 12218 | that timers close to multiples of 3s are nearly always related to lost packets |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12219 | due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12220 | close to a timeout value specified in the configuration, it often means that a |
| 12221 | session has been aborted on timeout. |
| 12222 | |
| 12223 | Most common cases : |
| 12224 | |
| 12225 | - If "Tq" is close to 3000, a packet has probably been lost between the |
| 12226 | client and the proxy. This is very rare on local networks but might happen |
| 12227 | when clients are on far remote networks and send large requests. It may |
| 12228 | happen that values larger than usual appear here without any network cause. |
| 12229 | Sometimes, during an attack or just after a resource starvation has ended, |
| 12230 | haproxy may accept thousands of connections in a few milliseconds. The time |
| 12231 | spent accepting these connections will inevitably slightly delay processing |
| 12232 | of other connections, and it can happen that request times in the order of |
| 12233 | a few tens of milliseconds are measured after a few thousands of new |
Patrick Mezard | 105faca | 2010-06-12 17:02:46 +0200 | [diff] [blame] | 12234 | connections have been accepted at once. Setting "option http-server-close" |
| 12235 | may display larger request times since "Tq" also measures the time spent |
| 12236 | waiting for additional requests. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12237 | |
| 12238 | - If "Tc" is close to 3000, a packet has probably been lost between the |
| 12239 | server and the proxy during the server connection phase. This value should |
| 12240 | always be very low, such as 1 ms on local networks and less than a few tens |
| 12241 | of ms on remote networks. |
| 12242 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 12243 | - If "Tr" is nearly always lower than 3000 except some rare values which seem |
| 12244 | to be the average majored by 3000, there are probably some packets lost |
| 12245 | between the proxy and the server. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12246 | |
| 12247 | - If "Tt" is large even for small byte counts, it generally is because |
| 12248 | neither the client nor the server decides to close the connection, for |
| 12249 | instance because both have agreed on a keep-alive connection mode. In order |
| 12250 | to solve this issue, it will be needed to specify "option httpclose" on |
| 12251 | either the frontend or the backend. If the problem persists, it means that |
| 12252 | the server ignores the "close" connection mode and expects the client to |
| 12253 | close. Then it will be required to use "option forceclose". Having the |
| 12254 | smallest possible 'Tt' is important when connection regulation is used with |
| 12255 | the "maxconn" option on the servers, since no new connection will be sent |
| 12256 | to the server until another one is released. |
| 12257 | |
| 12258 | Other noticeable HTTP log cases ('xx' means any value to be ignored) : |
| 12259 | |
| 12260 | Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log |
| 12261 | was emitted before the data phase. All the timers are valid |
| 12262 | except "Tt" which is shorter than reality. |
| 12263 | |
| 12264 | -1/xx/xx/xx/Tt The client was not able to send a complete request in time |
| 12265 | or it aborted too early. Check the session termination flags |
| 12266 | then "timeout http-request" and "timeout client" settings. |
| 12267 | |
| 12268 | Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because |
| 12269 | servers were out of order, because the request was invalid |
| 12270 | or forbidden by ACL rules. Check the session termination |
| 12271 | flags. |
| 12272 | |
| 12273 | Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it |
| 12274 | actively refused it or it timed out after Tt-(Tq+Tw) ms. |
| 12275 | Check the session termination flags, then check the |
| 12276 | "timeout connect" setting. Note that the tarpit action might |
| 12277 | return similar-looking patterns, with "Tw" equal to the time |
| 12278 | the client connection was maintained open. |
| 12279 | |
| 12280 | Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 12281 | a complete response in time, or it closed its connection |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12282 | unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session |
| 12283 | termination flags, then check the "timeout server" setting. |
| 12284 | |
| 12285 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12286 | 8.5. Session state at disconnection |
| 12287 | ----------------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12288 | |
| 12289 | TCP and HTTP logs provide a session termination indicator in the |
| 12290 | "termination_state" field, just before the number of active connections. It is |
| 12291 | 2-characters long in TCP mode, and is extended to 4 characters in HTTP mode, |
| 12292 | each of which has a special meaning : |
| 12293 | |
| 12294 | - On the first character, a code reporting the first event which caused the |
| 12295 | session to terminate : |
| 12296 | |
| 12297 | C : the TCP session was unexpectedly aborted by the client. |
| 12298 | |
| 12299 | S : the TCP session was unexpectedly aborted by the server, or the |
| 12300 | server explicitly refused it. |
| 12301 | |
| 12302 | P : the session was prematurely aborted by the proxy, because of a |
| 12303 | connection limit enforcement, because a DENY filter was matched, |
| 12304 | because of a security check which detected and blocked a dangerous |
| 12305 | error in server response which might have caused information leak |
Willy Tarreau | 570f221 | 2013-06-10 16:42:09 +0200 | [diff] [blame] | 12306 | (eg: cacheable cookie). |
| 12307 | |
| 12308 | L : the session was locally processed by haproxy and was not passed to |
| 12309 | a server. This is what happens for stats and redirects. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12310 | |
| 12311 | R : a resource on the proxy has been exhausted (memory, sockets, source |
| 12312 | ports, ...). Usually, this appears during the connection phase, and |
| 12313 | system logs should contain a copy of the precise error. If this |
| 12314 | happens, it must be considered as a very serious anomaly which |
| 12315 | should be fixed as soon as possible by any means. |
| 12316 | |
| 12317 | I : an internal error was identified by the proxy during a self-check. |
| 12318 | This should NEVER happen, and you are encouraged to report any log |
| 12319 | containing this, because this would almost certainly be a bug. It |
| 12320 | would be wise to preventively restart the process after such an |
| 12321 | event too, in case it would be caused by memory corruption. |
| 12322 | |
Simon Horman | 752dc4a | 2011-06-21 14:34:59 +0900 | [diff] [blame] | 12323 | D : the session was killed by haproxy because the server was detected |
| 12324 | as down and was configured to kill all connections when going down. |
| 12325 | |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 12326 | U : the session was killed by haproxy on this backup server because an |
| 12327 | active server was detected as up and was configured to kill all |
| 12328 | backup connections when going up. |
| 12329 | |
Willy Tarreau | a2a64e9 | 2011-09-07 23:01:56 +0200 | [diff] [blame] | 12330 | K : the session was actively killed by an admin operating on haproxy. |
| 12331 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12332 | c : the client-side timeout expired while waiting for the client to |
| 12333 | send or receive data. |
| 12334 | |
| 12335 | s : the server-side timeout expired while waiting for the server to |
| 12336 | send or receive data. |
| 12337 | |
| 12338 | - : normal session completion, both the client and the server closed |
| 12339 | with nothing left in the buffers. |
| 12340 | |
| 12341 | - on the second character, the TCP or HTTP session state when it was closed : |
| 12342 | |
Willy Tarreau | f7b30a9 | 2010-12-06 22:59:17 +0100 | [diff] [blame] | 12343 | R : the proxy was waiting for a complete, valid REQUEST from the client |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12344 | (HTTP mode only). Nothing was sent to any server. |
| 12345 | |
| 12346 | Q : the proxy was waiting in the QUEUE for a connection slot. This can |
| 12347 | only happen when servers have a 'maxconn' parameter set. It can |
| 12348 | also happen in the global queue after a redispatch consecutive to |
| 12349 | a failed attempt to connect to a dying server. If no redispatch is |
| 12350 | reported, then no connection attempt was made to any server. |
| 12351 | |
| 12352 | C : the proxy was waiting for the CONNECTION to establish on the |
| 12353 | server. The server might at most have noticed a connection attempt. |
| 12354 | |
| 12355 | H : the proxy was waiting for complete, valid response HEADERS from the |
| 12356 | server (HTTP only). |
| 12357 | |
| 12358 | D : the session was in the DATA phase. |
| 12359 | |
| 12360 | L : the proxy was still transmitting LAST data to the client while the |
| 12361 | server had already finished. This one is very rare as it can only |
| 12362 | happen when the client dies while receiving the last packets. |
| 12363 | |
| 12364 | T : the request was tarpitted. It has been held open with the client |
| 12365 | during the whole "timeout tarpit" duration or until the client |
| 12366 | closed, both of which will be reported in the "Tw" timer. |
| 12367 | |
| 12368 | - : normal session completion after end of data transfer. |
| 12369 | |
| 12370 | - the third character tells whether the persistence cookie was provided by |
| 12371 | the client (only in HTTP mode) : |
| 12372 | |
| 12373 | N : the client provided NO cookie. This is usually the case for new |
| 12374 | visitors, so counting the number of occurrences of this flag in the |
| 12375 | logs generally indicate a valid trend for the site frequentation. |
| 12376 | |
| 12377 | I : the client provided an INVALID cookie matching no known server. |
| 12378 | This might be caused by a recent configuration change, mixed |
Cyril Bonté | a8e7bbc | 2010-04-25 22:29:29 +0200 | [diff] [blame] | 12379 | cookies between HTTP/HTTPS sites, persistence conditionally |
| 12380 | ignored, or an attack. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12381 | |
| 12382 | D : the client provided a cookie designating a server which was DOWN, |
| 12383 | so either "option persist" was used and the client was sent to |
| 12384 | this server, or it was not set and the client was redispatched to |
| 12385 | another server. |
| 12386 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12387 | V : the client provided a VALID cookie, and was sent to the associated |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12388 | server. |
| 12389 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12390 | E : the client provided a valid cookie, but with a last date which was |
| 12391 | older than what is allowed by the "maxidle" cookie parameter, so |
| 12392 | the cookie is consider EXPIRED and is ignored. The request will be |
| 12393 | redispatched just as if there was no cookie. |
| 12394 | |
| 12395 | O : the client provided a valid cookie, but with a first date which was |
| 12396 | older than what is allowed by the "maxlife" cookie parameter, so |
| 12397 | the cookie is consider too OLD and is ignored. The request will be |
| 12398 | redispatched just as if there was no cookie. |
| 12399 | |
Willy Tarreau | c89ccb6 | 2012-04-05 21:18:22 +0200 | [diff] [blame] | 12400 | U : a cookie was present but was not used to select the server because |
| 12401 | some other server selection mechanism was used instead (typically a |
| 12402 | "use-server" rule). |
| 12403 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12404 | - : does not apply (no cookie set in configuration). |
| 12405 | |
| 12406 | - the last character reports what operations were performed on the persistence |
| 12407 | cookie returned by the server (only in HTTP mode) : |
| 12408 | |
| 12409 | N : NO cookie was provided by the server, and none was inserted either. |
| 12410 | |
| 12411 | I : no cookie was provided by the server, and the proxy INSERTED one. |
| 12412 | Note that in "cookie insert" mode, if the server provides a cookie, |
| 12413 | it will still be overwritten and reported as "I" here. |
| 12414 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12415 | U : the proxy UPDATED the last date in the cookie that was presented by |
| 12416 | the client. This can only happen in insert mode with "maxidle". It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 12417 | happens every time there is activity at a different date than the |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12418 | date indicated in the cookie. If any other change happens, such as |
| 12419 | a redispatch, then the cookie will be marked as inserted instead. |
| 12420 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12421 | P : a cookie was PROVIDED by the server and transmitted as-is. |
| 12422 | |
| 12423 | R : the cookie provided by the server was REWRITTEN by the proxy, which |
| 12424 | happens in "cookie rewrite" or "cookie prefix" modes. |
| 12425 | |
| 12426 | D : the cookie provided by the server was DELETED by the proxy. |
| 12427 | |
| 12428 | - : does not apply (no cookie set in configuration). |
| 12429 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12430 | The combination of the two first flags gives a lot of information about what |
| 12431 | was happening when the session terminated, and why it did terminate. It can be |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12432 | helpful to detect server saturation, network troubles, local system resource |
| 12433 | starvation, attacks, etc... |
| 12434 | |
| 12435 | The most common termination flags combinations are indicated below. They are |
| 12436 | alphabetically sorted, with the lowercase set just after the upper case for |
| 12437 | easier finding and understanding. |
| 12438 | |
| 12439 | Flags Reason |
| 12440 | |
| 12441 | -- Normal termination. |
| 12442 | |
| 12443 | CC The client aborted before the connection could be established to the |
| 12444 | server. This can happen when haproxy tries to connect to a recently |
| 12445 | dead (or unchecked) server, and the client aborts while haproxy is |
| 12446 | waiting for the server to respond or for "timeout connect" to expire. |
| 12447 | |
| 12448 | CD The client unexpectedly aborted during data transfer. This can be |
| 12449 | caused by a browser crash, by an intermediate equipment between the |
| 12450 | client and haproxy which decided to actively break the connection, |
| 12451 | by network routing issues between the client and haproxy, or by a |
| 12452 | keep-alive session between the server and the client terminated first |
| 12453 | by the client. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 12454 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12455 | cD The client did not send nor acknowledge any data for as long as the |
| 12456 | "timeout client" delay. This is often caused by network failures on |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 12457 | the client side, or the client simply leaving the net uncleanly. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12458 | |
| 12459 | CH The client aborted while waiting for the server to start responding. |
| 12460 | It might be the server taking too long to respond or the client |
| 12461 | clicking the 'Stop' button too fast. |
| 12462 | |
| 12463 | cH The "timeout client" stroke while waiting for client data during a |
| 12464 | POST request. This is sometimes caused by too large TCP MSS values |
| 12465 | for PPPoE networks which cannot transport full-sized packets. It can |
| 12466 | also happen when client timeout is smaller than server timeout and |
| 12467 | the server takes too long to respond. |
| 12468 | |
| 12469 | CQ The client aborted while its session was queued, waiting for a server |
| 12470 | with enough empty slots to accept it. It might be that either all the |
| 12471 | servers were saturated or that the assigned server was taking too |
| 12472 | long a time to respond. |
| 12473 | |
| 12474 | CR The client aborted before sending a full HTTP request. Most likely |
| 12475 | the request was typed by hand using a telnet client, and aborted |
| 12476 | too early. The HTTP status code is likely a 400 here. Sometimes this |
| 12477 | might also be caused by an IDS killing the connection between haproxy |
| 12478 | and the client. |
| 12479 | |
| 12480 | cR The "timeout http-request" stroke before the client sent a full HTTP |
| 12481 | request. This is sometimes caused by too large TCP MSS values on the |
| 12482 | client side for PPPoE networks which cannot transport full-sized |
| 12483 | packets, or by clients sending requests by hand and not typing fast |
| 12484 | enough, or forgetting to enter the empty line at the end of the |
| 12485 | request. The HTTP status code is likely a 408 here. |
| 12486 | |
| 12487 | CT The client aborted while its session was tarpitted. It is important to |
| 12488 | check if this happens on valid requests, in order to be sure that no |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 12489 | wrong tarpit rules have been written. If a lot of them happen, it |
| 12490 | might make sense to lower the "timeout tarpit" value to something |
| 12491 | closer to the average reported "Tw" timer, in order not to consume |
| 12492 | resources for just a few attackers. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12493 | |
Willy Tarreau | 570f221 | 2013-06-10 16:42:09 +0200 | [diff] [blame] | 12494 | LR The request was intercepted and locally handled by haproxy. Generally |
| 12495 | it means that this was a redirect or a stats request. |
| 12496 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12497 | SC The server or an equipment between it and haproxy explicitly refused |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12498 | the TCP connection (the proxy received a TCP RST or an ICMP message |
| 12499 | in return). Under some circumstances, it can also be the network |
| 12500 | stack telling the proxy that the server is unreachable (eg: no route, |
| 12501 | or no ARP response on local network). When this happens in HTTP mode, |
| 12502 | the status code is likely a 502 or 503 here. |
| 12503 | |
| 12504 | sC The "timeout connect" stroke before a connection to the server could |
| 12505 | complete. When this happens in HTTP mode, the status code is likely a |
| 12506 | 503 or 504 here. |
| 12507 | |
| 12508 | SD The connection to the server died with an error during the data |
| 12509 | transfer. This usually means that haproxy has received an RST from |
| 12510 | the server or an ICMP message from an intermediate equipment while |
| 12511 | exchanging data with the server. This can be caused by a server crash |
| 12512 | or by a network issue on an intermediate equipment. |
| 12513 | |
| 12514 | sD The server did not send nor acknowledge any data for as long as the |
| 12515 | "timeout server" setting during the data phase. This is often caused |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12516 | by too short timeouts on L4 equipments before the server (firewalls, |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12517 | load-balancers, ...), as well as keep-alive sessions maintained |
| 12518 | between the client and the server expiring first on haproxy. |
| 12519 | |
| 12520 | SH The server aborted before sending its full HTTP response headers, or |
| 12521 | it crashed while processing the request. Since a server aborting at |
| 12522 | this moment is very rare, it would be wise to inspect its logs to |
| 12523 | control whether it crashed and why. The logged request may indicate a |
| 12524 | small set of faulty requests, demonstrating bugs in the application. |
| 12525 | Sometimes this might also be caused by an IDS killing the connection |
| 12526 | between haproxy and the server. |
| 12527 | |
| 12528 | sH The "timeout server" stroke before the server could return its |
| 12529 | response headers. This is the most common anomaly, indicating too |
| 12530 | long transactions, probably caused by server or database saturation. |
| 12531 | The immediate workaround consists in increasing the "timeout server" |
| 12532 | setting, but it is important to keep in mind that the user experience |
| 12533 | will suffer from these long response times. The only long term |
| 12534 | solution is to fix the application. |
| 12535 | |
| 12536 | sQ The session spent too much time in queue and has been expired. See |
| 12537 | the "timeout queue" and "timeout connect" settings to find out how to |
| 12538 | fix this if it happens too often. If it often happens massively in |
| 12539 | short periods, it may indicate general problems on the affected |
| 12540 | servers due to I/O or database congestion, or saturation caused by |
| 12541 | external attacks. |
| 12542 | |
| 12543 | PC The proxy refused to establish a connection to the server because the |
| 12544 | process' socket limit has been reached while attempting to connect. |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 12545 | The global "maxconn" parameter may be increased in the configuration |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12546 | so that it does not happen anymore. This status is very rare and |
| 12547 | might happen when the global "ulimit-n" parameter is forced by hand. |
| 12548 | |
Willy Tarreau | ed2fd2d | 2010-12-29 11:23:27 +0100 | [diff] [blame] | 12549 | PD The proxy blocked an incorrectly formatted chunked encoded message in |
| 12550 | a request or a response, after the server has emitted its headers. In |
| 12551 | most cases, this will indicate an invalid message from the server to |
Willy Tarreau | f3a3e13 | 2013-08-31 08:16:26 +0200 | [diff] [blame] | 12552 | the client. Haproxy supports chunk sizes of up to 2GB - 1 (2147483647 |
| 12553 | bytes). Any larger size will be considered as an error. |
Willy Tarreau | ed2fd2d | 2010-12-29 11:23:27 +0100 | [diff] [blame] | 12554 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12555 | PH The proxy blocked the server's response, because it was invalid, |
| 12556 | incomplete, dangerous (cache control), or matched a security filter. |
| 12557 | In any case, an HTTP 502 error is sent to the client. One possible |
| 12558 | cause for this error is an invalid syntax in an HTTP header name |
Willy Tarreau | ed2fd2d | 2010-12-29 11:23:27 +0100 | [diff] [blame] | 12559 | containing unauthorized characters. It is also possible but quite |
| 12560 | rare, that the proxy blocked a chunked-encoding request from the |
| 12561 | client due to an invalid syntax, before the server responded. In this |
| 12562 | case, an HTTP 400 error is sent to the client and reported in the |
| 12563 | logs. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12564 | |
| 12565 | PR The proxy blocked the client's HTTP request, either because of an |
| 12566 | invalid HTTP syntax, in which case it returned an HTTP 400 error to |
| 12567 | the client, or because a deny filter matched, in which case it |
| 12568 | returned an HTTP 403 error. |
| 12569 | |
| 12570 | PT The proxy blocked the client's request and has tarpitted its |
| 12571 | connection before returning it a 500 server error. Nothing was sent |
| 12572 | to the server. The connection was maintained open for as long as |
| 12573 | reported by the "Tw" timer field. |
| 12574 | |
| 12575 | RC A local resource has been exhausted (memory, sockets, source ports) |
| 12576 | preventing the connection to the server from establishing. The error |
| 12577 | logs will tell precisely what was missing. This is very rare and can |
| 12578 | only be solved by proper system tuning. |
| 12579 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12580 | The combination of the two last flags gives a lot of information about how |
| 12581 | persistence was handled by the client, the server and by haproxy. This is very |
| 12582 | important to troubleshoot disconnections, when users complain they have to |
| 12583 | re-authenticate. The commonly encountered flags are : |
| 12584 | |
| 12585 | -- Persistence cookie is not enabled. |
| 12586 | |
| 12587 | NN No cookie was provided by the client, none was inserted in the |
| 12588 | response. For instance, this can be in insert mode with "postonly" |
| 12589 | set on a GET request. |
| 12590 | |
| 12591 | II A cookie designating an invalid server was provided by the client, |
| 12592 | a valid one was inserted in the response. This typically happens when |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 12593 | a "server" entry is removed from the configuration, since its cookie |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 12594 | value can be presented by a client when no other server knows it. |
| 12595 | |
| 12596 | NI No cookie was provided by the client, one was inserted in the |
| 12597 | response. This typically happens for first requests from every user |
| 12598 | in "insert" mode, which makes it an easy way to count real users. |
| 12599 | |
| 12600 | VN A cookie was provided by the client, none was inserted in the |
| 12601 | response. This happens for most responses for which the client has |
| 12602 | already got a cookie. |
| 12603 | |
| 12604 | VU A cookie was provided by the client, with a last visit date which is |
| 12605 | not completely up-to-date, so an updated cookie was provided in |
| 12606 | response. This can also happen if there was no date at all, or if |
| 12607 | there was a date but the "maxidle" parameter was not set, so that the |
| 12608 | cookie can be switched to unlimited time. |
| 12609 | |
| 12610 | EI A cookie was provided by the client, with a last visit date which is |
| 12611 | too old for the "maxidle" parameter, so the cookie was ignored and a |
| 12612 | new cookie was inserted in the response. |
| 12613 | |
| 12614 | OI A cookie was provided by the client, with a first visit date which is |
| 12615 | too old for the "maxlife" parameter, so the cookie was ignored and a |
| 12616 | new cookie was inserted in the response. |
| 12617 | |
| 12618 | DI The server designated by the cookie was down, a new server was |
| 12619 | selected and a new cookie was emitted in the response. |
| 12620 | |
| 12621 | VI The server designated by the cookie was not marked dead but could not |
| 12622 | be reached. A redispatch happened and selected another one, which was |
| 12623 | then advertised in the response. |
| 12624 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12625 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12626 | 8.6. Non-printable characters |
| 12627 | ----------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12628 | |
| 12629 | In order not to cause trouble to log analysis tools or terminals during log |
| 12630 | consulting, non-printable characters are not sent as-is into log files, but are |
| 12631 | converted to the two-digits hexadecimal representation of their ASCII code, |
| 12632 | prefixed by the character '#'. The only characters that can be logged without |
| 12633 | being escaped are comprised between 32 and 126 (inclusive). Obviously, the |
| 12634 | escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It |
| 12635 | is the same for the character '"' which becomes "#22", as well as '{', '|' and |
| 12636 | '}' when logging headers. |
| 12637 | |
| 12638 | Note that the space character (' ') is not encoded in headers, which can cause |
| 12639 | issues for tools relying on space count to locate fields. A typical header |
| 12640 | containing spaces is "User-Agent". |
| 12641 | |
| 12642 | Last, it has been observed that some syslog daemons such as syslog-ng escape |
| 12643 | the quote ('"') with a backslash ('\'). The reverse operation can safely be |
| 12644 | performed since no quote may appear anywhere else in the logs. |
| 12645 | |
| 12646 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12647 | 8.7. Capturing HTTP cookies |
| 12648 | --------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12649 | |
| 12650 | Cookie capture simplifies the tracking a complete user session. This can be |
| 12651 | achieved using the "capture cookie" statement in the frontend. Please refer to |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12652 | section 4.2 for more details. Only one cookie can be captured, and the same |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12653 | cookie will simultaneously be checked in the request ("Cookie:" header) and in |
| 12654 | the response ("Set-Cookie:" header). The respective values will be reported in |
| 12655 | the HTTP logs at the "captured_request_cookie" and "captured_response_cookie" |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12656 | locations (see section 8.2.3 about HTTP log format). When either cookie is |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12657 | not seen, a dash ('-') replaces the value. This way, it's easy to detect when a |
| 12658 | user switches to a new session for example, because the server will reassign it |
| 12659 | a new cookie. It is also possible to detect if a server unexpectedly sets a |
| 12660 | wrong cookie to a client, leading to session crossing. |
| 12661 | |
| 12662 | Examples : |
| 12663 | # capture the first cookie whose name starts with "ASPSESSION" |
| 12664 | capture cookie ASPSESSION len 32 |
| 12665 | |
| 12666 | # capture the first cookie whose name is exactly "vgnvisitor" |
| 12667 | capture cookie vgnvisitor= len 32 |
| 12668 | |
| 12669 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12670 | 8.8. Capturing HTTP headers |
| 12671 | --------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12672 | |
| 12673 | Header captures are useful to track unique request identifiers set by an upper |
| 12674 | proxy, virtual host names, user-agents, POST content-length, referrers, etc. In |
| 12675 | the response, one can search for information about the response length, how the |
| 12676 | server asked the cache to behave, or an object location during a redirection. |
| 12677 | |
| 12678 | Header captures are performed using the "capture request header" and "capture |
| 12679 | response header" statements in the frontend. Please consult their definition in |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12680 | section 4.2 for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12681 | |
| 12682 | It is possible to include both request headers and response headers at the same |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12683 | time. Non-existent headers are logged as empty strings, and if one header |
| 12684 | appears more than once, only its last occurrence will be logged. Request headers |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12685 | are grouped within braces '{' and '}' in the same order as they were declared, |
| 12686 | and delimited with a vertical bar '|' without any space. Response headers |
| 12687 | follow the same representation, but are displayed after a space following the |
| 12688 | request headers block. These blocks are displayed just before the HTTP request |
| 12689 | in the logs. |
| 12690 | |
| 12691 | Example : |
| 12692 | # This instance chains to the outgoing proxy |
| 12693 | listen proxy-out |
| 12694 | mode http |
| 12695 | option httplog |
| 12696 | option logasap |
| 12697 | log global |
| 12698 | server cache1 192.168.1.1:3128 |
| 12699 | |
| 12700 | # log the name of the virtual server |
| 12701 | capture request header Host len 20 |
| 12702 | |
| 12703 | # log the amount of data uploaded during a POST |
| 12704 | capture request header Content-Length len 10 |
| 12705 | |
| 12706 | # log the beginning of the referrer |
| 12707 | capture request header Referer len 20 |
| 12708 | |
| 12709 | # server name (useful for outgoing proxies only) |
| 12710 | capture response header Server len 20 |
| 12711 | |
| 12712 | # logging the content-length is useful with "option logasap" |
| 12713 | capture response header Content-Length len 10 |
| 12714 | |
| 12715 | # log the expected cache behaviour on the response |
| 12716 | capture response header Cache-Control len 8 |
| 12717 | |
| 12718 | # the Via header will report the next proxy's name |
| 12719 | capture response header Via len 20 |
| 12720 | |
| 12721 | # log the URL location during a redirection |
| 12722 | capture response header Location len 20 |
| 12723 | |
| 12724 | >>> Aug 9 20:26:09 localhost \ |
| 12725 | haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \ |
| 12726 | proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \ |
| 12727 | {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \ |
| 12728 | "GET http://fr.adserver.yahoo.com/" |
| 12729 | |
| 12730 | >>> Aug 9 20:30:46 localhost \ |
| 12731 | haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \ |
| 12732 | proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \ |
| 12733 | {w.ods.org||} {Formilux/0.1.8|3495|||} \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 12734 | "GET http://trafic.1wt.eu/ HTTP/1.1" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12735 | |
| 12736 | >>> Aug 9 20:30:46 localhost \ |
| 12737 | haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \ |
| 12738 | proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \ |
| 12739 | {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \ |
| 12740 | {Apache|230|||http://www.sytadin.} \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 12741 | "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12742 | |
| 12743 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12744 | 8.9. Examples of logs |
| 12745 | --------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12746 | |
| 12747 | These are real-world examples of logs accompanied with an explanation. Some of |
| 12748 | them have been made up by hand. The syslog part has been removed for better |
| 12749 | reading. Their sole purpose is to explain how to decipher them. |
| 12750 | |
| 12751 | >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \ |
| 12752 | px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \ |
| 12753 | "HEAD / HTTP/1.0" |
| 12754 | |
| 12755 | => long request (6.5s) entered by hand through 'telnet'. The server replied |
| 12756 | in 147 ms, and the session ended normally ('----') |
| 12757 | |
| 12758 | >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \ |
| 12759 | px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \ |
| 12760 | 0/9 "HEAD / HTTP/1.0" |
| 12761 | |
| 12762 | => Idem, but the request was queued in the global queue behind 9 other |
| 12763 | requests, and waited there for 1230 ms. |
| 12764 | |
| 12765 | >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \ |
| 12766 | px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \ |
| 12767 | "GET /image.iso HTTP/1.0" |
| 12768 | |
| 12769 | => request for a long data transfer. The "logasap" option was specified, so |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12770 | the log was produced just before transferring data. The server replied in |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12771 | 14 ms, 243 bytes of headers were sent to the client, and total time from |
| 12772 | accept to first data byte is 30 ms. |
| 12773 | |
| 12774 | >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \ |
| 12775 | px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \ |
| 12776 | "GET /cgi-bin/bug.cgi? HTTP/1.0" |
| 12777 | |
| 12778 | => the proxy blocked a server response either because of an "rspdeny" or |
| 12779 | "rspideny" filter, or because the response was improperly formatted and |
Willy Tarreau | 3c92c5f | 2011-08-28 09:45:47 +0200 | [diff] [blame] | 12780 | not HTTP-compliant, or because it blocked sensitive information which |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12781 | risked being cached. In this case, the response is replaced with a "502 |
| 12782 | bad gateway". The flags ("PH--") tell us that it was haproxy who decided |
| 12783 | to return the 502 and not the server. |
| 12784 | |
| 12785 | >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 12786 | px-http/<NOSRV> -1/-1/-1/-1/8490 -1 0 - - CR-- 2/2/2/0/0 0/0 "" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12787 | |
| 12788 | => the client never completed its request and aborted itself ("C---") after |
| 12789 | 8.5s, while the proxy was waiting for the request headers ("-R--"). |
| 12790 | Nothing was sent to any server. |
| 12791 | |
| 12792 | >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \ |
| 12793 | px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 "" |
| 12794 | |
| 12795 | => The client never completed its request, which was aborted by the |
| 12796 | time-out ("c---") after 50s, while the proxy was waiting for the request |
| 12797 | headers ("-R--"). Nothing was sent to any server, but the proxy could |
| 12798 | send a 408 return code to the client. |
| 12799 | |
| 12800 | >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \ |
| 12801 | px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0 |
| 12802 | |
| 12803 | => This log was produced with "option tcplog". The client timed out after |
| 12804 | 5 seconds ("c----"). |
| 12805 | |
| 12806 | >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \ |
| 12807 | px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 12808 | 0/0 "HEAD / HTTP/1.0" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12809 | |
| 12810 | => The request took 3s to complete (probably a network problem), and the |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12811 | connection to the server failed ('SC--') after 4 attempts of 2 seconds |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 12812 | (config says 'retries 3'), and no redispatch (otherwise we would have |
| 12813 | seen "/+3"). Status code 503 was returned to the client. There were 115 |
| 12814 | connections on this server, 202 connections on this proxy, and 205 on |
| 12815 | the global process. It is possible that the server refused the |
| 12816 | connection because of too many already established. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12817 | |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 12818 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12819 | 9. Statistics and monitoring |
| 12820 | ---------------------------- |
| 12821 | |
| 12822 | It is possible to query HAProxy about its status. The most commonly used |
| 12823 | mechanism is the HTTP statistics page. This page also exposes an alternative |
| 12824 | CSV output format for monitoring tools. The same format is provided on the |
| 12825 | Unix socket. |
| 12826 | |
| 12827 | |
| 12828 | 9.1. CSV format |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 12829 | --------------- |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 12830 | |
Willy Tarreau | 7f062c4 | 2009-03-05 18:43:00 +0100 | [diff] [blame] | 12831 | The statistics may be consulted either from the unix socket or from the HTTP |
| 12832 | page. Both means provide a CSV format whose fields follow. |
| 12833 | |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 12834 | 0. pxname: proxy name |
| 12835 | 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name |
| 12836 | for server) |
| 12837 | 2. qcur: current queued requests |
| 12838 | 3. qmax: max queued requests |
| 12839 | 4. scur: current sessions |
| 12840 | 5. smax: max sessions |
| 12841 | 6. slim: sessions limit |
| 12842 | 7. stot: total sessions |
| 12843 | 8. bin: bytes in |
| 12844 | 9. bout: bytes out |
| 12845 | 10. dreq: denied requests |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 12846 | 11. dresp: denied responses |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 12847 | 12. ereq: request errors |
| 12848 | 13. econ: connection errors |
Willy Tarreau | ae52678 | 2010-03-04 20:34:23 +0100 | [diff] [blame] | 12849 | 14. eresp: response errors (among which srv_abrt) |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 12850 | 15. wretr: retries (warning) |
| 12851 | 16. wredis: redispatches (warning) |
Cyril Bonté | 0dae585 | 2010-02-03 00:26:28 +0100 | [diff] [blame] | 12852 | 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...) |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 12853 | 18. weight: server weight (server), total weight (backend) |
| 12854 | 19. act: server is active (server), number of active servers (backend) |
| 12855 | 20. bck: server is backup (server), number of backup servers (backend) |
| 12856 | 21. chkfail: number of failed checks |
| 12857 | 22. chkdown: number of UP->DOWN transitions |
| 12858 | 23. lastchg: last status change (in seconds) |
| 12859 | 24. downtime: total downtime (in seconds) |
| 12860 | 25. qlimit: queue limit |
| 12861 | 26. pid: process id (0 for first instance, 1 for second, ...) |
| 12862 | 27. iid: unique proxy id |
| 12863 | 28. sid: service id (unique inside a proxy) |
| 12864 | 29. throttle: warm up status |
| 12865 | 30. lbtot: total number of times a server was selected |
| 12866 | 31. tracked: id of proxy/server if tracking is enabled |
Krzysztof Piotr Oledzki | aeebf9b | 2009-10-04 15:43:17 +0200 | [diff] [blame] | 12867 | 32. type (0=frontend, 1=backend, 2=server, 3=socket) |
Krzysztof Piotr Oledzki | db57c6b | 2009-08-31 21:23:27 +0200 | [diff] [blame] | 12868 | 33. rate: number of sessions per second over last elapsed second |
| 12869 | 34. rate_lim: limit on new sessions per second |
| 12870 | 35. rate_max: max number of new sessions per second |
Krzysztof Piotr Oledzki | 0960541 | 2009-09-23 22:09:24 +0200 | [diff] [blame] | 12871 | 36. check_status: status of last health check, one of: |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 12872 | UNK -> unknown |
| 12873 | INI -> initializing |
| 12874 | SOCKERR -> socket error |
| 12875 | L4OK -> check passed on layer 4, no upper layers testing enabled |
| 12876 | L4TMOUT -> layer 1-4 timeout |
| 12877 | L4CON -> layer 1-4 connection problem, for example |
| 12878 | "Connection refused" (tcp rst) or "No route to host" (icmp) |
| 12879 | L6OK -> check passed on layer 6 |
| 12880 | L6TOUT -> layer 6 (SSL) timeout |
| 12881 | L6RSP -> layer 6 invalid response - protocol error |
| 12882 | L7OK -> check passed on layer 7 |
| 12883 | L7OKC -> check conditionally passed on layer 7, for example 404 with |
| 12884 | disable-on-404 |
| 12885 | L7TOUT -> layer 7 (HTTP/SMTP) timeout |
| 12886 | L7RSP -> layer 7 invalid response - protocol error |
| 12887 | L7STS -> layer 7 response error, for example HTTP 5xx |
Krzysztof Piotr Oledzki | 0960541 | 2009-09-23 22:09:24 +0200 | [diff] [blame] | 12888 | 37. check_code: layer5-7 code, if available |
| 12889 | 38. check_duration: time in ms took to finish last health check |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12890 | 39. hrsp_1xx: http responses with 1xx code |
| 12891 | 40. hrsp_2xx: http responses with 2xx code |
| 12892 | 41. hrsp_3xx: http responses with 3xx code |
| 12893 | 42. hrsp_4xx: http responses with 4xx code |
| 12894 | 43. hrsp_5xx: http responses with 5xx code |
| 12895 | 44. hrsp_other: http responses with other codes (protocol error) |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 12896 | 45. hanafail: failed health checks details |
| 12897 | 46. req_rate: HTTP requests per second over last elapsed second |
| 12898 | 47. req_rate_max: max number of HTTP requests per second observed |
| 12899 | 48. req_tot: total number of HTTP requests received |
Willy Tarreau | ae52678 | 2010-03-04 20:34:23 +0100 | [diff] [blame] | 12900 | 49. cli_abrt: number of data transfers aborted by the client |
| 12901 | 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp) |
Willy Tarreau | 55058a7 | 2012-11-21 08:27:21 +0100 | [diff] [blame] | 12902 | 51. comp_in: number of HTTP response bytes fed to the compressor |
| 12903 | 52. comp_out: number of HTTP response bytes emitted by the compressor |
| 12904 | 53. comp_byp: number of bytes that bypassed the HTTP compressor (CPU/BW limit) |
Willy Tarreau | 11d4ec8 | 2012-11-26 00:49:03 +0100 | [diff] [blame] | 12905 | 54. comp_rsp: number of HTTP responses that were compressed |
Willy Tarreau | f522f3d | 2014-02-10 22:22:49 +0100 | [diff] [blame] | 12906 | 55. lastsess: number of seconds since last session assigned to server/backend |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12907 | |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 12908 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12909 | 9.2. Unix Socket commands |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 12910 | ------------------------- |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 12911 | |
Willy Tarreau | 468f493 | 2013-08-01 16:50:16 +0200 | [diff] [blame] | 12912 | The stats socket is not enabled by default. In order to enable it, it is |
| 12913 | necessary to add one line in the global section of the haproxy configuration. |
| 12914 | A second line is recommended to set a larger timeout, always appreciated when |
| 12915 | issuing commands by hand : |
| 12916 | |
| 12917 | global |
| 12918 | stats socket /var/run/haproxy.sock mode 600 level admin |
| 12919 | stats timeout 2m |
| 12920 | |
| 12921 | It is also possible to add multiple instances of the stats socket by repeating |
| 12922 | the line, and make them listen to a TCP port instead of a UNIX socket. This is |
| 12923 | never done by default because this is dangerous, but can be handy in some |
| 12924 | situations : |
| 12925 | |
| 12926 | global |
| 12927 | stats socket /var/run/haproxy.sock mode 600 level admin |
| 12928 | stats socket ipv4@192.168.0.1:9999 level admin |
| 12929 | stats timeout 2m |
| 12930 | |
| 12931 | To access the socket, an external utility such as "socat" is required. Socat is a |
| 12932 | swiss-army knife to connect anything to anything. We use it to connect terminals |
| 12933 | to the socket, or a couple of stdin/stdout pipes to it for scripts. The two main |
| 12934 | syntaxes we'll use are the following : |
| 12935 | |
| 12936 | # socat /var/run/haproxy.sock stdio |
| 12937 | # socat /var/run/haproxy.sock readline |
| 12938 | |
| 12939 | The first one is used with scripts. It is possible to send the output of a |
| 12940 | script to haproxy, and pass haproxy's output to another script. That's useful |
| 12941 | for retrieving counters or attack traces for example. |
| 12942 | |
| 12943 | The second one is only useful for issuing commands by hand. It has the benefit |
| 12944 | that the terminal is handled by the readline library which supports line |
| 12945 | editing and history, which is very convenient when issuing repeated commands |
| 12946 | (eg: watch a counter). |
| 12947 | |
| 12948 | The socket supports two operation modes : |
| 12949 | - interactive |
| 12950 | - non-interactive |
| 12951 | |
| 12952 | The non-interactive mode is the default when socat connects to the socket. In |
| 12953 | this mode, a single line may be sent. It is processed as a whole, responses are |
| 12954 | sent back, and the connection closes after the end of the response. This is the |
| 12955 | mode that scripts and monitoring tools use. It is possible to send multiple |
| 12956 | commands in this mode, they need to be delimited by a semi-colon (';'). For |
| 12957 | example : |
| 12958 | |
| 12959 | # echo "show info;show stat;show table" | socat /var/run/haproxy stdio |
| 12960 | |
| 12961 | The interactive mode displays a prompt ('>') and waits for commands to be |
| 12962 | entered on the line, then processes them, and displays the prompt again to wait |
| 12963 | for a new command. This mode is entered via the "prompt" command which must be |
| 12964 | sent on the first line in non-interactive mode. The mode is a flip switch, if |
| 12965 | "prompt" is sent in interactive mode, it is disabled and the connection closes |
| 12966 | after processing the last command of the same line. |
| 12967 | |
| 12968 | For this reason, when debugging by hand, it's quite common to start with the |
| 12969 | "prompt" command : |
| 12970 | |
| 12971 | # socat /var/run/haproxy readline |
| 12972 | prompt |
| 12973 | > show info |
| 12974 | ... |
| 12975 | > |
| 12976 | |
| 12977 | Since multiple commands may be issued at once, haproxy uses the empty line as a |
| 12978 | delimiter to mark an end of output for each command, and takes care of ensuring |
| 12979 | that no command can emit an empty line on output. A script can thus easily |
| 12980 | parse the output even when multiple commands were pipelined on a single line. |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 12981 | |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 12982 | It is important to understand that when multiple haproxy processes are started |
| 12983 | on the same sockets, any process may pick up the request and will output its |
| 12984 | own stats. |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 12985 | |
Willy Tarreau | 468f493 | 2013-08-01 16:50:16 +0200 | [diff] [blame] | 12986 | The list of commands currently supported on the stats socket is provided below. |
| 12987 | If an unknown command is sent, haproxy displays the usage message which reminds |
| 12988 | all supported commands. Some commands support a more complex syntax, generally |
| 12989 | it will explain what part of the command is invalid when this happens. |
| 12990 | |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 12991 | add acl <acl> <pattern> |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 12992 | Add an entry into the acl <acl>. <acl> is the #<id> or the <file> returned by |
| 12993 | "show acl". This command does not verify if the entry already exists. This |
| 12994 | command cannot be used if the reference <acl> is a file also used with a map. |
| 12995 | In this case, you must use the command "add map" in place of "add acl". |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 12996 | |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 12997 | add map <map> <key> <value> |
| 12998 | Add an entry into the map <map> to associate the value <value> to the key |
| 12999 | <key>. This command does not verify if the entry already exists. It is |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13000 | mainly used to fill a map after a clear operation. Note that if the reference |
| 13001 | <map> is a file and is shared with a map, this map will contain also a new |
| 13002 | pattern entry. |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 13003 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13004 | clear counters |
| 13005 | Clear the max values of the statistics counters in each proxy (frontend & |
| 13006 | backend) and in each server. The cumulated counters are not affected. This |
| 13007 | can be used to get clean counters after an incident, without having to |
| 13008 | restart nor to clear traffic counters. This command is restricted and can |
| 13009 | only be issued on sockets configured for levels "operator" or "admin". |
| 13010 | |
| 13011 | clear counters all |
| 13012 | Clear all statistics counters in each proxy (frontend & backend) and in each |
| 13013 | server. This has the same effect as restarting. This command is restricted |
| 13014 | and can only be issued on sockets configured for level "admin". |
| 13015 | |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13016 | clear acl <acl> |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13017 | Remove all entries from the acl <acl>. <acl> is the #<id> or the <file> |
| 13018 | returned by "show acl". Note that if the reference <acl> is a file and is |
| 13019 | shared with a map, this map will be also cleared. |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13020 | |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 13021 | clear map <map> |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13022 | Remove all entries from the map <map>. <map> is the #<id> or the <file> |
| 13023 | returned by "show map". Note that if the reference <map> is a file and is |
| 13024 | shared with a acl, this acl will be also cleared. |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 13025 | |
Simon Horman | c88b887 | 2011-06-15 15:18:49 +0900 | [diff] [blame] | 13026 | clear table <table> [ data.<type> <operator> <value> ] | [ key <key> ] |
| 13027 | Remove entries from the stick-table <table>. |
| 13028 | |
| 13029 | This is typically used to unblock some users complaining they have been |
| 13030 | abusively denied access to a service, but this can also be used to clear some |
| 13031 | stickiness entries matching a server that is going to be replaced (see "show |
| 13032 | table" below for details). Note that sometimes, removal of an entry will be |
| 13033 | refused because it is currently tracked by a session. Retrying a few seconds |
| 13034 | later after the session ends is usual enough. |
| 13035 | |
| 13036 | In the case where no options arguments are given all entries will be removed. |
| 13037 | |
| 13038 | When the "data." form is used entries matching a filter applied using the |
| 13039 | stored data (see "stick-table" in section 4.2) are removed. A stored data |
| 13040 | type must be specified in <type>, and this data type must be stored in the |
| 13041 | table otherwise an error is reported. The data is compared according to |
| 13042 | <operator> with the 64-bit integer <value>. Operators are the same as with |
| 13043 | the ACLs : |
| 13044 | |
| 13045 | - eq : match entries whose data is equal to this value |
| 13046 | - ne : match entries whose data is not equal to this value |
| 13047 | - le : match entries whose data is less than or equal to this value |
| 13048 | - ge : match entries whose data is greater than or equal to this value |
| 13049 | - lt : match entries whose data is less than this value |
| 13050 | - gt : match entries whose data is greater than this value |
| 13051 | |
| 13052 | When the key form is used the entry <key> is removed. The key must be of the |
Simon Horman | 619e3cc | 2011-06-15 15:18:52 +0900 | [diff] [blame] | 13053 | same type as the table, which currently is limited to IPv4, IPv6, integer and |
| 13054 | string. |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13055 | |
| 13056 | Example : |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13057 | $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 13058 | >>> # table: http_proxy, type: ip, size:204800, used:2 |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13059 | >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \ |
| 13060 | bytes_out_rate(60000)=187 |
| 13061 | >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| 13062 | bytes_out_rate(60000)=191 |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13063 | |
| 13064 | $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1 |
| 13065 | |
| 13066 | $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 13067 | >>> # table: http_proxy, type: ip, size:204800, used:1 |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13068 | >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| 13069 | bytes_out_rate(60000)=191 |
Simon Horman | c88b887 | 2011-06-15 15:18:49 +0900 | [diff] [blame] | 13070 | $ echo "clear table http_proxy data.gpc0 eq 1" | socat stdio /tmp/sock1 |
| 13071 | $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
| 13072 | >>> # table: http_proxy, type: ip, size:204800, used:1 |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13073 | |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13074 | del acl <acl> [<key>|#<ref>] |
| 13075 | Delete all the acl entries from the acl <acl> corresponding to the key <key>. |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13076 | <acl> is the #<id> or the <file> returned by "show acl". If the <ref> is used, |
| 13077 | this command delete only the listed reference. The reference can be found with |
| 13078 | listing the content of the acl. Note that if the reference <acl> is a file and |
| 13079 | is shared with a map, the entry will be also deleted in the map. |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13080 | |
| 13081 | del map <map> [<key>|#<ref>] |
Thierry FOURNIER | 0b90f31 | 2014-01-29 20:40:18 +0100 | [diff] [blame] | 13082 | Delete all the map entries from the map <map> corresponding to the key <key>. |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13083 | <map> is the #<id> or the <file> returned by "show map". If the <ref> is used, |
| 13084 | this command delete only the listed reference. The reference can be found with |
| 13085 | listing the content of the map. Note that if the reference <map> is a file and |
| 13086 | is shared with a acl, the entry will be also deleted in the map. |
Thierry FOURNIER | 0b90f31 | 2014-01-29 20:40:18 +0100 | [diff] [blame] | 13087 | |
| 13088 | disable agent <backend>/<server> |
Simon Horman | 671b6f0 | 2013-11-25 10:46:39 +0900 | [diff] [blame] | 13089 | Mark the auxiliary agent check as temporarily stopped. |
| 13090 | |
| 13091 | In the case where an agent check is being run as a auxiliary check, due |
| 13092 | to the agent-check parameter of a server directive, new checks are only |
| 13093 | initialised when the agent is in the enabled. Thus, disable agent will |
| 13094 | prevent any new agent checks from begin initiated until the agent |
| 13095 | re-enabled using enable agent. |
| 13096 | |
| 13097 | When an agent is disabled the processing of an auxiliary agent check that |
| 13098 | was initiated while the agent was set as enabled is as follows: All |
| 13099 | results that would alter the weight, specifically "drain" or a weight |
| 13100 | returned by the agent, are ignored. The processing of agent check is |
| 13101 | otherwise unchanged. |
| 13102 | |
| 13103 | The motivation for this feature is to allow the weight changing effects |
| 13104 | of the agent checks to be paused to allow the weight of a server to be |
| 13105 | configured using set weight without being overridden by the agent. |
| 13106 | |
| 13107 | This command is restricted and can only be issued on sockets configured for |
| 13108 | level "admin". |
| 13109 | |
Willy Tarreau | 532a450 | 2011-09-07 22:37:44 +0200 | [diff] [blame] | 13110 | disable frontend <frontend> |
| 13111 | Mark the frontend as temporarily stopped. This corresponds to the mode which |
| 13112 | is used during a soft restart : the frontend releases the port but can be |
| 13113 | enabled again if needed. This should be used with care as some non-Linux OSes |
| 13114 | are unable to enable it back. This is intended to be used in environments |
| 13115 | where stopping a proxy is not even imaginable but a misconfigured proxy must |
| 13116 | be fixed. That way it's possible to release the port and bind it into another |
| 13117 | process to restore operations. The frontend will appear with status "STOP" |
| 13118 | on the stats page. |
| 13119 | |
| 13120 | The frontend may be specified either by its name or by its numeric ID, |
| 13121 | prefixed with a sharp ('#'). |
| 13122 | |
| 13123 | This command is restricted and can only be issued on sockets configured for |
| 13124 | level "admin". |
| 13125 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13126 | disable server <backend>/<server> |
| 13127 | Mark the server DOWN for maintenance. In this mode, no more checks will be |
| 13128 | performed on the server until it leaves maintenance. |
| 13129 | If the server is tracked by other servers, those servers will be set to DOWN |
| 13130 | during the maintenance. |
| 13131 | |
| 13132 | In the statistics page, a server DOWN for maintenance will appear with a |
| 13133 | "MAINT" status, its tracking servers with the "MAINT(via)" one. |
| 13134 | |
| 13135 | Both the backend and the server may be specified either by their name or by |
Willy Tarreau | f5f3192 | 2011-08-02 11:32:07 +0200 | [diff] [blame] | 13136 | their numeric ID, prefixed with a sharp ('#'). |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13137 | |
| 13138 | This command is restricted and can only be issued on sockets configured for |
| 13139 | level "admin". |
| 13140 | |
Simon Horman | 671b6f0 | 2013-11-25 10:46:39 +0900 | [diff] [blame] | 13141 | enable agent <backend>/<server> |
| 13142 | Resume auxiliary agent check that was temporarily stopped. |
| 13143 | |
| 13144 | See "disable agent" for details of the effect of temporarily starting |
| 13145 | and stopping an auxiliary agent. |
| 13146 | |
| 13147 | This command is restricted and can only be issued on sockets configured for |
| 13148 | level "admin". |
| 13149 | |
Willy Tarreau | 532a450 | 2011-09-07 22:37:44 +0200 | [diff] [blame] | 13150 | enable frontend <frontend> |
| 13151 | Resume a frontend which was temporarily stopped. It is possible that some of |
| 13152 | the listening ports won't be able to bind anymore (eg: if another process |
| 13153 | took them since the 'disable frontend' operation). If this happens, an error |
| 13154 | is displayed. Some operating systems might not be able to resume a frontend |
| 13155 | which was disabled. |
| 13156 | |
| 13157 | The frontend may be specified either by its name or by its numeric ID, |
| 13158 | prefixed with a sharp ('#'). |
| 13159 | |
| 13160 | This command is restricted and can only be issued on sockets configured for |
| 13161 | level "admin". |
| 13162 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13163 | enable server <backend>/<server> |
| 13164 | If the server was previously marked as DOWN for maintenance, this marks the |
| 13165 | server UP and checks are re-enabled. |
| 13166 | |
| 13167 | Both the backend and the server may be specified either by their name or by |
Willy Tarreau | f5f3192 | 2011-08-02 11:32:07 +0200 | [diff] [blame] | 13168 | their numeric ID, prefixed with a sharp ('#'). |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13169 | |
| 13170 | This command is restricted and can only be issued on sockets configured for |
| 13171 | level "admin". |
| 13172 | |
Thierry FOURNIER | 5b16df7 | 2014-02-26 18:07:38 +0100 | [diff] [blame] | 13173 | get map <map> <value> |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13174 | get acl <acl> <value> |
| 13175 | Lookup the value <value> in the map <map> or in the ACL <acl>. <map> or <acl> |
| 13176 | are the #<id> or the <file> returned by "show map" or "show acl". This command |
| 13177 | returns all the matching patterns associated with this map. This is useful for |
| 13178 | debugging maps and ACLs. The output format is composed by one line par |
| 13179 | matching type. Each line is composed by space-delimited series of words. |
Thierry FOURNIER | 5b16df7 | 2014-02-26 18:07:38 +0100 | [diff] [blame] | 13180 | |
| 13181 | The first two words are: |
| 13182 | |
| 13183 | <match method>: The match method applied. It can be "found", "bool", |
| 13184 | "int", "ip", "bin", "len", "str", "beg", "sub", "dir", |
| 13185 | "dom", "end" or "reg". |
| 13186 | |
| 13187 | <match result>: The result. Can be "match" or "no-match". |
| 13188 | |
| 13189 | The following words are returned only if the pattern matches an entry. |
| 13190 | |
| 13191 | <index type>: "tree" or "list". The internal lookup algorithm. |
| 13192 | |
| 13193 | <case>: "case-insensitive" or "case-sensitive". The |
| 13194 | interpretation of the case. |
| 13195 | |
| 13196 | <entry matched>: match="<entry>". Return the matched pattern. It is |
| 13197 | useful with regular expressions. |
| 13198 | |
| 13199 | The two last word are used to show the returned value and its type. With the |
| 13200 | "acl" case, the pattern doesn't exist. |
| 13201 | |
| 13202 | return=nothing: No return because there are no "map". |
| 13203 | return="<value>": The value returned in the string format. |
| 13204 | return=cannot-display: The value cannot be converted as string. |
| 13205 | |
| 13206 | type="<type>": The type of the returned sample. |
| 13207 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13208 | get weight <backend>/<server> |
| 13209 | Report the current weight and the initial weight of server <server> in |
| 13210 | backend <backend> or an error if either doesn't exist. The initial weight is |
| 13211 | the one that appears in the configuration file. Both are normally equal |
| 13212 | unless the current weight has been changed. Both the backend and the server |
| 13213 | may be specified either by their name or by their numeric ID, prefixed with a |
Willy Tarreau | f5f3192 | 2011-08-02 11:32:07 +0200 | [diff] [blame] | 13214 | sharp ('#'). |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13215 | |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13216 | help |
| 13217 | Print the list of known keywords and their basic usage. The same help screen |
| 13218 | is also displayed for unknown commands. |
Willy Tarreau | 3dfe6cd | 2008-12-07 22:29:48 +0100 | [diff] [blame] | 13219 | |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13220 | prompt |
| 13221 | Toggle the prompt at the beginning of the line and enter or leave interactive |
| 13222 | mode. In interactive mode, the connection is not closed after a command |
| 13223 | completes. Instead, the prompt will appear again, indicating the user that |
| 13224 | the interpreter is waiting for a new command. The prompt consists in a right |
| 13225 | angle bracket followed by a space "> ". This mode is particularly convenient |
| 13226 | when one wants to periodically check information such as stats or errors. |
| 13227 | It is also a good idea to enter interactive mode before issuing a "help" |
| 13228 | command. |
| 13229 | |
| 13230 | quit |
| 13231 | Close the connection when in interactive mode. |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 13232 | |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13233 | set map <map> [<key>|#<ref>] <value> |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13234 | Modify the value corresponding to each key <key> in a map <map>. <map> is the |
| 13235 | #<id> or <file> returned by "show map". If the <ref> is used in place of |
| 13236 | <key>, only the entry pointed by <ref> is changed. The new value is <value>. |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 13237 | |
Willy Tarreau | 2a0f4d2 | 2011-08-02 11:49:05 +0200 | [diff] [blame] | 13238 | set maxconn frontend <frontend> <value> |
Willy Tarreau | 3c7a79d | 2012-09-26 21:07:15 +0200 | [diff] [blame] | 13239 | Dynamically change the specified frontend's maxconn setting. Any positive |
| 13240 | value is allowed including zero, but setting values larger than the global |
| 13241 | maxconn does not make much sense. If the limit is increased and connections |
| 13242 | were pending, they will immediately be accepted. If it is lowered to a value |
| 13243 | below the current number of connections, new connections acceptation will be |
Willy Tarreau | 2a0f4d2 | 2011-08-02 11:49:05 +0200 | [diff] [blame] | 13244 | delayed until the threshold is reached. The frontend might be specified by |
| 13245 | either its name or its numeric ID prefixed with a sharp ('#'). |
| 13246 | |
Willy Tarreau | 91886b6 | 2011-09-07 14:38:31 +0200 | [diff] [blame] | 13247 | set maxconn global <maxconn> |
| 13248 | Dynamically change the global maxconn setting within the range defined by the |
| 13249 | initial global maxconn setting. If it is increased and connections were |
| 13250 | pending, they will immediately be accepted. If it is lowered to a value below |
| 13251 | the current number of connections, new connections acceptation will be |
| 13252 | delayed until the threshold is reached. A value of zero restores the initial |
| 13253 | setting. |
| 13254 | |
Willy Tarreau | f5b2287 | 2011-09-07 16:13:44 +0200 | [diff] [blame] | 13255 | set rate-limit connections global <value> |
| 13256 | Change the process-wide connection rate limit, which is set by the global |
| 13257 | 'maxconnrate' setting. A value of zero disables the limitation. This limit |
| 13258 | applies to all frontends and the change has an immediate effect. The value |
| 13259 | is passed in number of connections per second. |
| 13260 | |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 13261 | set rate-limit http-compression global <value> |
| 13262 | Change the maximum input compression rate, which is set by the global |
| 13263 | 'maxcomprate' setting. A value of zero disables the limitation. The value is |
William Lallemand | 096f554 | 2012-11-19 17:26:05 +0100 | [diff] [blame] | 13264 | passed in number of kilobytes per second. The value is available in the "show |
| 13265 | info" on the line "CompressBpsRateLim" in bytes. |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 13266 | |
Willy Tarreau | 93e7c00 | 2013-10-07 18:51:07 +0200 | [diff] [blame] | 13267 | set rate-limit sessions global <value> |
| 13268 | Change the process-wide session rate limit, which is set by the global |
| 13269 | 'maxsessrate' setting. A value of zero disables the limitation. This limit |
| 13270 | applies to all frontends and the change has an immediate effect. The value |
| 13271 | is passed in number of sessions per second. |
| 13272 | |
Willy Tarreau | e43d532 | 2013-10-07 20:01:52 +0200 | [diff] [blame] | 13273 | set rate-limit ssl-sessions global <value> |
| 13274 | Change the process-wide SSL session rate limit, which is set by the global |
| 13275 | 'maxsslrate' setting. A value of zero disables the limitation. This limit |
| 13276 | applies to all frontends and the change has an immediate effect. The value |
| 13277 | is passed in number of sessions per second sent to the SSL stack. It applies |
| 13278 | before the handshake in order to protect the stack against handshake abuses. |
| 13279 | |
Willy Tarreau | 47060b6 | 2013-08-01 21:11:42 +0200 | [diff] [blame] | 13280 | set table <table> key <key> [data.<data_type> <value>]* |
Willy Tarreau | 654694e | 2012-06-07 01:03:16 +0200 | [diff] [blame] | 13281 | Create or update a stick-table entry in the table. If the key is not present, |
| 13282 | an entry is inserted. See stick-table in section 4.2 to find all possible |
| 13283 | values for <data_type>. The most likely use consists in dynamically entering |
| 13284 | entries for source IP addresses, with a flag in gpc0 to dynamically block an |
Willy Tarreau | 47060b6 | 2013-08-01 21:11:42 +0200 | [diff] [blame] | 13285 | IP address or affect its quality of service. It is possible to pass multiple |
| 13286 | data_types in a single call. |
Willy Tarreau | 654694e | 2012-06-07 01:03:16 +0200 | [diff] [blame] | 13287 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13288 | set timeout cli <delay> |
| 13289 | Change the CLI interface timeout for current connection. This can be useful |
| 13290 | during long debugging sessions where the user needs to constantly inspect |
| 13291 | some indicators without being disconnected. The delay is passed in seconds. |
| 13292 | |
| 13293 | set weight <backend>/<server> <weight>[%] |
| 13294 | Change a server's weight to the value passed in argument. If the value ends |
| 13295 | with the '%' sign, then the new weight will be relative to the initially |
Simon Horman | 58b5d29 | 2013-02-12 10:45:52 +0900 | [diff] [blame] | 13296 | configured weight. Absolute weights are permitted between 0 and 256. |
| 13297 | Relative weights must be positive with the resulting absolute weight is |
| 13298 | capped at 256. Servers which are part of a farm running a static |
| 13299 | load-balancing algorithm have stricter limitations because the weight |
| 13300 | cannot change once set. Thus for these servers, the only accepted values |
| 13301 | are 0 and 100% (or 0 and the initial weight). Changes take effect |
| 13302 | immediately, though certain LB algorithms require a certain amount of |
| 13303 | requests to consider changes. A typical usage of this command is to |
| 13304 | disable a server during an update by setting its weight to zero, then to |
| 13305 | enable it again after the update by setting it back to 100%. This command |
| 13306 | is restricted and can only be issued on sockets configured for level |
| 13307 | "admin". Both the backend and the server may be specified either by their |
| 13308 | name or by their numeric ID, prefixed with a sharp ('#'). |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 13309 | |
Willy Tarreau | e0c8a1a | 2009-03-04 16:33:10 +0100 | [diff] [blame] | 13310 | show errors [<iid>] |
| 13311 | Dump last known request and response errors collected by frontends and |
| 13312 | backends. If <iid> is specified, the limit the dump to errors concerning |
Willy Tarreau | 6162db2 | 2009-10-10 17:13:00 +0200 | [diff] [blame] | 13313 | either frontend or backend whose ID is <iid>. This command is restricted |
| 13314 | and can only be issued on sockets configured for levels "operator" or |
| 13315 | "admin". |
Willy Tarreau | e0c8a1a | 2009-03-04 16:33:10 +0100 | [diff] [blame] | 13316 | |
| 13317 | The errors which may be collected are the last request and response errors |
| 13318 | caused by protocol violations, often due to invalid characters in header |
| 13319 | names. The report precisely indicates what exact character violated the |
| 13320 | protocol. Other important information such as the exact date the error was |
| 13321 | detected, frontend and backend names, the server name (when known), the |
| 13322 | internal session ID and the source address which has initiated the session |
| 13323 | are reported too. |
| 13324 | |
| 13325 | All characters are returned, and non-printable characters are encoded. The |
| 13326 | most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one |
| 13327 | letter following a backslash. The backslash itself is encoded as '\\' to |
| 13328 | avoid confusion. Other non-printable characters are encoded '\xNN' where |
| 13329 | NN is the two-digits hexadecimal representation of the character's ASCII |
| 13330 | code. |
| 13331 | |
| 13332 | Lines are prefixed with the position of their first character, starting at 0 |
| 13333 | for the beginning of the buffer. At most one input line is printed per line, |
| 13334 | and large lines will be broken into multiple consecutive output lines so that |
| 13335 | the output never goes beyond 79 characters wide. It is easy to detect if a |
| 13336 | line was broken, because it will not end with '\n' and the next line's offset |
| 13337 | will be followed by a '+' sign, indicating it is a continuation of previous |
| 13338 | line. |
| 13339 | |
| 13340 | Example : |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13341 | $ echo "show errors" | socat stdio /tmp/sock1 |
| 13342 | >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response |
Willy Tarreau | e0c8a1a | 2009-03-04 16:33:10 +0100 | [diff] [blame] | 13343 | src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1) |
| 13344 | response length 213 bytes, error at position 23: |
| 13345 | |
| 13346 | 00000 HTTP/1.0 200 OK\r\n |
| 13347 | 00017 header/bizarre:blah\r\n |
| 13348 | 00038 Location: blah\r\n |
| 13349 | 00054 Long-line: this is a very long line which should b |
| 13350 | 00104+ e broken into multiple lines on the output buffer, |
| 13351 | 00154+ otherwise it would be too large to print in a ter |
| 13352 | 00204+ minal\r\n |
| 13353 | 00211 \r\n |
| 13354 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 13355 | In the example above, we see that the backend "http-in" which has internal |
Willy Tarreau | e0c8a1a | 2009-03-04 16:33:10 +0100 | [diff] [blame] | 13356 | ID 2 has blocked an invalid response from its server s2 which has internal |
| 13357 | ID 1. The request was on session 54 initiated by source 127.0.0.1 and |
| 13358 | received by frontend fe-eth0 whose ID is 1. The total response length was |
| 13359 | 213 bytes when the error was detected, and the error was at byte 23. This |
| 13360 | is the slash ('/') in header name "header/bizarre", which is not a valid |
| 13361 | HTTP character for a header name. |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 13362 | |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13363 | show info |
| 13364 | Dump info about haproxy status on current process. |
| 13365 | |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 13366 | show map [<map>] |
| 13367 | Dump info about map converters. Without argument, the list of all available |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13368 | maps is returned. If a <map> is specified, its contents are dumped. <map> is |
| 13369 | the #<id> or <file>. The first column is a unique identifier. It can be used |
| 13370 | as reference for the operation "del map" and "set map". The second column is |
| 13371 | the pattern and the third column is the sample if available. The data returned |
| 13372 | are not directly a list of available maps, but are the list of all patterns |
| 13373 | composing any map. Many of these patterns can be shared with ACL. |
Thierry FOURNIER | d32079e | 2014-01-29 20:02:04 +0100 | [diff] [blame] | 13374 | |
| 13375 | show acl [<acl>] |
| 13376 | Dump info about acl converters. Without argument, the list of all available |
Thierry FOURNIER | 65ce613 | 2014-03-20 11:42:45 +0100 | [diff] [blame] | 13377 | acls is returned. If a <acl> is specified, its contents are dumped. <acl> if |
| 13378 | the #<id> or <file>. The dump format is the same than the map even for the |
| 13379 | sample value. The data returned are not a list of available ACL, but are the |
| 13380 | list of all patterns composing any ACL. Many of these patterns can be shared |
| 13381 | with maps. |
Thierry FOURNIER | c0e0d7b | 2013-12-11 16:55:52 +0100 | [diff] [blame] | 13382 | |
Willy Tarreau | 12833bb | 2014-01-28 16:49:56 +0100 | [diff] [blame] | 13383 | show pools |
| 13384 | Dump the status of internal memory pools. This is useful to track memory |
| 13385 | usage when suspecting a memory leak for example. It does exactly the same |
| 13386 | as the SIGQUIT when running in foreground except that it does not flush |
| 13387 | the pools. |
| 13388 | |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13389 | show sess |
| 13390 | Dump all known sessions. Avoid doing this on slow connections as this can |
Willy Tarreau | 6162db2 | 2009-10-10 17:13:00 +0200 | [diff] [blame] | 13391 | be huge. This command is restricted and can only be issued on sockets |
| 13392 | configured for levels "operator" or "admin". |
| 13393 | |
Willy Tarreau | 66dc20a | 2010-03-05 17:53:32 +0100 | [diff] [blame] | 13394 | show sess <id> |
| 13395 | Display a lot of internal information about the specified session identifier. |
| 13396 | This identifier is the first field at the beginning of the lines in the dumps |
| 13397 | of "show sess" (it corresponds to the session pointer). Those information are |
| 13398 | useless to most users but may be used by haproxy developers to troubleshoot a |
| 13399 | complex bug. The output format is intentionally not documented so that it can |
Willy Tarreau | 7615366 | 2012-11-26 01:16:39 +0100 | [diff] [blame] | 13400 | freely evolve depending on demands. The special id "all" dumps the states of |
| 13401 | all sessions, which can be avoided as much as possible as it is highly CPU |
| 13402 | intensive and can take a lot of time. |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13403 | |
| 13404 | show stat [<iid> <type> <sid>] |
| 13405 | Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is |
| 13406 | possible to dump only selected items : |
| 13407 | - <iid> is a proxy ID, -1 to dump everything |
| 13408 | - <type> selects the type of dumpable objects : 1 for frontends, 2 for |
| 13409 | backends, 4 for servers, -1 for everything. These values can be ORed, |
| 13410 | for example: |
| 13411 | 1 + 2 = 3 -> frontend + backend. |
| 13412 | 1 + 2 + 4 = 7 -> frontend + backend + server. |
| 13413 | - <sid> is a server ID, -1 to dump everything from the selected proxy. |
| 13414 | |
| 13415 | Example : |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13416 | $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1 |
| 13417 | >>> Name: HAProxy |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13418 | Version: 1.4-dev2-49 |
| 13419 | Release_date: 2009/09/23 |
| 13420 | Nbproc: 1 |
| 13421 | Process_num: 1 |
| 13422 | (...) |
| 13423 | |
| 13424 | # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...) |
| 13425 | stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...) |
| 13426 | stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...) |
| 13427 | (...) |
| 13428 | www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...) |
| 13429 | |
| 13430 | $ |
| 13431 | |
| 13432 | Here, two commands have been issued at once. That way it's easy to find |
| 13433 | which process the stats apply to in multi-process mode. Notice the empty |
| 13434 | line after the information output which marks the end of the first block. |
| 13435 | A similar empty line appears at the end of the second block (stats) so that |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 13436 | the reader knows the output has not been truncated. |
Willy Tarreau | 9a42c0d | 2009-09-22 19:31:03 +0200 | [diff] [blame] | 13437 | |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13438 | show table |
| 13439 | Dump general information on all known stick-tables. Their name is returned |
| 13440 | (the name of the proxy which holds them), their type (currently zero, always |
| 13441 | IP), their size in maximum possible number of entries, and the number of |
| 13442 | entries currently in use. |
| 13443 | |
| 13444 | Example : |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13445 | $ echo "show table" | socat stdio /tmp/sock1 |
Simon Horman | 64b28d0 | 2011-08-13 08:03:50 +0900 | [diff] [blame] | 13446 | >>> # table: front_pub, type: ip, size:204800, used:171454 |
| 13447 | >>> # table: back_rdp, type: ip, size:204800, used:0 |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13448 | |
Simon Horman | 17bce34 | 2011-06-15 15:18:47 +0900 | [diff] [blame] | 13449 | show table <name> [ data.<type> <operator> <value> ] | [ key <key> ] |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13450 | Dump contents of stick-table <name>. In this mode, a first line of generic |
| 13451 | information about the table is reported as with "show table", then all |
| 13452 | entries are dumped. Since this can be quite heavy, it is possible to specify |
Simon Horman | 17bce34 | 2011-06-15 15:18:47 +0900 | [diff] [blame] | 13453 | a filter in order to specify what entries to display. |
| 13454 | |
| 13455 | When the "data." form is used the filter applies to the stored data (see |
| 13456 | "stick-table" in section 4.2). A stored data type must be specified |
| 13457 | in <type>, and this data type must be stored in the table otherwise an |
| 13458 | error is reported. The data is compared according to <operator> with the |
| 13459 | 64-bit integer <value>. Operators are the same as with the ACLs : |
| 13460 | |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13461 | - eq : match entries whose data is equal to this value |
| 13462 | - ne : match entries whose data is not equal to this value |
| 13463 | - le : match entries whose data is less than or equal to this value |
| 13464 | - ge : match entries whose data is greater than or equal to this value |
| 13465 | - lt : match entries whose data is less than this value |
| 13466 | - gt : match entries whose data is greater than this value |
| 13467 | |
Simon Horman | c88b887 | 2011-06-15 15:18:49 +0900 | [diff] [blame] | 13468 | |
| 13469 | When the key form is used the entry <key> is shown. The key must be of the |
Simon Horman | 619e3cc | 2011-06-15 15:18:52 +0900 | [diff] [blame] | 13470 | same type as the table, which currently is limited to IPv4, IPv6, integer, |
| 13471 | and string. |
Simon Horman | 17bce34 | 2011-06-15 15:18:47 +0900 | [diff] [blame] | 13472 | |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13473 | Example : |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13474 | $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
Simon Horman | 64b28d0 | 2011-08-13 08:03:50 +0900 | [diff] [blame] | 13475 | >>> # table: http_proxy, type: ip, size:204800, used:2 |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13476 | >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \ |
| 13477 | bytes_out_rate(60000)=187 |
| 13478 | >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| 13479 | bytes_out_rate(60000)=191 |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13480 | |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13481 | $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1 |
Simon Horman | 64b28d0 | 2011-08-13 08:03:50 +0900 | [diff] [blame] | 13482 | >>> # table: http_proxy, type: ip, size:204800, used:2 |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13483 | >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| 13484 | bytes_out_rate(60000)=191 |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13485 | |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13486 | $ echo "show table http_proxy data.conn_rate gt 5" | \ |
| 13487 | socat stdio /tmp/sock1 |
Simon Horman | 64b28d0 | 2011-08-13 08:03:50 +0900 | [diff] [blame] | 13488 | >>> # table: http_proxy, type: ip, size:204800, used:2 |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13489 | >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| 13490 | bytes_out_rate(60000)=191 |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13491 | |
Simon Horman | 17bce34 | 2011-06-15 15:18:47 +0900 | [diff] [blame] | 13492 | $ echo "show table http_proxy key 127.0.0.2" | \ |
| 13493 | socat stdio /tmp/sock1 |
Simon Horman | 64b28d0 | 2011-08-13 08:03:50 +0900 | [diff] [blame] | 13494 | >>> # table: http_proxy, type: ip, size:204800, used:2 |
Simon Horman | 17bce34 | 2011-06-15 15:18:47 +0900 | [diff] [blame] | 13495 | >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| 13496 | bytes_out_rate(60000)=191 |
| 13497 | |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13498 | When the data criterion applies to a dynamic value dependent on time such as |
| 13499 | a bytes rate, the value is dynamically computed during the evaluation of the |
| 13500 | entry in order to decide whether it has to be dumped or not. This means that |
| 13501 | such a filter could match for some time then not match anymore because as |
| 13502 | time goes, the average event rate drops. |
| 13503 | |
| 13504 | It is possible to use this to extract lists of IP addresses abusing the |
| 13505 | service, in order to monitor them or even blacklist them in a firewall. |
| 13506 | Example : |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 13507 | $ echo "show table http_proxy data.gpc0 gt 0" \ |
| 13508 | | socat stdio /tmp/sock1 \ |
Willy Tarreau | 88bc4ec | 2010-08-01 07:58:48 +0200 | [diff] [blame] | 13509 | | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt |
| 13510 | ( or | awk '/key/{ print a[split($2,a,"=")]; }' ) |
Krzysztof Piotr Oledzki | 719e726 | 2009-10-04 15:02:46 +0200 | [diff] [blame] | 13511 | |
Willy Tarreau | 532a450 | 2011-09-07 22:37:44 +0200 | [diff] [blame] | 13512 | shutdown frontend <frontend> |
| 13513 | Completely delete the specified frontend. All the ports it was bound to will |
| 13514 | be released. It will not be possible to enable the frontend anymore after |
| 13515 | this operation. This is intended to be used in environments where stopping a |
| 13516 | proxy is not even imaginable but a misconfigured proxy must be fixed. That |
| 13517 | way it's possible to release the port and bind it into another process to |
| 13518 | restore operations. The frontend will not appear at all on the stats page |
| 13519 | once it is terminated. |
| 13520 | |
| 13521 | The frontend may be specified either by its name or by its numeric ID, |
| 13522 | prefixed with a sharp ('#'). |
| 13523 | |
| 13524 | This command is restricted and can only be issued on sockets configured for |
| 13525 | level "admin". |
| 13526 | |
Willy Tarreau | a295edc | 2011-09-07 23:21:03 +0200 | [diff] [blame] | 13527 | shutdown session <id> |
| 13528 | Immediately terminate the session matching the specified session identifier. |
| 13529 | This identifier is the first field at the beginning of the lines in the dumps |
| 13530 | of "show sess" (it corresponds to the session pointer). This can be used to |
| 13531 | terminate a long-running session without waiting for a timeout or when an |
| 13532 | endless transfer is ongoing. Such terminated sessions are reported with a 'K' |
| 13533 | flag in the logs. |
| 13534 | |
Willy Tarreau | 52b2d22 | 2011-09-07 23:48:48 +0200 | [diff] [blame] | 13535 | shutdown sessions <backend>/<server> |
| 13536 | Immediately terminate all the sessions attached to the specified server. This |
| 13537 | can be used to terminate long-running sessions after a server is put into |
| 13538 | maintenance mode, for instance. Such terminated sessions are reported with a |
| 13539 | 'K' flag in the logs. |
| 13540 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 13541 | /* |
| 13542 | * Local variables: |
| 13543 | * fill-column: 79 |
| 13544 | * End: |
| 13545 | */ |