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 | 1db5579 | 2020-11-05 17:20:35 +0100 | [diff] [blame] | 5 | version 2.4 |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 6 | willy tarreau |
Willy Tarreau | 080347f | 2021-05-01 08:25:15 +0200 | [diff] [blame] | 7 | 2021/05/01 |
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 |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11 | specified above. It does not provide any hints, examples, 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. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13 | The summary below is meant to help you find sections by name and navigate |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 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 |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 22 | sometimes useful to prefix all output lines (logs, console outputs) with 3 |
| 23 | closing angle brackets ('>>>') in order to emphasize the difference between |
| 24 | inputs and outputs when they may be ambiguous. If you add sections, |
Willy Tarreau | 62a36c4 | 2010-08-17 15:53:10 +0200 | [diff] [blame] | 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 |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 34 | 1.2.1. The request line |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 35 | 1.2.2. The request headers |
| 36 | 1.3. HTTP response |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 37 | 1.3.1. The response line |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 38 | 1.3.2. The response headers |
| 39 | |
| 40 | 2. Configuring HAProxy |
| 41 | 2.1. Configuration file format |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 42 | 2.2. Quoting and escaping |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 43 | 2.3. Environment variables |
Willy Tarreau | 4b10302 | 2021-02-12 17:59:10 +0100 | [diff] [blame] | 44 | 2.4. Conditional blocks |
| 45 | 2.5. Time format |
| 46 | 2.6. Examples |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 47 | |
| 48 | 3. Global parameters |
| 49 | 3.1. Process management and security |
| 50 | 3.2. Performance tuning |
| 51 | 3.3. Debugging |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 52 | 3.4. Userlists |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 53 | 3.5. Peers |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 54 | 3.6. Mailers |
William Lallemand | c951552 | 2019-06-12 16:32:11 +0200 | [diff] [blame] | 55 | 3.7. Programs |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 56 | 3.8. HTTP-errors |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 57 | 3.9. Rings |
William Lallemand | 0217b7b | 2020-11-18 10:41:24 +0100 | [diff] [blame] | 58 | 3.10. Log forwarding |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 59 | |
| 60 | 4. Proxies |
| 61 | 4.1. Proxy keywords matrix |
| 62 | 4.2. Alphabetically sorted keywords reference |
| 63 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 64 | 5. Bind and server options |
Willy Tarreau | 086fbf5 | 2012-09-24 20:34:51 +0200 | [diff] [blame] | 65 | 5.1. Bind options |
| 66 | 5.2. Server and default-server options |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 67 | 5.3. Server DNS resolution |
| 68 | 5.3.1. Global overview |
| 69 | 5.3.2. The resolvers section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 70 | |
Julien Pivotto | 6ccee41 | 2019-11-27 15:49:54 +0100 | [diff] [blame] | 71 | 6. Cache |
| 72 | 6.1. Limitation |
| 73 | 6.2. Setup |
| 74 | 6.2.1. Cache section |
| 75 | 6.2.2. Proxy section |
| 76 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 77 | 7. Using ACLs and fetching samples |
| 78 | 7.1. ACL basics |
| 79 | 7.1.1. Matching booleans |
| 80 | 7.1.2. Matching integers |
| 81 | 7.1.3. Matching strings |
| 82 | 7.1.4. Matching regular expressions (regexes) |
| 83 | 7.1.5. Matching arbitrary data blocks |
| 84 | 7.1.6. Matching IPv4 and IPv6 addresses |
| 85 | 7.2. Using ACLs to form conditions |
| 86 | 7.3. Fetching samples |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 87 | 7.3.1. Converters |
| 88 | 7.3.2. Fetching samples from internal states |
| 89 | 7.3.3. Fetching samples at Layer 4 |
| 90 | 7.3.4. Fetching samples at Layer 5 |
| 91 | 7.3.5. Fetching samples from buffer contents (Layer 6) |
| 92 | 7.3.6. Fetching HTTP samples (Layer 7) |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 93 | 7.3.7. Fetching samples for developers |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 94 | 7.4. Pre-defined ACLs |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 95 | |
| 96 | 8. Logging |
| 97 | 8.1. Log levels |
| 98 | 8.2. Log formats |
| 99 | 8.2.1. Default log format |
| 100 | 8.2.2. TCP log format |
| 101 | 8.2.3. HTTP log format |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 102 | 8.2.4. Custom log format |
Willy Tarreau | 5f51e1a | 2012-12-03 18:40:10 +0100 | [diff] [blame] | 103 | 8.2.5. Error log format |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 104 | 8.3. Advanced logging options |
| 105 | 8.3.1. Disabling logging of external tests |
| 106 | 8.3.2. Logging before waiting for the session to terminate |
| 107 | 8.3.3. Raising log level upon errors |
| 108 | 8.3.4. Disabling logging of successful connections |
| 109 | 8.4. Timing events |
| 110 | 8.5. Session state at disconnection |
| 111 | 8.6. Non-printable characters |
| 112 | 8.7. Capturing HTTP cookies |
| 113 | 8.8. Capturing HTTP headers |
| 114 | 8.9. Examples of logs |
| 115 | |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 116 | 9. Supported filters |
| 117 | 9.1. Trace |
| 118 | 9.2. HTTP compression |
Christopher Faulet | f7e4e7e | 2016-10-27 22:29:49 +0200 | [diff] [blame] | 119 | 9.3. Stream Processing Offload Engine (SPOE) |
Christopher Faulet | 99a17a2 | 2018-12-11 09:18:27 +0100 | [diff] [blame] | 120 | 9.4. Cache |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 121 | 9.5. fcgi-app |
Miroslav Zagorac | dc32cd9 | 2020-12-13 18:32:57 +0100 | [diff] [blame] | 122 | 9.6. OpenTracing |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 123 | |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 124 | 10. FastCGI applications |
| 125 | 10.1. Setup |
| 126 | 10.1.1. Fcgi-app section |
| 127 | 10.1.2. Proxy section |
| 128 | 10.1.3. Example |
| 129 | 10.2. Default parameters |
| 130 | 10.3. Limitations |
| 131 | |
Emeric Brun | ce325c4 | 2021-04-02 17:05:09 +0200 | [diff] [blame] | 132 | 11. Address formats |
| 133 | 11.1. Address family prefixes |
| 134 | 11.2. Socket type prefixes |
| 135 | 11.3. Protocol prefixes |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 136 | |
| 137 | 1. Quick reminder about HTTP |
| 138 | ---------------------------- |
| 139 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 140 | When HAProxy is running in HTTP mode, both the request and the response are |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 141 | fully analyzed and indexed, thus it becomes possible to build matching criteria |
| 142 | on almost anything found in the contents. |
| 143 | |
| 144 | However, it is important to understand how HTTP requests and responses are |
| 145 | formed, and how HAProxy decomposes them. It will then become easier to write |
| 146 | correct rules and to debug existing configurations. |
| 147 | |
| 148 | |
| 149 | 1.1. The HTTP transaction model |
| 150 | ------------------------------- |
| 151 | |
| 152 | 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] | 153 | to one and only one response. Traditionally, a TCP connection is established |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 154 | from the client to the server, a request is sent by the client through the |
| 155 | connection, the server responds, and the connection is closed. A new request |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 156 | will involve a new connection : |
| 157 | |
| 158 | [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ... |
| 159 | |
| 160 | In this mode, called the "HTTP close" mode, there are as many connection |
| 161 | establishments as there are HTTP transactions. Since the connection is closed |
| 162 | by the server after the response, the client does not need to know the content |
| 163 | length. |
| 164 | |
| 165 | Due to the transactional nature of the protocol, it was possible to improve it |
| 166 | to avoid closing a connection between two subsequent transactions. In this mode |
| 167 | however, it is mandatory that the server indicates the content length for each |
| 168 | response so that the client does not wait indefinitely. For this, a special |
| 169 | header is used: "Content-length". This mode is called the "keep-alive" mode : |
| 170 | |
| 171 | [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ... |
| 172 | |
| 173 | Its advantages are a reduced latency between transactions, and less processing |
| 174 | power required on the server side. It is generally better than the close mode, |
| 175 | but not always because the clients often limit their concurrent connections to |
Patrick Mezard | 9ec2ec4 | 2010-06-12 17:02:45 +0200 | [diff] [blame] | 176 | a smaller value. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 177 | |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 178 | Another improvement in the communications is the pipelining mode. It still uses |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 179 | keep-alive, but the client does not wait for the first response to send the |
| 180 | second request. This is useful for fetching large number of images composing a |
| 181 | page : |
| 182 | |
| 183 | [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ... |
| 184 | |
| 185 | This can obviously have a tremendous benefit on performance because the network |
| 186 | latency is eliminated between subsequent requests. Many HTTP agents do not |
| 187 | correctly support pipelining since there is no way to associate a response with |
| 188 | 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] | 189 | 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] | 190 | |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 191 | The next improvement is the multiplexed mode, as implemented in HTTP/2. This |
| 192 | time, each transaction is assigned a single stream identifier, and all streams |
| 193 | are multiplexed over an existing connection. Many requests can be sent in |
| 194 | parallel by the client, and responses can arrive in any order since they also |
| 195 | carry the stream identifier. |
| 196 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 197 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 198 | connections: for each connection it processes each request and response, and |
| 199 | leaves the connection idle on both sides between the end of a response and the |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 200 | start of a new request. When it receives HTTP/2 connections from a client, it |
| 201 | processes all the requests in parallel and leaves the connection idling, |
| 202 | waiting for new requests, just as if it was a keep-alive HTTP connection. |
Patrick Mezard | 9ec2ec4 | 2010-06-12 17:02:45 +0200 | [diff] [blame] | 203 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 204 | HAProxy supports 4 connection modes : |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 205 | - keep alive : all requests and responses are processed (default) |
| 206 | - tunnel : only the first request and response are processed, |
Christopher Faulet | 6c9bbb2 | 2019-03-26 21:37:23 +0100 | [diff] [blame] | 207 | everything else is forwarded with no analysis (deprecated). |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 208 | - server close : the server-facing connection is closed after the response. |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 209 | - close : the connection is actively closed after end of response. |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 210 | |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 211 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 212 | |
| 213 | 1.2. HTTP request |
| 214 | ----------------- |
| 215 | |
| 216 | First, let's consider this HTTP request : |
| 217 | |
| 218 | Line Contents |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 219 | number |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 220 | 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1 |
| 221 | 2 Host: www.mydomain.com |
| 222 | 3 User-agent: my small browser |
| 223 | 4 Accept: image/jpeg, image/gif |
| 224 | 5 Accept: image/png |
| 225 | |
| 226 | |
| 227 | 1.2.1. The Request line |
| 228 | ----------------------- |
| 229 | |
| 230 | Line 1 is the "request line". It is always composed of 3 fields : |
| 231 | |
| 232 | - a METHOD : GET |
| 233 | - a URI : /serv/login.php?lang=en&profile=2 |
| 234 | - a version tag : HTTP/1.1 |
| 235 | |
| 236 | All of them are delimited by what the standard calls LWS (linear white spaces), |
| 237 | which are commonly spaces, but can also be tabs or line feeds/carriage returns |
| 238 | followed by spaces/tabs. The method itself cannot contain any colon (':') and |
| 239 | is limited to alphabetic letters. All those various combinations make it |
| 240 | desirable that HAProxy performs the splitting itself rather than leaving it to |
| 241 | the user to write a complex or inaccurate regular expression. |
| 242 | |
| 243 | The URI itself can have several forms : |
| 244 | |
| 245 | - A "relative URI" : |
| 246 | |
| 247 | /serv/login.php?lang=en&profile=2 |
| 248 | |
| 249 | It is a complete URL without the host part. This is generally what is |
| 250 | received by servers, reverse proxies and transparent proxies. |
| 251 | |
| 252 | - An "absolute URI", also called a "URL" : |
| 253 | |
| 254 | http://192.168.0.12:8080/serv/login.php?lang=en&profile=2 |
| 255 | |
| 256 | It is composed of a "scheme" (the protocol name followed by '://'), a host |
| 257 | name or address, optionally a colon (':') followed by a port number, then |
| 258 | a relative URI beginning at the first slash ('/') after the address part. |
| 259 | This is generally what proxies receive, but a server supporting HTTP/1.1 |
| 260 | must accept this form too. |
| 261 | |
| 262 | - a star ('*') : this form is only accepted in association with the OPTIONS |
| 263 | method and is not relayable. It is used to inquiry a next hop's |
| 264 | capabilities. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 265 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 266 | - an address:port combination : 192.168.0.12:80 |
| 267 | This is used with the CONNECT method, which is used to establish TCP |
| 268 | tunnels through HTTP proxies, generally for HTTPS, but sometimes for |
| 269 | other protocols too. |
| 270 | |
| 271 | In a relative URI, two sub-parts are identified. The part before the question |
| 272 | mark is called the "path". It is typically the relative path to static objects |
| 273 | on the server. The part after the question mark is called the "query string". |
| 274 | It is mostly used with GET requests sent to dynamic scripts and is very |
| 275 | specific to the language, framework or application in use. |
| 276 | |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 277 | HTTP/2 doesn't convey a version information with the request, so the version is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 278 | assumed to be the same as the one of the underlying protocol (i.e. "HTTP/2"). |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 279 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 280 | |
| 281 | 1.2.2. The request headers |
| 282 | -------------------------- |
| 283 | |
| 284 | The headers start at the second line. They are composed of a name at the |
| 285 | beginning of the line, immediately followed by a colon (':'). Traditionally, |
| 286 | an LWS is added after the colon but that's not required. Then come the values. |
| 287 | Multiple identical headers may be folded into one single line, delimiting the |
| 288 | values with commas, provided that their order is respected. This is commonly |
| 289 | encountered in the "Cookie:" field. A header may span over multiple lines if |
| 290 | the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5 |
| 291 | define a total of 3 values for the "Accept:" header. |
| 292 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 293 | Contrary to a common misconception, header names are not case-sensitive, and |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 294 | their values are not either if they refer to other header names (such as the |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 295 | "Connection:" header). In HTTP/2, header names are always sent in lower case, |
Willy Tarreau | 253c251 | 2020-07-07 15:55:23 +0200 | [diff] [blame] | 296 | as can be seen when running in debug mode. Internally, all header names are |
| 297 | normalized to lower case so that HTTP/1.x and HTTP/2 use the exact same |
| 298 | representation, and they are sent as-is on the other side. This explains why an |
| 299 | HTTP/1.x request typed with camel case is delivered in lower case. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 300 | |
| 301 | The end of the headers is indicated by the first empty line. People often say |
| 302 | that it's a double line feed, which is not exact, even if a double line feed |
| 303 | is one valid form of empty line. |
| 304 | |
| 305 | Fortunately, HAProxy takes care of all these complex combinations when indexing |
| 306 | headers, checking values and counting them, so there is no reason to worry |
| 307 | about the way they could be written, but it is important not to accuse an |
| 308 | application of being buggy if it does unusual, valid things. |
| 309 | |
| 310 | Important note: |
Lukas Tribus | 2395368 | 2017-04-28 13:24:30 +0000 | [diff] [blame] | 311 | As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 312 | in the middle of headers by LWS in order to join multi-line headers. This |
| 313 | is necessary for proper analysis and helps less capable HTTP parsers to work |
| 314 | correctly and not to be fooled by such complex constructs. |
| 315 | |
| 316 | |
| 317 | 1.3. HTTP response |
| 318 | ------------------ |
| 319 | |
| 320 | An HTTP response looks very much like an HTTP request. Both are called HTTP |
| 321 | messages. Let's consider this HTTP response : |
| 322 | |
| 323 | Line Contents |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 324 | number |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 325 | 1 HTTP/1.1 200 OK |
| 326 | 2 Content-length: 350 |
| 327 | 3 Content-Type: text/html |
| 328 | |
Willy Tarreau | 816b979 | 2009-09-15 21:25:21 +0200 | [diff] [blame] | 329 | As a special case, HTTP supports so called "Informational responses" as status |
| 330 | codes 1xx. These messages are special in that they don't convey any part of the |
| 331 | 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] | 332 | continue to post its request for instance. In the case of a status 100 response |
| 333 | the requested information will be carried by the next non-100 response message |
| 334 | following the informational one. This implies that multiple responses may be |
| 335 | sent to a single request, and that this only works when keep-alive is enabled |
| 336 | (1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to |
| 337 | correctly forward and skip them, and only process the next non-100 response. As |
| 338 | such, these messages are neither logged nor transformed, unless explicitly |
| 339 | state otherwise. Status 101 messages indicate that the protocol is changing |
| 340 | over the same connection and that haproxy must switch to tunnel mode, just as |
| 341 | if a CONNECT had occurred. Then the Upgrade header would contain additional |
| 342 | information about the type of protocol the connection is switching to. |
Willy Tarreau | 816b979 | 2009-09-15 21:25:21 +0200 | [diff] [blame] | 343 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 344 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 345 | 1.3.1. The response line |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 346 | ------------------------ |
| 347 | |
| 348 | Line 1 is the "response line". It is always composed of 3 fields : |
| 349 | |
| 350 | - a version tag : HTTP/1.1 |
| 351 | - a status code : 200 |
| 352 | - a reason : OK |
| 353 | |
| 354 | The status code is always 3-digit. The first digit indicates a general status : |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 355 | - 1xx = informational message to be skipped (e.g. 100, 101) |
| 356 | - 2xx = OK, content is following (e.g. 200, 206) |
| 357 | - 3xx = OK, no content following (e.g. 302, 304) |
| 358 | - 4xx = error caused by the client (e.g. 401, 403, 404) |
| 359 | - 5xx = error caused by the server (e.g. 500, 502, 503) |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 360 | |
Lukas Tribus | 2395368 | 2017-04-28 13:24:30 +0000 | [diff] [blame] | 361 | Please refer to RFC7231 for the detailed meaning of all such codes. The |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 362 | "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] | 363 | found there, but it's a common practice to respect the well-established |
| 364 | messages. It can be composed of one or multiple words, such as "OK", "Found", |
| 365 | or "Authentication Required". |
| 366 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 367 | HAProxy may emit the following status codes by itself : |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 368 | |
| 369 | Code When / reason |
| 370 | 200 access to stats page, and when replying to monitoring requests |
| 371 | 301 when performing a redirection, depending on the configured code |
| 372 | 302 when performing a redirection, depending on the configured code |
| 373 | 303 when performing a redirection, depending on the configured code |
Willy Tarreau | b67fdc4 | 2013-03-29 19:28:11 +0100 | [diff] [blame] | 374 | 307 when performing a redirection, depending on the configured code |
| 375 | 308 when performing a redirection, depending on the configured code |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 376 | 400 for an invalid or too large request |
| 377 | 401 when an authentication is required to perform the action (when |
| 378 | accessing the stats page) |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 379 | 403 when a request is forbidden by a "http-request deny" rule |
Florian Tham | 9205fea | 2020-01-08 13:35:30 +0100 | [diff] [blame] | 380 | 404 when the requested resource could not be found |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 381 | 408 when the request timeout strikes before the request is complete |
Florian Tham | 272e29b | 2020-01-08 10:19:05 +0100 | [diff] [blame] | 382 | 410 when the requested resource is no longer available and will not |
| 383 | be available again |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 384 | 500 when haproxy encounters an unrecoverable internal error, such as a |
| 385 | memory allocation failure, which should never happen |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 386 | 501 when haproxy is unable to satisfy a client request because of an |
| 387 | unsupported feature |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 388 | 502 when the server returns an empty, invalid or incomplete response, or |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 389 | when an "http-response deny" rule blocks the response. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 390 | 503 when no server was available to handle the request, or in response to |
| 391 | monitoring requests which match the "monitor fail" condition |
| 392 | 504 when the response timeout strikes before the server responds |
| 393 | |
| 394 | The error 4xx and 5xx codes above may be customized (see "errorloc" in section |
| 395 | 4.2). |
| 396 | |
| 397 | |
| 398 | 1.3.2. The response headers |
| 399 | --------------------------- |
| 400 | |
| 401 | Response headers work exactly like request headers, and as such, HAProxy uses |
| 402 | the same parsing function for both. Please refer to paragraph 1.2.2 for more |
| 403 | details. |
| 404 | |
| 405 | |
| 406 | 2. Configuring HAProxy |
| 407 | ---------------------- |
| 408 | |
| 409 | 2.1. Configuration file format |
| 410 | ------------------------------ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 411 | |
| 412 | HAProxy's configuration process involves 3 major sources of parameters : |
| 413 | |
| 414 | - the arguments from the command-line, which always take precedence |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 415 | - the configuration file(s), whose format is described here |
Thayne McCombs | cdbcca9 | 2021-01-07 21:24:41 -0700 | [diff] [blame] | 416 | - the running process's environment, in case some environment variables are |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 417 | explicitly referenced |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 418 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 419 | The configuration file follows a fairly simple hierarchical format which obey |
| 420 | a few basic rules: |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 421 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 422 | 1. a configuration file is an ordered sequence of statements |
| 423 | |
| 424 | 2. a statement is a single non-empty line before any unprotected "#" (hash) |
| 425 | |
| 426 | 3. a line is a series of tokens or "words" delimited by unprotected spaces or |
| 427 | tab characters |
| 428 | |
| 429 | 4. the first word or sequence of words of a line is one of the keywords or |
| 430 | keyword sequences listed in this document |
| 431 | |
| 432 | 5. all other words are all arguments of the first one, some being well-known |
| 433 | keywords listed in this document, others being values, references to other |
| 434 | parts of the configuration, or expressions |
| 435 | |
| 436 | 6. certain keywords delimit a section inside which only a subset of keywords |
| 437 | are supported |
| 438 | |
| 439 | 7. a section ends at the end of a file or on a special keyword starting a new |
| 440 | section |
| 441 | |
| 442 | This is all that is needed to know to write a simple but reliable configuration |
| 443 | generator, but this is not enough to reliably parse any configuration nor to |
| 444 | figure how to deal with certain corner cases. |
| 445 | |
| 446 | First, there are a few consequences of the rules above. Rule 6 and 7 imply that |
| 447 | the keywords used to define a new section are valid everywhere and cannot have |
| 448 | a different meaning in a specific section. These keywords are always a single |
| 449 | word (as opposed to a sequence of words), and traditionally the section that |
| 450 | follows them is designated using the same name. For example when speaking about |
| 451 | the "global section", it designates the section of configuration that follows |
| 452 | the "global" keyword. This usage is used a lot in error messages to help locate |
| 453 | the parts that need to be addressed. |
| 454 | |
| 455 | A number of sections create an internal object or configuration space, which |
| 456 | requires to be distinguished from other ones. In this case they will take an |
| 457 | extra word which will set the name of this particular section. For some of them |
| 458 | the section name is mandatory. For example "frontend foo" will create a new |
| 459 | section of type "frontend" named "foo". Usually a name is specific to its |
| 460 | section and two sections of different types may use the same name, but this is |
| 461 | not recommended as it tends to complexify configuration management. |
| 462 | |
| 463 | A direct consequence of rule 7 is that when multiple files are read at once, |
| 464 | each of them must start with a new section, and the end of each file will end |
| 465 | a section. A file cannot contain sub-sections nor end an existing section and |
| 466 | start a new one. |
| 467 | |
| 468 | Rule 1 mentioned that ordering matters. Indeed, some keywords create directives |
| 469 | that can be repeated multiple times to create ordered sequences of rules to be |
| 470 | applied in a certain order. For example "tcp-request" can be used to alternate |
| 471 | "accept" and "reject" rules on varying criteria. As such, a configuration file |
| 472 | processor must always preserve a section's ordering when editing a file. The |
| 473 | ordering of sections usually does not matter except for the global section |
| 474 | which must be placed before other sections, but it may be repeated if needed. |
| 475 | In addition, some automatic identifiers may automatically be assigned to some |
| 476 | of the created objects (e.g. proxies), and by reordering sections, their |
| 477 | identifiers will change. These ones appear in the statistics for example. As |
| 478 | such, the configuration below will assign "foo" ID number 1 and "bar" ID number |
| 479 | 2, which will be swapped if the two sections are reversed: |
| 480 | |
| 481 | listen foo |
| 482 | bind :80 |
| 483 | |
| 484 | listen bar |
| 485 | bind :81 |
| 486 | |
| 487 | Another important point is that according to rules 2 and 3 above, empty lines, |
| 488 | spaces, tabs, and comments following and unprotected "#" character are not part |
| 489 | of the configuration as they are just used as delimiters. This implies that the |
| 490 | following configurations are strictly equivalent: |
| 491 | |
| 492 | global#this is the global section |
| 493 | daemon#daemonize |
| 494 | frontend foo |
| 495 | mode http # or tcp |
| 496 | |
| 497 | and: |
| 498 | |
| 499 | global |
| 500 | daemon |
| 501 | |
| 502 | # this is the public web frontend |
| 503 | frontend foo |
| 504 | mode http |
| 505 | |
| 506 | The common practice is to align to the left only the keyword that initiates a |
| 507 | new section, and indent (i.e. prepend a tab character or a few spaces) all |
| 508 | other keywords so that it's instantly visible that they belong to the same |
| 509 | section (as done in the second example above). Placing comments before a new |
| 510 | section helps the reader decide if it's the desired one. Leaving a blank line |
| 511 | at the end of a section also visually helps spotting the end when editing it. |
| 512 | |
| 513 | Tabs are very convenient for indent but they do not copy-paste well. If spaces |
| 514 | are used instead, it is recommended to avoid placing too many (2 to 4) so that |
| 515 | editing in field doesn't become a burden with limited editors that do not |
| 516 | support automatic indent. |
| 517 | |
| 518 | In the early days it used to be common to see arguments split at fixed tab |
| 519 | positions because most keywords would not take more than two arguments. With |
| 520 | modern versions featuring complex expressions this practice does not stand |
| 521 | anymore, and is not recommended. |
| 522 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 523 | |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 524 | 2.2. Quoting and escaping |
| 525 | ------------------------- |
| 526 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 527 | In modern configurations, some arguments require the use of some characters |
| 528 | that were previously considered as pure delimiters. In order to make this |
| 529 | possible, HAProxy supports character escaping by prepending a backslash ('\') |
| 530 | in front of the character to be escaped, weak quoting within double quotes |
| 531 | ('"') and strong quoting within single quotes ("'"). |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 532 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 533 | This is pretty similar to what is done in a number of programming languages and |
| 534 | very close to what is commonly encountered in Bourne shell. The principle is |
| 535 | the following: while the configuration parser cuts the lines into words, it |
| 536 | also takes care of quotes and backslashes to decide whether a character is a |
| 537 | delimiter or is the raw representation of this character within the current |
| 538 | word. The escape character is then removed, the quotes are removed, and the |
| 539 | remaining word is used as-is as a keyword or argument for example. |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 540 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 541 | If a backslash is needed in a word, it must either be escaped using itself |
| 542 | (i.e. double backslash) or be strongly quoted. |
| 543 | |
| 544 | Escaping outside quotes is achieved by preceding a special character by a |
| 545 | backslash ('\'): |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 546 | |
| 547 | \ to mark a space and differentiate it from a delimiter |
| 548 | \# to mark a hash and differentiate it from a comment |
| 549 | \\ to use a backslash |
| 550 | \' to use a single quote and differentiate it from strong quoting |
| 551 | \" to use a double quote and differentiate it from weak quoting |
| 552 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 553 | In addition, a few non-printable characters may be emitted using their usual |
| 554 | C-language representation: |
| 555 | |
| 556 | \n to insert a line feed (LF, character \x0a or ASCII 10 decimal) |
| 557 | \r to insert a carriage return (CR, character \x0d or ASCII 13 decimal) |
| 558 | \t to insert a tab (character \x09 or ASCII 9 decimal) |
| 559 | \xNN to insert character having ASCII code hex NN (e.g \x0a for LF). |
| 560 | |
| 561 | Weak quoting is achieved by surrounding double quotes ("") around the character |
| 562 | or sequence of characters to protect. Weak quoting prevents the interpretation |
| 563 | of: |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 564 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 565 | space or tab as a word separator |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 566 | ' single quote as a strong quoting delimiter |
| 567 | # hash as a comment start |
| 568 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 569 | Weak quoting permits the interpretation of environment variables (which are not |
| 570 | evaluated outside of quotes) by preceding them with a dollar sign ('$'). If a |
| 571 | dollar character is needed inside double quotes, it must be escaped using a |
| 572 | backslash. |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 573 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 574 | Strong quoting is achieved by surrounding single quotes ('') around the |
| 575 | character or sequence of characters to protect. Inside single quotes, nothing |
| 576 | is interpreted, it's the efficient way to quote regular expressions. |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 577 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 578 | As a result, here is the matrix indicating how special characters can be |
| 579 | entered in different contexts (unprintable characters are replaced with their |
| 580 | name within angle brackets). Note that some characters that may only be |
| 581 | represented escaped have no possible representation inside single quotes, |
| 582 | hence the '-' there: |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 583 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 584 | Character | Unquoted | Weakly quoted | Strongly quoted |
| 585 | -----------+---------------+-----------------------------+----------------- |
| 586 | <TAB> | \<TAB>, \x09 | "<TAB>", "\<TAB>", "\x09" | '<TAB>' |
| 587 | <LF> | \n, \x0a | "\n", "\x0a" | - |
| 588 | <CR> | \r, \x0d | "\r", "\x0d" | - |
| 589 | <SPC> | \<SPC>, \x20 | "<SPC>", "\<SPC>", "\x20" | '<SPC>' |
| 590 | " | \", \x22 | "\"", "\x22" | '"' |
| 591 | # | \#, \x23 | "#", "\#", "\x23" | '#' |
| 592 | $ | $, \$, \x24 | "\$", "\x24" | '$' |
| 593 | ' | \', \x27 | "'", "\'", "\x27" | - |
| 594 | \ | \\, \x5c | "\\", "\x5c" | '\' |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 595 | |
| 596 | Example: |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 597 | # those are all strictly equivalent: |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 598 | log-format %{+Q}o\ %t\ %s\ %{-Q}r |
| 599 | log-format "%{+Q}o %t %s %{-Q}r" |
| 600 | log-format '%{+Q}o %t %s %{-Q}r' |
| 601 | log-format "%{+Q}o %t"' %s %{-Q}r' |
| 602 | log-format "%{+Q}o %t"' %s'\ %{-Q}r |
| 603 | |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 604 | There is one particular case where a second level of quoting or escaping may be |
| 605 | necessary. Some keywords take arguments within parenthesis, sometimes delimited |
| 606 | by commas. These arguments are commonly integers or predefined words, but when |
| 607 | they are arbitrary strings, it may be required to perform a separate level of |
| 608 | escaping to disambiguate the characters that belong to the argument from the |
| 609 | characters that are used to delimit the arguments themselves. A pretty common |
| 610 | case is the "regsub" converter. It takes a regular expression in argument, and |
| 611 | if a closing parenthesis is needed inside, this one will require to have its |
| 612 | own quotes. |
| 613 | |
| 614 | The keyword argument parser is exactly the same as the top-level one regarding |
| 615 | quotes, except that is will not make special cases of backslashes. But what is |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 616 | not always obvious is that the delimiters used inside must first be escaped or |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 617 | quoted so that they are not resolved at the top level. |
| 618 | |
| 619 | Let's take this example making use of the "regsub" converter which takes 3 |
| 620 | arguments, one regular expression, one replacement string and one set of flags: |
| 621 | |
| 622 | # replace all occurrences of "foo" with "blah" in the path: |
| 623 | http-request set-path %[path,regsub(foo,blah,g)] |
| 624 | |
| 625 | Here no special quoting was necessary. But if now we want to replace either |
| 626 | "foo" or "bar" with "blah", we'll need the regular expression "(foo|bar)". We |
| 627 | cannot write: |
| 628 | |
| 629 | http-request set-path %[path,regsub((foo|bar),blah,g)] |
| 630 | |
| 631 | because we would like the string to cut like this: |
| 632 | |
| 633 | http-request set-path %[path,regsub((foo|bar),blah,g)] |
| 634 | |---------|----|-| |
| 635 | arg1 _/ / / |
| 636 | arg2 __________/ / |
| 637 | arg3 ______________/ |
| 638 | |
| 639 | but actually what is passed is a string between the opening and closing |
| 640 | parenthesis then garbage: |
| 641 | |
| 642 | http-request set-path %[path,regsub((foo|bar),blah,g)] |
| 643 | |--------|--------| |
| 644 | arg1=(foo|bar _/ / |
| 645 | trailing garbage _________/ |
| 646 | |
| 647 | The obvious solution here seems to be that the closing parenthesis needs to be |
| 648 | quoted, but alone this will not work, because as mentioned above, quotes are |
| 649 | processed by the top-level parser which will resolve them before processing |
| 650 | this word: |
| 651 | |
| 652 | http-request set-path %[path,regsub("(foo|bar)",blah,g)] |
| 653 | ------------ -------- ---------------------------------- |
| 654 | word1 word2 word3=%[path,regsub((foo|bar),blah,g)] |
| 655 | |
| 656 | So we didn't change anything for the argument parser at the second level which |
| 657 | still sees a truncated regular expression as the only argument, and garbage at |
| 658 | the end of the string. By escaping the quotes they will be passed unmodified to |
| 659 | the second level: |
| 660 | |
| 661 | http-request set-path %[path,regsub(\"(foo|bar)\",blah,g)] |
| 662 | ------------ -------- ------------------------------------ |
| 663 | word1 word2 word3=%[path,regsub("(foo|bar)",blah,g)] |
| 664 | |---------||----|-| |
| 665 | arg1=(foo|bar) _/ / / |
| 666 | arg2=blah ___________/ / |
| 667 | arg3=g _______________/ |
| 668 | |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 669 | Another approach consists in using single quotes outside the whole string and |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 670 | double quotes inside (so that the double quotes are not stripped again): |
| 671 | |
| 672 | http-request set-path '%[path,regsub("(foo|bar)",blah,g)]' |
| 673 | ------------ -------- ---------------------------------- |
| 674 | word1 word2 word3=%[path,regsub("(foo|bar)",blah,g)] |
| 675 | |---------||----|-| |
| 676 | arg1=(foo|bar) _/ / / |
| 677 | arg2 ___________/ / |
| 678 | arg3 _______________/ |
| 679 | |
| 680 | When using regular expressions, it can happen that the dollar ('$') character |
| 681 | appears in the expression or that a backslash ('\') is used in the replacement |
| 682 | string. In this case these ones will also be processed inside the double quotes |
| 683 | thus single quotes are preferred (or double escaping). Example: |
| 684 | |
| 685 | http-request set-path '%[path,regsub("^/(here)(/|$)","my/\1",g)]' |
| 686 | ------------ -------- ----------------------------------------- |
| 687 | word1 word2 word3=%[path,regsub("^/(here)(/|$)","my/\1",g)] |
| 688 | |-------------| |-----||-| |
| 689 | arg1=(here)(/|$) _/ / / |
| 690 | arg2=my/\1 ________________/ / |
| 691 | arg3 ______________________/ |
| 692 | |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 693 | Remember that backslahes are not escape characters within single quotes and |
Willy Tarreau | 6f1129d | 2020-11-25 19:58:20 +0100 | [diff] [blame] | 694 | that the whole word3 above is already protected against them using the single |
| 695 | quotes. Conversely, if double quotes had been used around the whole expression, |
| 696 | single the dollar character and the backslashes would have been resolved at top |
| 697 | level, breaking the argument contents at the second level. |
| 698 | |
| 699 | When in doubt, simply do not use quotes anywhere, and start to place single or |
| 700 | double quotes around arguments that require a comma or a closing parenthesis, |
| 701 | and think about escaping these quotes using a backslash of the string contains |
| 702 | a dollar or a backslash. Again, this is pretty similar to what is used under |
| 703 | a Bourne shell when double-escaping a command passed to "eval". For API writers |
| 704 | the best is probably to place escaped quotes around each and every argument, |
| 705 | regardless of their contents. Users will probably find that using single quotes |
| 706 | around the whole expression and double quotes around each argument provides |
| 707 | more readable configurations. |
William Lallemand | f9873ba | 2015-05-05 17:37:14 +0200 | [diff] [blame] | 708 | |
| 709 | |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 710 | 2.3. Environment variables |
| 711 | -------------------------- |
| 712 | |
| 713 | HAProxy's configuration supports environment variables. Those variables are |
| 714 | interpreted only within double quotes. Variables are expanded during the |
| 715 | configuration parsing. Variable names must be preceded by a dollar ("$") and |
| 716 | optionally enclosed with braces ("{}") similarly to what is done in Bourne |
| 717 | shell. Variable names can contain alphanumerical characters or the character |
Amaury Denoyelle | fa41cb6 | 2020-10-01 14:32:35 +0200 | [diff] [blame] | 718 | underscore ("_") but should not start with a digit. If the variable contains a |
| 719 | list of several values separated by spaces, it can be expanded as individual |
| 720 | arguments by enclosing the variable with braces and appending the suffix '[*]' |
| 721 | before the closing brace. |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 722 | |
| 723 | Example: |
| 724 | |
| 725 | bind "fd@${FD_APP1}" |
| 726 | |
| 727 | log "${LOCAL_SYSLOG}:514" local0 notice # send to local server |
| 728 | |
| 729 | user "$HAPROXY_USER" |
| 730 | |
William Lallemand | 4d03e43 | 2019-06-14 15:35:37 +0200 | [diff] [blame] | 731 | Some variables are defined by HAProxy, they can be used in the configuration |
| 732 | file, or could be inherited by a program (See 3.7. Programs): |
William Lallemand | daf4cd2 | 2018-04-17 16:46:13 +0200 | [diff] [blame] | 733 | |
William Lallemand | 4d03e43 | 2019-06-14 15:35:37 +0200 | [diff] [blame] | 734 | * HAPROXY_LOCALPEER: defined at the startup of the process which contains the |
| 735 | name of the local peer. (See "-L" in the management guide.) |
| 736 | |
| 737 | * HAPROXY_CFGFILES: list of the configuration files loaded by HAProxy, |
| 738 | separated by semicolons. Can be useful in the case you specified a |
| 739 | directory. |
| 740 | |
| 741 | * HAPROXY_MWORKER: In master-worker mode, this variable is set to 1. |
| 742 | |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 743 | * HAPROXY_CLI: configured listeners addresses of the stats socket for every |
William Lallemand | 4d03e43 | 2019-06-14 15:35:37 +0200 | [diff] [blame] | 744 | processes, separated by semicolons. |
| 745 | |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 746 | * HAPROXY_MASTER_CLI: In master-worker mode, listeners addresses of the master |
William Lallemand | 4d03e43 | 2019-06-14 15:35:37 +0200 | [diff] [blame] | 747 | CLI, separated by semicolons. |
| 748 | |
| 749 | See also "external-check command" for other variables. |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 750 | |
Willy Tarreau | 4b10302 | 2021-02-12 17:59:10 +0100 | [diff] [blame] | 751 | |
| 752 | 2.4. Conditional blocks |
| 753 | ----------------------- |
| 754 | |
| 755 | It may sometimes be convenient to be able to conditionally enable or disable |
| 756 | some arbitrary parts of the configuration, for example to enable/disable SSL or |
| 757 | ciphers, enable or disable some pre-production listeners without modifying the |
| 758 | configuration, or adjust the configuration's syntax to support two distinct |
| 759 | versions of HAProxy during a migration.. HAProxy brings a set of nestable |
| 760 | preprocessor-like directives which allow to integrate or ignore some blocks of |
| 761 | text. These directives must be placed on their own line and they act on the |
| 762 | lines that follow them. Two of them support an expression, the other ones only |
| 763 | switch to an alternate block or end a current level. The 4 following directives |
| 764 | are defined to form conditional blocks: |
| 765 | |
| 766 | - .if <condition> |
| 767 | - .elif <condition> |
| 768 | - .else |
| 769 | - .endif |
| 770 | |
| 771 | The ".if" directive nests a new level, ".elif" stays at the same level, ".else" |
| 772 | as well, and ".endif" closes a level. Each ".if" must be terminated by a |
| 773 | matching ".endif". The ".elif" may only be placed after ".if" or ".elif", and |
| 774 | there is no limit to the number of ".elif" that may be chained. There may be |
| 775 | only one ".else" per ".if" and it must always be after the ".if" or the last |
| 776 | ".elif" of a block. |
| 777 | |
| 778 | Comments may be placed on the same line if needed after a '#', they will be |
| 779 | ignored. The directives are tokenized like other configuration directives, and |
| 780 | as such it is possible to use environment variables in conditions. |
| 781 | |
| 782 | The conditions are currently limited to: |
| 783 | |
| 784 | - an empty string, always returns "false" |
| 785 | - the integer zero ('0'), always returns "false" |
| 786 | - a non-nul integer (e.g. '1'), always returns "true". |
| 787 | |
| 788 | Other patterns are not supported yet but the purpose is to bring a few |
| 789 | functions to test for certain build options and supported features. |
| 790 | |
| 791 | Three other directives are provided to report some status: |
| 792 | |
| 793 | - .notice "message" : emit this message at level NOTICE |
| 794 | - .warning "message" : emit this message at level WARNING |
| 795 | - .alert "message" : emit this message at level ALERT |
| 796 | |
| 797 | Messages emitted at level WARNING may cause the process to fail to start if the |
| 798 | "strict-mode" is enabled. Messages emitted at level ALERT will always cause a |
| 799 | fatal error. These can be used to detect some inappropriate conditions and |
| 800 | provide advice to the user. |
| 801 | |
| 802 | Example: |
| 803 | |
| 804 | .if "${A}" |
| 805 | .if "${B}" |
| 806 | .notice "A=1, B=1" |
| 807 | .elif "${C}" |
| 808 | .notice "A=1, B=0, C=1" |
| 809 | .elif "${D}" |
| 810 | .warning "A=1, B=0, C=0, D=1" |
| 811 | .else |
| 812 | .alert "A=1, B=0, C=0, D=0" |
| 813 | .endif |
| 814 | .else |
| 815 | .notice "A=0" |
| 816 | .endif |
| 817 | |
| 818 | |
| 819 | 2.5. Time format |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 820 | ---------------- |
| 821 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 822 | Some parameters involve values representing time, such as timeouts. These |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 823 | values are generally expressed in milliseconds (unless explicitly stated |
| 824 | otherwise) but may be expressed in any other unit by suffixing the unit to the |
| 825 | numeric value. It is important to consider this because it will not be repeated |
| 826 | for every keyword. Supported units are : |
| 827 | |
| 828 | - us : microseconds. 1 microsecond = 1/1000000 second |
| 829 | - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default. |
| 830 | - s : seconds. 1s = 1000ms |
| 831 | - m : minutes. 1m = 60s = 60000ms |
| 832 | - h : hours. 1h = 60m = 3600s = 3600000ms |
| 833 | - d : days. 1d = 24h = 1440m = 86400s = 86400000ms |
| 834 | |
| 835 | |
Willy Tarreau | 4b10302 | 2021-02-12 17:59:10 +0100 | [diff] [blame] | 836 | 2.6. Examples |
Patrick Mezard | 35da19c | 2010-06-12 17:02:47 +0200 | [diff] [blame] | 837 | ------------- |
| 838 | |
| 839 | # Simple configuration for an HTTP proxy listening on port 80 on all |
| 840 | # interfaces and forwarding requests to a single backend "servers" with a |
| 841 | # single server "server1" listening on 127.0.0.1:8000 |
| 842 | global |
| 843 | daemon |
| 844 | maxconn 256 |
| 845 | |
| 846 | defaults |
| 847 | mode http |
| 848 | timeout connect 5000ms |
| 849 | timeout client 50000ms |
| 850 | timeout server 50000ms |
| 851 | |
| 852 | frontend http-in |
| 853 | bind *:80 |
| 854 | default_backend servers |
| 855 | |
| 856 | backend servers |
| 857 | server server1 127.0.0.1:8000 maxconn 32 |
| 858 | |
| 859 | |
| 860 | # The same configuration defined with a single listen block. Shorter but |
| 861 | # less expressive, especially in HTTP mode. |
| 862 | global |
| 863 | daemon |
| 864 | maxconn 256 |
| 865 | |
| 866 | defaults |
| 867 | mode http |
| 868 | timeout connect 5000ms |
| 869 | timeout client 50000ms |
| 870 | timeout server 50000ms |
| 871 | |
| 872 | listen http-in |
| 873 | bind *:80 |
| 874 | server server1 127.0.0.1:8000 maxconn 32 |
| 875 | |
| 876 | |
| 877 | Assuming haproxy is in $PATH, test these configurations in a shell with: |
| 878 | |
Willy Tarreau | ccb289d | 2010-12-11 20:19:38 +0100 | [diff] [blame] | 879 | $ sudo haproxy -f configuration.conf -c |
Patrick Mezard | 35da19c | 2010-06-12 17:02:47 +0200 | [diff] [blame] | 880 | |
| 881 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 882 | 3. Global parameters |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 883 | -------------------- |
| 884 | |
| 885 | Parameters in the "global" section are process-wide and often OS-specific. They |
| 886 | are generally set once for all and do not need being changed once correct. Some |
| 887 | of them have command-line equivalents. |
| 888 | |
| 889 | The following keywords are supported in the "global" section : |
| 890 | |
| 891 | * Process management and security |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 892 | - ca-base |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 893 | - chroot |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 894 | - crt-base |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 895 | - cpu-map |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 896 | - daemon |
Willy Tarreau | 8a022d5 | 2021-04-27 20:29:11 +0200 | [diff] [blame] | 897 | - default-path |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 898 | - description |
| 899 | - deviceatlas-json-file |
| 900 | - deviceatlas-log-level |
| 901 | - deviceatlas-separator |
| 902 | - deviceatlas-properties-cookie |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 903 | - external-check |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 904 | - gid |
| 905 | - group |
Cyril Bonté | 203ec5a | 2017-03-23 22:44:13 +0100 | [diff] [blame] | 906 | - hard-stop-after |
Christopher Faulet | 98fbe95 | 2019-07-22 16:18:24 +0200 | [diff] [blame] | 907 | - h1-case-adjust |
| 908 | - h1-case-adjust-file |
Willy Tarreau | d96f112 | 2019-12-03 07:07:36 +0100 | [diff] [blame] | 909 | - insecure-fork-wanted |
Willy Tarreau | a45a8b5 | 2019-12-06 16:31:45 +0100 | [diff] [blame] | 910 | - insecure-setuid-wanted |
Emmanuel Hocdet | 70df7bf | 2019-01-04 11:08:20 +0100 | [diff] [blame] | 911 | - issuers-chain-path |
Dragan Dosen | 13cd54c | 2020-06-18 18:24:05 +0200 | [diff] [blame] | 912 | - localpeer |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 913 | - log |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 914 | - log-tag |
Joe Williams | df5b38f | 2010-12-29 17:05:48 +0100 | [diff] [blame] | 915 | - log-send-hostname |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 916 | - lua-load |
Thierry Fournier | 59f11be | 2020-11-29 00:37:41 +0100 | [diff] [blame] | 917 | - lua-load-per-thread |
Tim Duesterhus | dd74b5f | 2020-01-12 13:55:40 +0100 | [diff] [blame] | 918 | - lua-prepend-path |
William Lallemand | 27edc4b | 2019-05-07 17:49:33 +0200 | [diff] [blame] | 919 | - mworker-max-reloads |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 920 | - nbproc |
Christopher Faulet | be0faa2 | 2017-08-29 15:37:10 +0200 | [diff] [blame] | 921 | - nbthread |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 922 | - node |
Amaury Denoyelle | 0f50cb9 | 2021-03-26 18:50:33 +0100 | [diff] [blame] | 923 | - numa-cpu-mapping |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 924 | - pidfile |
Willy Tarreau | 119e50e | 2020-05-22 13:53:29 +0200 | [diff] [blame] | 925 | - pp2-never-send-local |
Willy Tarreau | 1d54972 | 2016-02-16 12:41:57 +0100 | [diff] [blame] | 926 | - presetenv |
| 927 | - resetenv |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 928 | - uid |
| 929 | - ulimit-n |
| 930 | - user |
Willy Tarreau | 636848a | 2019-04-15 19:38:50 +0200 | [diff] [blame] | 931 | - set-dumpable |
Willy Tarreau | 13d2ba2 | 2021-03-26 11:38:08 +0100 | [diff] [blame] | 932 | - set-var |
Willy Tarreau | 1d54972 | 2016-02-16 12:41:57 +0100 | [diff] [blame] | 933 | - setenv |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 934 | - stats |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 935 | - ssl-default-bind-ciphers |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 936 | - ssl-default-bind-ciphersuites |
Jerome Magnin | b203ff6 | 2020-04-03 15:28:22 +0200 | [diff] [blame] | 937 | - ssl-default-bind-curves |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 938 | - ssl-default-bind-options |
| 939 | - ssl-default-server-ciphers |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 940 | - ssl-default-server-ciphersuites |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 941 | - ssl-default-server-options |
| 942 | - ssl-dh-param-file |
Emeric Brun | 850efd5 | 2014-01-29 12:24:34 +0100 | [diff] [blame] | 943 | - ssl-server-verify |
Emmanuel Hocdet | c3b7e74 | 2020-04-22 11:06:19 +0200 | [diff] [blame] | 944 | - ssl-skip-self-issued-ca |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 945 | - unix-bind |
Willy Tarreau | 1d54972 | 2016-02-16 12:41:57 +0100 | [diff] [blame] | 946 | - unsetenv |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 947 | - 51degrees-data-file |
| 948 | - 51degrees-property-name-list |
Dragan Dosen | 93b38d9 | 2015-06-29 16:43:25 +0200 | [diff] [blame] | 949 | - 51degrees-property-separator |
Dragan Dosen | ae6d39a | 2015-06-29 16:43:27 +0200 | [diff] [blame] | 950 | - 51degrees-cache-size |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 951 | - wurfl-data-file |
| 952 | - wurfl-information-list |
| 953 | - wurfl-information-list-separator |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 954 | - wurfl-cache-size |
William Dauchy | 0fec3ab | 2019-10-27 20:08:11 +0100 | [diff] [blame] | 955 | - strict-limits |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 956 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 957 | * Performance tuning |
William Dauchy | 0a8824f | 2019-10-27 20:08:09 +0100 | [diff] [blame] | 958 | - busy-polling |
Willy Tarreau | 1746eec | 2014-04-25 10:46:47 +0200 | [diff] [blame] | 959 | - max-spread-checks |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 960 | - maxconn |
Willy Tarreau | 81c25d0 | 2011-09-07 15:17:21 +0200 | [diff] [blame] | 961 | - maxconnrate |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 962 | - maxcomprate |
William Lallemand | 072a2bf | 2012-11-20 17:01:01 +0100 | [diff] [blame] | 963 | - maxcompcpuusage |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 964 | - maxpipes |
Willy Tarreau | 93e7c00 | 2013-10-07 18:51:07 +0200 | [diff] [blame] | 965 | - maxsessrate |
Willy Tarreau | 403edff | 2012-09-06 11:58:37 +0200 | [diff] [blame] | 966 | - maxsslconn |
Willy Tarreau | e43d532 | 2013-10-07 20:01:52 +0200 | [diff] [blame] | 967 | - maxsslrate |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 968 | - maxzlibmem |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 969 | - noepoll |
| 970 | - nokqueue |
Emmanuel Hocdet | 0ba4f48 | 2019-04-08 16:53:32 +0000 | [diff] [blame] | 971 | - noevports |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 972 | - nopoll |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 973 | - nosplice |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 974 | - nogetaddrinfo |
Lukas Tribus | a0bcbdc | 2016-09-12 21:42:20 +0000 | [diff] [blame] | 975 | - noreuseport |
Willy Tarreau | 75c62c2 | 2018-11-22 11:02:09 +0100 | [diff] [blame] | 976 | - profiling.tasks |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 977 | - spread-checks |
Baptiste Assmann | 5626f48 | 2015-08-23 10:00:10 +0200 | [diff] [blame] | 978 | - server-state-base |
Baptiste Assmann | ef1f0fc | 2015-08-23 10:06:39 +0200 | [diff] [blame] | 979 | - server-state-file |
Grant Zhang | 872f9c2 | 2017-01-21 01:10:18 +0000 | [diff] [blame] | 980 | - ssl-engine |
Grant Zhang | fa6c7ee | 2017-01-14 01:42:15 +0000 | [diff] [blame] | 981 | - ssl-mode-async |
Baptiste Assmann | 3493d0f | 2015-10-12 20:21:23 +0200 | [diff] [blame] | 982 | - tune.buffers.limit |
| 983 | - tune.buffers.reserve |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 984 | - tune.bufsize |
Willy Tarreau | 43961d5 | 2010-10-04 20:39:20 +0200 | [diff] [blame] | 985 | - tune.chksize |
William Lallemand | f374783 | 2012-11-09 12:33:10 +0100 | [diff] [blame] | 986 | - tune.comp.maxlevel |
Willy Tarreau | bc52bec | 2020-06-18 08:58:47 +0200 | [diff] [blame] | 987 | - tune.fd.edge-triggered |
Willy Tarreau | fe20e5b | 2017-07-27 11:42:14 +0200 | [diff] [blame] | 988 | - tune.h2.header-table-size |
Willy Tarreau | e6baec0 | 2017-07-27 11:45:11 +0200 | [diff] [blame] | 989 | - tune.h2.initial-window-size |
Willy Tarreau | 5242ef8 | 2017-07-27 11:47:28 +0200 | [diff] [blame] | 990 | - tune.h2.max-concurrent-streams |
Willy Tarreau | 193b8c6 | 2012-11-22 00:17:38 +0100 | [diff] [blame] | 991 | - tune.http.cookielen |
Stéphane Cottin | 23e9e93 | 2017-05-18 08:58:41 +0200 | [diff] [blame] | 992 | - tune.http.logurilen |
Willy Tarreau | ac1932d | 2011-10-24 19:14:41 +0200 | [diff] [blame] | 993 | - tune.http.maxhdr |
Willy Tarreau | 76cc699 | 2020-07-01 18:49:24 +0200 | [diff] [blame] | 994 | - tune.idle-pool.shared |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 995 | - tune.idletimer |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 996 | - tune.lua.forced-yield |
Willy Tarreau | 32f61e2 | 2015-03-18 17:54:59 +0100 | [diff] [blame] | 997 | - tune.lua.maxmem |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 998 | - tune.lua.session-timeout |
| 999 | - tune.lua.task-timeout |
Thierry FOURNIER | 7dd784b | 2015-10-01 14:49:33 +0200 | [diff] [blame] | 1000 | - tune.lua.service-timeout |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 1001 | - tune.maxaccept |
| 1002 | - tune.maxpollevents |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 1003 | - tune.maxrewrite |
Willy Tarreau | f3045d2 | 2015-04-29 16:24:50 +0200 | [diff] [blame] | 1004 | - tune.pattern.cache-size |
Willy Tarreau | bd9a0a7 | 2011-10-23 21:14:29 +0200 | [diff] [blame] | 1005 | - tune.pipesize |
Willy Tarreau | a8e2d97 | 2020-07-01 18:27:16 +0200 | [diff] [blame] | 1006 | - tune.pool-high-fd-ratio |
| 1007 | - tune.pool-low-fd-ratio |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 1008 | - tune.rcvbuf.client |
| 1009 | - tune.rcvbuf.server |
Willy Tarreau | b22fc30 | 2015-12-14 12:04:35 +0100 | [diff] [blame] | 1010 | - tune.recv_enough |
Olivier Houchard | 1599b80 | 2018-05-24 18:59:04 +0200 | [diff] [blame] | 1011 | - tune.runqueue-depth |
Willy Tarreau | e7723bd | 2020-06-24 11:11:02 +0200 | [diff] [blame] | 1012 | - tune.sched.low-latency |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 1013 | - tune.sndbuf.client |
| 1014 | - tune.sndbuf.server |
Willy Tarreau | 6ec58db | 2012-11-16 16:32:15 +0100 | [diff] [blame] | 1015 | - tune.ssl.cachesize |
William Lallemand | 7d42ef5 | 2020-07-06 11:41:30 +0200 | [diff] [blame] | 1016 | - tune.ssl.keylog |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 1017 | - tune.ssl.lifetime |
Emeric Brun | 8dc6039 | 2014-05-09 13:52:00 +0200 | [diff] [blame] | 1018 | - tune.ssl.force-private-cache |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 1019 | - tune.ssl.maxrecord |
Remi Gacogne | f46cd6e | 2014-06-12 14:58:40 +0200 | [diff] [blame] | 1020 | - tune.ssl.default-dh-param |
Christopher Faulet | 31af49d | 2015-06-09 17:29:50 +0200 | [diff] [blame] | 1021 | - tune.ssl.ssl-ctx-cache-size |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 1022 | - tune.ssl.capture-cipherlist-size |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 1023 | - tune.vars.global-max-size |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 1024 | - tune.vars.proc-max-size |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 1025 | - tune.vars.reqres-max-size |
| 1026 | - tune.vars.sess-max-size |
| 1027 | - tune.vars.txn-max-size |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 1028 | - tune.zlib.memlevel |
| 1029 | - tune.zlib.windowsize |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 1030 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1031 | * Debugging |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1032 | - quiet |
Willy Tarreau | 3eb10b8 | 2020-04-15 16:42:39 +0200 | [diff] [blame] | 1033 | - zero-warning |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1034 | |
| 1035 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 1036 | 3.1. Process management and security |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1037 | ------------------------------------ |
| 1038 | |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 1039 | ca-base <dir> |
| 1040 | Assigns a default directory to fetch SSL CA certificates and CRLs from when a |
Emmanuel Hocdet | 842e94e | 2019-12-16 16:39:17 +0100 | [diff] [blame] | 1041 | relative path is used with "ca-file", "ca-verify-file" or "crl-file" |
| 1042 | directives. Absolute locations specified in "ca-file", "ca-verify-file" and |
| 1043 | "crl-file" prevail and ignore "ca-base". |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 1044 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1045 | chroot <jail dir> |
| 1046 | Changes current directory to <jail dir> and performs a chroot() there before |
| 1047 | dropping privileges. This increases the security level in case an unknown |
| 1048 | vulnerability would be exploited, since it would make it very hard for the |
| 1049 | attacker to exploit the system. This only works when the process is started |
| 1050 | with superuser privileges. It is important to ensure that <jail_dir> is both |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1051 | empty and non-writable to anyone. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 1052 | |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1053 | cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>... |
| 1054 | On Linux 2.6 and above, it is possible to bind a process or a thread to a |
| 1055 | specific CPU set. This means that the process or the thread will never run on |
| 1056 | other CPUs. The "cpu-map" directive specifies CPU sets for process or thread |
| 1057 | sets. The first argument is a process set, eventually followed by a thread |
| 1058 | set. These sets have the format |
| 1059 | |
| 1060 | all | odd | even | number[-[number]] |
| 1061 | |
| 1062 | <number>> must be a number between 1 and 32 or 64, depending on the machine's |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1063 | word size. Any process IDs above nbproc and any thread IDs above nbthread are |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1064 | ignored. It is possible to specify a range with two such number delimited by |
| 1065 | a dash ('-'). It also is possible to specify all processes at once using |
Christopher Faulet | 1dcb9cb | 2017-11-22 10:24:40 +0100 | [diff] [blame] | 1066 | "all", only odd numbers using "odd" or even numbers using "even", just like |
| 1067 | with the "bind-process" directive. The second and forthcoming arguments are |
Amaury Denoyelle | 982fb53 | 2021-04-21 18:39:58 +0200 | [diff] [blame] | 1068 | CPU sets. Each CPU set is either a unique number starting at 0 for the first |
| 1069 | CPU or a range with two such numbers delimited by a dash ('-'). Outside of |
| 1070 | Linux and BSDs, there may be a limitation on the maximum CPU index to either |
| 1071 | 31 or 63. Multiple CPU numbers or ranges may be specified, and the processes |
| 1072 | or threads will be allowed to bind to all of them. Obviously, multiple |
| 1073 | "cpu-map" directives may be specified. Each "cpu-map" directive will replace |
| 1074 | the previous ones when they overlap. A thread will be bound on the |
| 1075 | intersection of its mapping and the one of the process on which it is |
| 1076 | attached. If the intersection is null, no specific binding will be set for |
| 1077 | the thread. |
Willy Tarreau | fc6c032 | 2012-11-16 16:12:27 +0100 | [diff] [blame] | 1078 | |
Christopher Faulet | ff4121f | 2017-11-22 16:38:49 +0100 | [diff] [blame] | 1079 | Ranges can be partially defined. The higher bound can be omitted. In such |
| 1080 | case, it is replaced by the corresponding maximum value, 32 or 64 depending |
| 1081 | on the machine's word size. |
| 1082 | |
Christopher Faulet | 26028f6 | 2017-11-22 15:01:51 +0100 | [diff] [blame] | 1083 | The prefix "auto:" can be added before the process set to let HAProxy |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1084 | automatically bind a process or a thread to a CPU by incrementing |
| 1085 | process/thread and CPU sets. To be valid, both sets must have the same |
| 1086 | size. No matter the declaration order of the CPU sets, it will be bound from |
| 1087 | the lowest to the highest bound. Having a process and a thread range with the |
| 1088 | "auto:" prefix is not supported. Only one range is supported, the other one |
| 1089 | must be a fixed number. |
Christopher Faulet | 26028f6 | 2017-11-22 15:01:51 +0100 | [diff] [blame] | 1090 | |
| 1091 | Examples: |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1092 | cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs |
| 1093 | |
| 1094 | cpu-map 1/all 0-3 # bind all threads of the first process on the |
| 1095 | # first 4 CPUs |
| 1096 | |
| 1097 | cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63" |
| 1098 | # or "cpu-map 1-32 0-31" depending on the machine's |
| 1099 | # word size. |
| 1100 | |
Christopher Faulet | 26028f6 | 2017-11-22 15:01:51 +0100 | [diff] [blame] | 1101 | # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1 |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1102 | # and so on. |
Christopher Faulet | 26028f6 | 2017-11-22 15:01:51 +0100 | [diff] [blame] | 1103 | cpu-map auto:1-4 0-3 |
| 1104 | cpu-map auto:1-4 0-1 2-3 |
| 1105 | cpu-map auto:1-4 3 2 1 0 |
| 1106 | |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1107 | # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1 |
| 1108 | # and so on. |
| 1109 | cpu-map auto:1/1-4 0-3 |
| 1110 | cpu-map auto:1/1-4 0-1 2-3 |
| 1111 | cpu-map auto:1/1-4 3 2 1 0 |
| 1112 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1113 | # bind each process to exactly one CPU using all/odd/even keyword |
Christopher Faulet | 26028f6 | 2017-11-22 15:01:51 +0100 | [diff] [blame] | 1114 | cpu-map auto:all 0-63 |
| 1115 | cpu-map auto:even 0-31 |
| 1116 | cpu-map auto:odd 32-63 |
| 1117 | |
| 1118 | # invalid cpu-map because process and CPU sets have different sizes. |
| 1119 | cpu-map auto:1-4 0 # invalid |
| 1120 | cpu-map auto:1 0-3 # invalid |
| 1121 | |
Christopher Faulet | cb6a945 | 2017-11-22 16:50:41 +0100 | [diff] [blame] | 1122 | # invalid cpu-map because automatic binding is used with a process range |
| 1123 | # and a thread range. |
| 1124 | cpu-map auto:all/all 0 # invalid |
| 1125 | cpu-map auto:all/1-4 0 # invalid |
| 1126 | cpu-map auto:1-4/all 0 # invalid |
| 1127 | |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 1128 | crt-base <dir> |
| 1129 | Assigns a default directory to fetch SSL certificates from when a relative |
William Dauchy | 238ea3b | 2020-01-11 13:09:12 +0100 | [diff] [blame] | 1130 | path is used with "crtfile" or "crt" directives. Absolute locations specified |
| 1131 | prevail and ignore "crt-base". |
Emeric Brun | c8e8d12 | 2012-10-02 18:42:10 +0200 | [diff] [blame] | 1132 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1133 | daemon |
| 1134 | Makes the process fork into background. This is the recommended mode of |
| 1135 | operation. It is equivalent to the command line "-D" argument. It can be |
Lukas Tribus | f46bf95 | 2017-11-21 12:39:34 +0100 | [diff] [blame] | 1136 | disabled by the command line "-db" argument. This option is ignored in |
| 1137 | systemd mode. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1138 | |
Willy Tarreau | 8a022d5 | 2021-04-27 20:29:11 +0200 | [diff] [blame] | 1139 | default-path { current | config | parent | origin <path> } |
| 1140 | By default haproxy loads all files designated by a relative path from the |
| 1141 | location the process is started in. In some circumstances it might be |
| 1142 | desirable to force all relative paths to start from a different location |
| 1143 | just as if the process was started from such locations. This is what this |
| 1144 | directive is made for. Technically it will perform a temporary chdir() to |
| 1145 | the designated location while processing each configuration file, and will |
| 1146 | return to the original directory after processing each file. It takes an |
| 1147 | argument indicating the policy to use when loading files whose path does |
| 1148 | not start with a slash ('/'): |
| 1149 | - "current" indicates that all relative files are to be loaded from the |
| 1150 | directory the process is started in ; this is the default. |
| 1151 | |
| 1152 | - "config" indicates that all relative files should be loaded from the |
| 1153 | directory containing the configuration file. More specifically, if the |
| 1154 | configuration file contains a slash ('/'), the longest part up to the |
| 1155 | last slash is used as the directory to change to, otherwise the current |
| 1156 | directory is used. This mode is convenient to bundle maps, errorfiles, |
| 1157 | certificates and Lua scripts together as relocatable packages. When |
| 1158 | multiple configuration files are loaded, the directory is updated for |
| 1159 | each of them. |
| 1160 | |
| 1161 | - "parent" indicates that all relative files should be loaded from the |
| 1162 | parent of the directory containing the configuration file. More |
| 1163 | specifically, if the configuration file contains a slash ('/'), ".." |
| 1164 | is appended to the longest part up to the last slash is used as the |
| 1165 | directory to change to, otherwise the directory is "..". This mode is |
| 1166 | convenient to bundle maps, errorfiles, certificates and Lua scripts |
| 1167 | together as relocatable packages, but where each part is located in a |
| 1168 | different subdirectory (e.g. "config/", "certs/", "maps/", ...). |
| 1169 | |
| 1170 | - "origin" indicates that all relative files should be loaded from the |
| 1171 | designated (mandatory) path. This may be used to ease management of |
| 1172 | different haproxy instances running in parallel on a system, where each |
| 1173 | instance uses a different prefix but where the rest of the sections are |
| 1174 | made easily relocatable. |
| 1175 | |
| 1176 | Each "default-path" directive instantly replaces any previous one and will |
| 1177 | possibly result in switching to a different directory. While this should |
| 1178 | always result in the desired behavior, it is really not a good practice to |
| 1179 | use multiple default-path directives, and if used, the policy ought to remain |
| 1180 | consistent across all configuration files. |
| 1181 | |
| 1182 | Warning: some configuration elements such as maps or certificates are |
| 1183 | uniquely identified by their configured path. By using a relocatable layout, |
| 1184 | it becomes possible for several of them to end up with the same unique name, |
| 1185 | making it difficult to update them at run time, especially when multiple |
| 1186 | configuration files are loaded from different directories. It is essential to |
| 1187 | observe a strict collision-free file naming scheme before adopting relative |
| 1188 | paths. A robust approach could consist in prefixing all files names with |
| 1189 | their respective site name, or in doing so at the directory level. |
| 1190 | |
David Carlier | 8167f30 | 2015-06-01 13:50:06 +0200 | [diff] [blame] | 1191 | deviceatlas-json-file <path> |
| 1192 | Sets the path of the DeviceAtlas JSON data file to be loaded by the API. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1193 | The path must be a valid JSON data file and accessible by HAProxy process. |
David Carlier | 8167f30 | 2015-06-01 13:50:06 +0200 | [diff] [blame] | 1194 | |
| 1195 | deviceatlas-log-level <value> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1196 | Sets the level of information returned by the API. This directive is |
David Carlier | 8167f30 | 2015-06-01 13:50:06 +0200 | [diff] [blame] | 1197 | optional and set to 0 by default if not set. |
| 1198 | |
| 1199 | deviceatlas-separator <char> |
| 1200 | Sets the character separator for the API properties results. This directive |
| 1201 | is optional and set to | by default if not set. |
| 1202 | |
Cyril Bonté | 0306c4a | 2015-10-26 22:37:38 +0100 | [diff] [blame] | 1203 | deviceatlas-properties-cookie <name> |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 1204 | Sets the client cookie's name used for the detection if the DeviceAtlas |
| 1205 | Client-side component was used during the request. This directive is optional |
| 1206 | and set to DAPROPS by default if not set. |
David Carlier | 29b3ca3 | 2015-09-25 14:09:21 +0100 | [diff] [blame] | 1207 | |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 1208 | external-check |
Willy Tarreau | d96f112 | 2019-12-03 07:07:36 +0100 | [diff] [blame] | 1209 | Allows the use of an external agent to perform health checks. This is |
| 1210 | disabled by default as a security precaution, and even when enabled, checks |
Willy Tarreau | a45a8b5 | 2019-12-06 16:31:45 +0100 | [diff] [blame] | 1211 | may still fail unless "insecure-fork-wanted" is enabled as well. If the |
| 1212 | program launched makes use of a setuid executable (it should really not), |
| 1213 | you may also need to set "insecure-setuid-wanted" in the global section. |
| 1214 | See "option external-check", and "insecure-fork-wanted", and |
| 1215 | "insecure-setuid-wanted". |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 1216 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1217 | gid <number> |
Thayne McCombs | cdbcca9 | 2021-01-07 21:24:41 -0700 | [diff] [blame] | 1218 | Changes the process's group ID to <number>. It is recommended that the group |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1219 | ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 1220 | 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] | 1221 | Note that if haproxy is started from a user having supplementary groups, it |
| 1222 | 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] | 1223 | See also "group" and "uid". |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 1224 | |
Willy Tarreau | 11770ce | 2019-12-03 08:29:22 +0100 | [diff] [blame] | 1225 | group <group name> |
| 1226 | Similar to "gid" but uses the GID of group name <group name> from /etc/group. |
| 1227 | See also "gid" and "user". |
| 1228 | |
Cyril Bonté | 203ec5a | 2017-03-23 22:44:13 +0100 | [diff] [blame] | 1229 | hard-stop-after <time> |
| 1230 | Defines the maximum time allowed to perform a clean soft-stop. |
| 1231 | |
| 1232 | Arguments : |
| 1233 | <time> is the maximum time (by default in milliseconds) for which the |
| 1234 | instance will remain alive when a soft-stop is received via the |
| 1235 | SIGUSR1 signal. |
| 1236 | |
| 1237 | This may be used to ensure that the instance will quit even if connections |
| 1238 | remain opened during a soft-stop (for example with long timeouts for a proxy |
| 1239 | in tcp mode). It applies both in TCP and HTTP mode. |
| 1240 | |
| 1241 | Example: |
| 1242 | global |
| 1243 | hard-stop-after 30s |
| 1244 | |
Christopher Faulet | 98fbe95 | 2019-07-22 16:18:24 +0200 | [diff] [blame] | 1245 | h1-case-adjust <from> <to> |
| 1246 | Defines the case adjustment to apply, when enabled, to the header name |
| 1247 | <from>, to change it to <to> before sending it to HTTP/1 clients or |
| 1248 | servers. <from> must be in lower case, and <from> and <to> must not differ |
| 1249 | except for their case. It may be repeated if several header names need to be |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 1250 | adjusted. Duplicate entries are not allowed. If a lot of header names have to |
Christopher Faulet | 98fbe95 | 2019-07-22 16:18:24 +0200 | [diff] [blame] | 1251 | be adjusted, it might be more convenient to use "h1-case-adjust-file". |
| 1252 | Please note that no transformation will be applied unless "option |
| 1253 | h1-case-adjust-bogus-client" or "option h1-case-adjust-bogus-server" is |
| 1254 | specified in a proxy. |
| 1255 | |
| 1256 | There is no standard case for header names because, as stated in RFC7230, |
| 1257 | they are case-insensitive. So applications must handle them in a case- |
| 1258 | insensitive manner. But some bogus applications violate the standards and |
| 1259 | erroneously rely on the cases most commonly used by browsers. This problem |
| 1260 | becomes critical with HTTP/2 because all header names must be exchanged in |
| 1261 | lower case, and HAProxy follows the same convention. All header names are |
| 1262 | sent in lower case to clients and servers, regardless of the HTTP version. |
| 1263 | |
| 1264 | Applications which fail to properly process requests or responses may require |
| 1265 | to temporarily use such workarounds to adjust header names sent to them for |
| 1266 | the time it takes the application to be fixed. Please note that an |
| 1267 | application which requires such workarounds might be vulnerable to content |
| 1268 | smuggling attacks and must absolutely be fixed. |
| 1269 | |
| 1270 | Example: |
| 1271 | global |
| 1272 | h1-case-adjust content-length Content-Length |
| 1273 | |
| 1274 | See "h1-case-adjust-file", "option h1-case-adjust-bogus-client" and |
| 1275 | "option h1-case-adjust-bogus-server". |
| 1276 | |
| 1277 | h1-case-adjust-file <hdrs-file> |
| 1278 | Defines a file containing a list of key/value pairs used to adjust the case |
| 1279 | of some header names before sending them to HTTP/1 clients or servers. The |
| 1280 | file <hdrs-file> must contain 2 header names per line. The first one must be |
| 1281 | in lower case and both must not differ except for their case. Lines which |
| 1282 | start with '#' are ignored, just like empty lines. Leading and trailing tabs |
| 1283 | and spaces are stripped. Duplicate entries are not allowed. Please note that |
| 1284 | no transformation will be applied unless "option h1-case-adjust-bogus-client" |
| 1285 | or "option h1-case-adjust-bogus-server" is specified in a proxy. |
| 1286 | |
| 1287 | If this directive is repeated, only the last one will be processed. It is an |
| 1288 | alternative to the directive "h1-case-adjust" if a lot of header names need |
| 1289 | to be adjusted. Please read the risks associated with using this. |
| 1290 | |
| 1291 | See "h1-case-adjust", "option h1-case-adjust-bogus-client" and |
| 1292 | "option h1-case-adjust-bogus-server". |
| 1293 | |
Willy Tarreau | d96f112 | 2019-12-03 07:07:36 +0100 | [diff] [blame] | 1294 | insecure-fork-wanted |
| 1295 | By default haproxy tries hard to prevent any thread and process creation |
| 1296 | after it starts. Doing so is particularly important when using Lua files of |
| 1297 | uncertain origin, and when experimenting with development versions which may |
| 1298 | still contain bugs whose exploitability is uncertain. And generally speaking |
| 1299 | it's good hygiene to make sure that no unexpected background activity can be |
| 1300 | triggered by traffic. But this prevents external checks from working, and may |
| 1301 | break some very specific Lua scripts which actively rely on the ability to |
| 1302 | fork. This option is there to disable this protection. Note that it is a bad |
| 1303 | idea to disable it, as a vulnerability in a library or within haproxy itself |
| 1304 | will be easier to exploit once disabled. In addition, forking from Lua or |
| 1305 | anywhere else is not reliable as the forked process may randomly embed a lock |
| 1306 | set by another thread and never manage to finish an operation. As such it is |
| 1307 | highly recommended that this option is never used and that any workload |
| 1308 | requiring such a fork be reconsidered and moved to a safer solution (such as |
| 1309 | agents instead of external checks). This option supports the "no" prefix to |
| 1310 | disable it. |
| 1311 | |
Willy Tarreau | a45a8b5 | 2019-12-06 16:31:45 +0100 | [diff] [blame] | 1312 | insecure-setuid-wanted |
| 1313 | HAProxy doesn't need to call executables at run time (except when using |
| 1314 | external checks which are strongly recommended against), and is even expected |
| 1315 | to isolate itself into an empty chroot. As such, there basically is no valid |
| 1316 | reason to allow a setuid executable to be called without the user being fully |
| 1317 | aware of the risks. In a situation where haproxy would need to call external |
| 1318 | checks and/or disable chroot, exploiting a vulnerability in a library or in |
| 1319 | haproxy itself could lead to the execution of an external program. On Linux |
| 1320 | it is possible to lock the process so that any setuid bit present on such an |
| 1321 | executable is ignored. This significantly reduces the risk of privilege |
| 1322 | escalation in such a situation. This is what haproxy does by default. In case |
| 1323 | this causes a problem to an external check (for example one which would need |
| 1324 | the "ping" command), then it is possible to disable this protection by |
| 1325 | explicitly adding this directive in the global section. If enabled, it is |
| 1326 | possible to turn it back off by prefixing it with the "no" keyword. |
| 1327 | |
Emmanuel Hocdet | 70df7bf | 2019-01-04 11:08:20 +0100 | [diff] [blame] | 1328 | issuers-chain-path <dir> |
| 1329 | Assigns a directory to load certificate chain for issuer completion. All |
| 1330 | files must be in PEM format. For certificates loaded with "crt" or "crt-list", |
| 1331 | if certificate chain is not included in PEM (also commonly known as |
| 1332 | intermediate certificate), haproxy will complete chain if the issuer of the |
| 1333 | certificate corresponds to the first certificate of the chain loaded with |
| 1334 | "issuers-chain-path". |
| 1335 | A "crt" file with PrivateKey+Certificate+IntermediateCA2+IntermediateCA1 |
| 1336 | could be replaced with PrivateKey+Certificate. HAProxy will complete the |
| 1337 | chain if a file with IntermediateCA2+IntermediateCA1 is present in |
| 1338 | "issuers-chain-path" directory. All other certificates with the same issuer |
| 1339 | will share the chain in memory. |
| 1340 | |
Dragan Dosen | 13cd54c | 2020-06-18 18:24:05 +0200 | [diff] [blame] | 1341 | localpeer <name> |
| 1342 | Sets the local instance's peer name. It will be ignored if the "-L" |
| 1343 | command line argument is specified or if used after "peers" section |
| 1344 | definitions. In such cases, a warning message will be emitted during |
| 1345 | the configuration parsing. |
| 1346 | |
| 1347 | This option will also set the HAPROXY_LOCALPEER environment variable. |
| 1348 | See also "-L" in the management guide and "peers" section below. |
| 1349 | |
Jan Wagner | 3e67860 | 2020-12-17 22:22:32 +0100 | [diff] [blame] | 1350 | log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>] |
Frédéric Lécaille | d690dfa | 2019-04-25 10:52:17 +0200 | [diff] [blame] | 1351 | <facility> [max level [min level]] |
Cyril Bonté | 3e95487 | 2018-03-20 23:30:27 +0100 | [diff] [blame] | 1352 | Adds a global syslog server. Several global servers can be defined. They |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1353 | will receive logs for starts and exits, as well as all logs from proxies |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 1354 | configured with "log global". |
| 1355 | |
| 1356 | <address> can be one of: |
| 1357 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1358 | - 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] | 1359 | no port is specified, 514 is used by default (the standard syslog |
| 1360 | port). |
| 1361 | |
David du Colombier | 24bb5f5 | 2011-03-17 10:40:23 +0100 | [diff] [blame] | 1362 | - An IPv6 address followed by a colon and optionally a UDP port. If |
| 1363 | no port is specified, 514 is used by default (the standard syslog |
| 1364 | port). |
| 1365 | |
Willy Tarreau | 5a32ecc | 2018-11-12 07:34:59 +0100 | [diff] [blame] | 1366 | - A filesystem path to a datagram UNIX domain socket, keeping in mind |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 1367 | considerations for chroot (be sure the path is accessible inside |
| 1368 | the chroot) and uid/gid (be sure the path is appropriately |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1369 | writable). |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 1370 | |
Willy Tarreau | 5a32ecc | 2018-11-12 07:34:59 +0100 | [diff] [blame] | 1371 | - A file descriptor number in the form "fd@<number>", which may point |
| 1372 | to a pipe, terminal, or socket. In this case unbuffered logs are used |
| 1373 | and one writev() call per log is performed. This is a bit expensive |
| 1374 | but acceptable for most workloads. Messages sent this way will not be |
| 1375 | truncated but may be dropped, in which case the DroppedLogs counter |
| 1376 | will be incremented. The writev() call is atomic even on pipes for |
| 1377 | messages up to PIPE_BUF size, which POSIX recommends to be at least |
| 1378 | 512 and which is 4096 bytes on most modern operating systems. Any |
| 1379 | larger message may be interleaved with messages from other processes. |
| 1380 | Exceptionally for debugging purposes the file descriptor may also be |
| 1381 | directed to a file, but doing so will significantly slow haproxy down |
| 1382 | as non-blocking calls will be ignored. Also there will be no way to |
| 1383 | purge nor rotate this file without restarting the process. Note that |
| 1384 | the configured syslog format is preserved, so the output is suitable |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 1385 | for use with a TCP syslog server. See also the "short" and "raw" |
| 1386 | format below. |
Willy Tarreau | 5a32ecc | 2018-11-12 07:34:59 +0100 | [diff] [blame] | 1387 | |
| 1388 | - "stdout" / "stderr", which are respectively aliases for "fd@1" and |
| 1389 | "fd@2", see above. |
| 1390 | |
Willy Tarreau | c046d16 | 2019-08-30 15:24:59 +0200 | [diff] [blame] | 1391 | - A ring buffer in the form "ring@<name>", which will correspond to an |
| 1392 | in-memory ring buffer accessible over the CLI using the "show events" |
| 1393 | command, which will also list existing rings and their sizes. Such |
| 1394 | buffers are lost on reload or restart but when used as a complement |
| 1395 | this can help troubleshooting by having the logs instantly available. |
| 1396 | |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 1397 | You may want to reference some environment variables in the address |
| 1398 | parameter, see section 2.3 about environment variables. |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 1399 | |
Willy Tarreau | 18324f5 | 2014-06-27 18:10:07 +0200 | [diff] [blame] | 1400 | <length> is an optional maximum line length. Log lines larger than this value |
| 1401 | will be truncated before being sent. The reason is that syslog |
| 1402 | servers act differently on log line length. All servers support the |
| 1403 | default value of 1024, but some servers simply drop larger lines |
| 1404 | while others do log them. If a server supports long lines, it may |
| 1405 | make sense to set this value here in order to avoid truncating long |
| 1406 | lines. Similarly, if a server drops long lines, it is preferable to |
| 1407 | truncate them before sending them. Accepted values are 80 to 65535 |
| 1408 | inclusive. The default value of 1024 is generally fine for all |
| 1409 | standard usages. Some specific cases of long captures or |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1410 | JSON-formatted logs may require larger values. You may also need to |
| 1411 | increase "tune.http.logurilen" if your request URIs are truncated. |
Willy Tarreau | 18324f5 | 2014-06-27 18:10:07 +0200 | [diff] [blame] | 1412 | |
Dragan Dosen | 7ad3154 | 2015-09-28 17:16:47 +0200 | [diff] [blame] | 1413 | <format> is the log format used when generating syslog messages. It may be |
| 1414 | one of the following : |
| 1415 | |
Emeric Brun | 0237c4e | 2020-11-27 16:24:34 +0100 | [diff] [blame] | 1416 | local Analog to rfc3164 syslog message format except that hostname |
| 1417 | field is stripped. This is the default. |
| 1418 | Note: option "log-send-hostname" switches the default to |
| 1419 | rfc3164. |
| 1420 | |
| 1421 | rfc3164 The RFC3164 syslog message format. |
Dragan Dosen | 7ad3154 | 2015-09-28 17:16:47 +0200 | [diff] [blame] | 1422 | (https://tools.ietf.org/html/rfc3164) |
| 1423 | |
| 1424 | rfc5424 The RFC5424 syslog message format. |
| 1425 | (https://tools.ietf.org/html/rfc5424) |
| 1426 | |
Emeric Brun | 5464885 | 2020-07-06 15:54:06 +0200 | [diff] [blame] | 1427 | priority A message containing only a level plus syslog facility between |
| 1428 | angle brackets such as '<63>', followed by the text. The PID, |
| 1429 | date, time, process name and system name are omitted. This is |
| 1430 | designed to be used with a local log server. |
| 1431 | |
Willy Tarreau | e8746a0 | 2018-11-12 08:45:00 +0100 | [diff] [blame] | 1432 | short A message containing only a level between angle brackets such as |
| 1433 | '<3>', followed by the text. The PID, date, time, process name |
| 1434 | and system name are omitted. This is designed to be used with a |
| 1435 | local log server. This format is compatible with what the systemd |
| 1436 | logger consumes. |
| 1437 | |
Emeric Brun | 5464885 | 2020-07-06 15:54:06 +0200 | [diff] [blame] | 1438 | timed A message containing only a level between angle brackets such as |
| 1439 | '<3>', followed by ISO date and by the text. The PID, process |
| 1440 | name and system name are omitted. This is designed to be |
| 1441 | used with a local log server. |
| 1442 | |
| 1443 | iso A message containing only the ISO date, followed by the text. |
| 1444 | The PID, process name and system name are omitted. This is |
| 1445 | designed to be used with a local log server. |
| 1446 | |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 1447 | raw A message containing only the text. The level, PID, date, time, |
| 1448 | process name and system name are omitted. This is designed to be |
| 1449 | used in containers or during development, where the severity only |
| 1450 | depends on the file descriptor used (stdout/stderr). |
| 1451 | |
Frédéric Lécaille | d690dfa | 2019-04-25 10:52:17 +0200 | [diff] [blame] | 1452 | <ranges> A list of comma-separated ranges to identify the logs to sample. |
| 1453 | This is used to balance the load of the logs to send to the log |
| 1454 | server. The limits of the ranges cannot be null. They are numbered |
| 1455 | from 1. The size or period (in number of logs) of the sample must be |
| 1456 | set with <sample_size> parameter. |
| 1457 | |
| 1458 | <sample_size> |
| 1459 | The size of the sample in number of logs to consider when balancing |
| 1460 | their logging loads. It is used to balance the load of the logs to |
| 1461 | send to the syslog server. This size must be greater or equal to the |
| 1462 | maximum of the high limits of the ranges. |
| 1463 | (see also <ranges> parameter). |
| 1464 | |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 1465 | <facility> must be one of the 24 standard syslog facilities : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1466 | |
Willy Tarreau | e8746a0 | 2018-11-12 08:45:00 +0100 | [diff] [blame] | 1467 | kern user mail daemon auth syslog lpr news |
| 1468 | uucp cron auth2 ftp ntp audit alert cron2 |
| 1469 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 1470 | |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 1471 | Note that the facility is ignored for the "short" and "raw" |
| 1472 | formats, but still required as a positional field. It is |
| 1473 | recommended to use "daemon" in this case to make it clear that |
| 1474 | it's only supposed to be used locally. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1475 | |
| 1476 | An optional level can be specified to filter outgoing messages. By default, |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 1477 | all messages are sent. If a maximum level is specified, only messages with a |
| 1478 | severity at least as important as this level will be sent. An optional minimum |
| 1479 | level can be specified. If it is set, logs emitted with a more severe level |
| 1480 | than this one will be capped to this level. This is used to avoid sending |
| 1481 | "emerg" messages on all terminals on some default syslog configurations. |
| 1482 | Eight levels are known : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1483 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 1484 | emerg alert crit err warning notice info debug |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1485 | |
Joe Williams | df5b38f | 2010-12-29 17:05:48 +0100 | [diff] [blame] | 1486 | log-send-hostname [<string>] |
| 1487 | Sets the hostname field in the syslog header. If optional "string" parameter |
| 1488 | is set the header is set to the string contents, otherwise uses the hostname |
| 1489 | of the system. Generally used if one is not relaying logs through an |
| 1490 | intermediate syslog server or for simply customizing the hostname printed in |
| 1491 | the logs. |
| 1492 | |
Kevinm | 48936af | 2010-12-22 16:08:21 +0000 | [diff] [blame] | 1493 | log-tag <string> |
| 1494 | Sets the tag field in the syslog header to this string. It defaults to the |
| 1495 | program name as launched from the command line, which usually is "haproxy". |
| 1496 | Sometimes it can be useful to differentiate between multiple processes |
Willy Tarreau | 094af4e | 2015-01-07 15:03:42 +0100 | [diff] [blame] | 1497 | running on the same host. See also the per-proxy "log-tag" directive. |
Kevinm | 48936af | 2010-12-22 16:08:21 +0000 | [diff] [blame] | 1498 | |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 1499 | lua-load <file> |
Thierry Fournier | 59f11be | 2020-11-29 00:37:41 +0100 | [diff] [blame] | 1500 | This global directive loads and executes a Lua file in the shared context |
| 1501 | that is visible to all threads. Any variable set in such a context is visible |
| 1502 | from any thread. This is the easiest and recommended way to load Lua programs |
| 1503 | but it will not scale well if a lot of Lua calls are performed, as only one |
| 1504 | thread may be running on the global state at a time. A program loaded this |
| 1505 | way will always see 0 in the "core.thread" variable. This directive can be |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 1506 | used multiple times. |
| 1507 | |
Thierry Fournier | 59f11be | 2020-11-29 00:37:41 +0100 | [diff] [blame] | 1508 | lua-load-per-thread <file> |
| 1509 | This global directive loads and executes a Lua file into each started thread. |
| 1510 | Any global variable has a thread-local visibility so that each thread could |
| 1511 | see a different value. As such it is strongly recommended not to use global |
| 1512 | variables in programs loaded this way. An independent copy is loaded and |
| 1513 | initialized for each thread, everything is done sequentially and in the |
| 1514 | thread's numeric order from 1 to nbthread. If some operations need to be |
| 1515 | performed only once, the program should check the "core.thread" variable to |
| 1516 | figure what thread is being initialized. Programs loaded this way will run |
| 1517 | concurrently on all threads and will be highly scalable. This is the |
| 1518 | recommended way to load simple functions that register sample-fetches, |
| 1519 | converters, actions or services once it is certain the program doesn't depend |
| 1520 | on global variables. For the sake of simplicity, the directive is available |
| 1521 | even if only one thread is used and even if threads are disabled (in which |
| 1522 | case it will be equivalent to lua-load). This directive can be used multiple |
| 1523 | times. |
| 1524 | |
Tim Duesterhus | dd74b5f | 2020-01-12 13:55:40 +0100 | [diff] [blame] | 1525 | lua-prepend-path <string> [<type>] |
| 1526 | Prepends the given string followed by a semicolon to Lua's package.<type> |
| 1527 | variable. |
| 1528 | <type> must either be "path" or "cpath". If <type> is not given it defaults |
| 1529 | to "path". |
| 1530 | |
| 1531 | Lua's paths are semicolon delimited lists of patterns that specify how the |
| 1532 | `require` function attempts to find the source file of a library. Question |
| 1533 | marks (?) within a pattern will be replaced by module name. The path is |
| 1534 | evaluated left to right. This implies that paths that are prepended later |
| 1535 | will be checked earlier. |
| 1536 | |
| 1537 | As an example by specifying the following path: |
| 1538 | |
| 1539 | lua-prepend-path /usr/share/haproxy-lua/?/init.lua |
| 1540 | lua-prepend-path /usr/share/haproxy-lua/?.lua |
| 1541 | |
| 1542 | When `require "example"` is being called Lua will first attempt to load the |
| 1543 | /usr/share/haproxy-lua/example.lua script, if that does not exist the |
| 1544 | /usr/share/haproxy-lua/example/init.lua will be attempted and the default |
| 1545 | paths if that does not exist either. |
| 1546 | |
| 1547 | See https://www.lua.org/pil/8.1.html for the details within the Lua |
| 1548 | documentation. |
| 1549 | |
William Lallemand | 4cfede8 | 2017-11-24 22:02:34 +0100 | [diff] [blame] | 1550 | master-worker [no-exit-on-failure] |
William Lallemand | e202b1e | 2017-06-01 17:38:56 +0200 | [diff] [blame] | 1551 | Master-worker mode. It is equivalent to the command line "-W" argument. |
| 1552 | This mode will launch a "master" which will monitor the "workers". Using |
| 1553 | this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1554 | the master. The master-worker mode is compatible either with the foreground |
William Lallemand | e202b1e | 2017-06-01 17:38:56 +0200 | [diff] [blame] | 1555 | or daemon mode. It is recommended to use this mode with multiprocess and |
| 1556 | systemd. |
William Lallemand | 4cfede8 | 2017-11-24 22:02:34 +0100 | [diff] [blame] | 1557 | By default, if a worker exits with a bad return code, in the case of a |
| 1558 | segfault for example, all workers will be killed, and the master will leave. |
| 1559 | It is convenient to combine this behavior with Restart=on-failure in a |
| 1560 | systemd unit file in order to relaunch the whole process. If you don't want |
| 1561 | this behavior, you must use the keyword "no-exit-on-failure". |
William Lallemand | e202b1e | 2017-06-01 17:38:56 +0200 | [diff] [blame] | 1562 | |
William Lallemand | 4cfede8 | 2017-11-24 22:02:34 +0100 | [diff] [blame] | 1563 | See also "-W" in the management guide. |
William Lallemand | e202b1e | 2017-06-01 17:38:56 +0200 | [diff] [blame] | 1564 | |
William Lallemand | 27edc4b | 2019-05-07 17:49:33 +0200 | [diff] [blame] | 1565 | mworker-max-reloads <number> |
| 1566 | In master-worker mode, this option limits the number of time a worker can |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 1567 | survive to a reload. If the worker did not leave after a reload, once its |
William Lallemand | 27edc4b | 2019-05-07 17:49:33 +0200 | [diff] [blame] | 1568 | number of reloads is greater than this number, the worker will receive a |
| 1569 | SIGTERM. This option helps to keep under control the number of workers. |
| 1570 | See also "show proc" in the Management Guide. |
| 1571 | |
Willy Tarreau | f42d794 | 2020-10-20 11:54:49 +0200 | [diff] [blame] | 1572 | nbproc <number> (deprecated) |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1573 | Creates <number> processes when going daemon. This requires the "daemon" |
| 1574 | mode. By default, only one process is created, which is the recommended mode |
| 1575 | of operation. For systems limited to small sets of file descriptors per |
Willy Tarreau | 149ab77 | 2019-01-26 14:27:06 +0100 | [diff] [blame] | 1576 | process, it may be needed to fork multiple daemons. When set to a value |
| 1577 | larger than 1, threads are automatically disabled. USING MULTIPLE PROCESSES |
Willy Tarreau | f42d794 | 2020-10-20 11:54:49 +0200 | [diff] [blame] | 1578 | IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. This directive is deprecated |
| 1579 | and scheduled for removal in 2.5. Please use "nbthread" instead. See also |
| 1580 | "daemon" and "nbthread". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1581 | |
Christopher Faulet | be0faa2 | 2017-08-29 15:37:10 +0200 | [diff] [blame] | 1582 | nbthread <number> |
| 1583 | This setting is only available when support for threads was built in. It |
Willy Tarreau | 26f6ae1 | 2019-02-02 12:56:15 +0100 | [diff] [blame] | 1584 | makes haproxy run on <number> threads. This is exclusive with "nbproc". While |
| 1585 | "nbproc" historically used to be the only way to use multiple processors, it |
| 1586 | also involved a number of shortcomings related to the lack of synchronization |
| 1587 | between processes (health-checks, peers, stick-tables, stats, ...) which do |
| 1588 | not affect threads. As such, any modern configuration is strongly encouraged |
Willy Tarreau | 149ab77 | 2019-01-26 14:27:06 +0100 | [diff] [blame] | 1589 | to migrate away from "nbproc" to "nbthread". "nbthread" also works when |
| 1590 | HAProxy is started in foreground. On some platforms supporting CPU affinity, |
| 1591 | when nbproc is not used, the default "nbthread" value is automatically set to |
| 1592 | the number of CPUs the process is bound to upon startup. This means that the |
| 1593 | thread count can easily be adjusted from the calling process using commands |
| 1594 | like "taskset" or "cpuset". Otherwise, this value defaults to 1. The default |
| 1595 | value is reported in the output of "haproxy -vv". See also "nbproc". |
Christopher Faulet | be0faa2 | 2017-08-29 15:37:10 +0200 | [diff] [blame] | 1596 | |
Amaury Denoyelle | 0f50cb9 | 2021-03-26 18:50:33 +0100 | [diff] [blame] | 1597 | numa-cpu-mapping |
| 1598 | By default, if running on Linux, haproxy inspects on startup the CPU topology |
| 1599 | of the machine. If a multi-socket machine is detected, the affinity is |
| 1600 | automatically calculated to run on the CPUs of a single node. This is done in |
| 1601 | order to not suffer from the performance penalties caused by the inter-socket |
| 1602 | bus latency. However, if the applied binding is non optimal on a particular |
| 1603 | architecture, it can be disabled with the statement 'no numa-cpu-mapping'. |
| 1604 | This automatic binding is also not applied if a nbthread statement is present |
| 1605 | in the configuration, or the affinity of the process is already specified, |
| 1606 | for example via the 'cpu-map' directive or the taskset utility. |
| 1607 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1608 | pidfile <pidfile> |
MIZUTA Takeshi | c32f394 | 2020-08-26 13:46:19 +0900 | [diff] [blame] | 1609 | Writes PIDs of all daemons into file <pidfile> when daemon mode or writes PID |
| 1610 | of master process into file <pidfile> when master-worker mode. This option is |
| 1611 | equivalent to the "-p" command line argument. The file must be accessible to |
| 1612 | the user starting the process. See also "daemon" and "master-worker". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1613 | |
Willy Tarreau | 119e50e | 2020-05-22 13:53:29 +0200 | [diff] [blame] | 1614 | pp2-never-send-local |
| 1615 | A bug in the PROXY protocol v2 implementation was present in HAProxy up to |
| 1616 | version 2.1, causing it to emit a PROXY command instead of a LOCAL command |
| 1617 | for health checks. This is particularly minor but confuses some servers' |
| 1618 | logs. Sadly, the bug was discovered very late and revealed that some servers |
| 1619 | which possibly only tested their PROXY protocol implementation against |
| 1620 | HAProxy fail to properly handle the LOCAL command, and permanently remain in |
| 1621 | the "down" state when HAProxy checks them. When this happens, it is possible |
| 1622 | to enable this global option to revert to the older (bogus) behavior for the |
| 1623 | time it takes to contact the affected components' vendors and get them fixed. |
| 1624 | This option is disabled by default and acts on all servers having the |
| 1625 | "send-proxy-v2" statement. |
| 1626 | |
Willy Tarreau | 1d54972 | 2016-02-16 12:41:57 +0100 | [diff] [blame] | 1627 | presetenv <name> <value> |
| 1628 | Sets environment variable <name> to value <value>. If the variable exists, it |
| 1629 | is NOT overwritten. The changes immediately take effect so that the next line |
| 1630 | in the configuration file sees the new value. See also "setenv", "resetenv", |
| 1631 | and "unsetenv". |
| 1632 | |
| 1633 | resetenv [<name> ...] |
| 1634 | Removes all environment variables except the ones specified in argument. It |
| 1635 | allows to use a clean controlled environment before setting new values with |
| 1636 | setenv or unsetenv. Please note that some internal functions may make use of |
| 1637 | some environment variables, such as time manipulation functions, but also |
| 1638 | OpenSSL or even external checks. This must be used with extreme care and only |
| 1639 | after complete validation. The changes immediately take effect so that the |
| 1640 | next line in the configuration file sees the new environment. See also |
| 1641 | "setenv", "presetenv", and "unsetenv". |
| 1642 | |
Christopher Faulet | ff4121f | 2017-11-22 16:38:49 +0100 | [diff] [blame] | 1643 | stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ... |
Willy Tarreau | 35b7b16 | 2012-10-22 23:17:18 +0200 | [diff] [blame] | 1644 | Limits the stats socket to a certain set of processes numbers. By default the |
| 1645 | stats socket is bound to all processes, causing a warning to be emitted when |
| 1646 | nbproc is greater than 1 because there is no way to select the target process |
| 1647 | when connecting. However, by using this setting, it becomes possible to pin |
| 1648 | the stats socket to a specific set of processes, typically the first one. The |
| 1649 | warning will automatically be disabled when this setting is used, whatever |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 1650 | the number of processes used. The maximum process ID depends on the machine's |
Christopher Faulet | ff4121f | 2017-11-22 16:38:49 +0100 | [diff] [blame] | 1651 | word size (32 or 64). Ranges can be partially defined. The higher bound can |
| 1652 | be omitted. In such case, it is replaced by the corresponding maximum |
| 1653 | value. A better option consists in using the "process" setting of the "stats |
| 1654 | socket" line to force the process on each line. |
Willy Tarreau | 35b7b16 | 2012-10-22 23:17:18 +0200 | [diff] [blame] | 1655 | |
Baptiste Assmann | 5626f48 | 2015-08-23 10:00:10 +0200 | [diff] [blame] | 1656 | server-state-base <directory> |
| 1657 | Specifies the directory prefix to be prepended in front of all servers state |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 1658 | file names which do not start with a '/'. See also "server-state-file", |
| 1659 | "load-server-state-from-file" and "server-state-file-name". |
Baptiste Assmann | ef1f0fc | 2015-08-23 10:06:39 +0200 | [diff] [blame] | 1660 | |
| 1661 | server-state-file <file> |
| 1662 | Specifies the path to the file containing state of servers. If the path starts |
| 1663 | with a slash ('/'), it is considered absolute, otherwise it is considered |
| 1664 | relative to the directory specified using "server-state-base" (if set) or to |
| 1665 | the current directory. Before reloading HAProxy, it is possible to save the |
| 1666 | servers' current state using the stats command "show servers state". The |
| 1667 | output of this command must be written in the file pointed by <file>. When |
| 1668 | starting up, before handling traffic, HAProxy will read, load and apply state |
| 1669 | for each server found in the file and available in its current running |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 1670 | configuration. See also "server-state-base" and "show servers state", |
| 1671 | "load-server-state-from-file" and "server-state-file-name" |
Baptiste Assmann | 5626f48 | 2015-08-23 10:00:10 +0200 | [diff] [blame] | 1672 | |
Willy Tarreau | 13d2ba2 | 2021-03-26 11:38:08 +0100 | [diff] [blame] | 1673 | set-var <var-name> <expr> |
| 1674 | Sets the process-wide variable '<var-name>' to the result of the evaluation |
| 1675 | of the sample expression <expr>. The variable '<var-name>' may only be a |
| 1676 | process-wide variable (using the 'proc.' prefix). It works exactly like the |
| 1677 | 'set-var' action in TCP or HTTP rules except that the expression is evaluated |
| 1678 | at configuration parsing time and that the variable is instantly set. The |
| 1679 | sample fetch functions and converters permitted in the expression are only |
| 1680 | those using internal data, typically 'int(value)' or 'str(value)'. It's is |
| 1681 | possible to reference previously allocated variables as well. These variables |
| 1682 | will then be readable (and modifiable) from the regular rule sets. |
| 1683 | |
| 1684 | Example: |
| 1685 | global |
| 1686 | set-var proc.current_state str(primary) |
| 1687 | set-var proc.prio int(100) |
| 1688 | set-var proc.threshold int(200),sub(proc.prio) |
| 1689 | |
Willy Tarreau | 1d54972 | 2016-02-16 12:41:57 +0100 | [diff] [blame] | 1690 | setenv <name> <value> |
| 1691 | Sets environment variable <name> to value <value>. If the variable exists, it |
| 1692 | is overwritten. The changes immediately take effect so that the next line in |
| 1693 | the configuration file sees the new value. See also "presetenv", "resetenv", |
| 1694 | and "unsetenv". |
| 1695 | |
Willy Tarreau | 636848a | 2019-04-15 19:38:50 +0200 | [diff] [blame] | 1696 | set-dumpable |
| 1697 | This option is better left disabled by default and enabled only upon a |
William Dauchy | ec73098 | 2019-10-27 20:08:10 +0100 | [diff] [blame] | 1698 | developer's request. If it has been enabled, it may still be forcibly |
| 1699 | disabled by prefixing it with the "no" keyword. It has no impact on |
| 1700 | performance nor stability but will try hard to re-enable core dumps that were |
| 1701 | possibly disabled by file size limitations (ulimit -f), core size limitations |
| 1702 | (ulimit -c), or "dumpability" of a process after changing its UID/GID (such |
| 1703 | as /proc/sys/fs/suid_dumpable on Linux). Core dumps might still be limited by |
| 1704 | the current directory's permissions (check what directory the file is started |
| 1705 | from), the chroot directory's permission (it may be needed to temporarily |
| 1706 | disable the chroot directive or to move it to a dedicated writable location), |
| 1707 | or any other system-specific constraint. For example, some Linux flavours are |
| 1708 | notorious for replacing the default core file with a path to an executable |
| 1709 | not even installed on the system (check /proc/sys/kernel/core_pattern). Often, |
| 1710 | simply writing "core", "core.%p" or "/var/log/core/core.%p" addresses the |
| 1711 | issue. When trying to enable this option waiting for a rare issue to |
| 1712 | re-appear, it's often a good idea to first try to obtain such a dump by |
| 1713 | issuing, for example, "kill -11" to the haproxy process and verify that it |
| 1714 | leaves a core where expected when dying. |
Willy Tarreau | 636848a | 2019-04-15 19:38:50 +0200 | [diff] [blame] | 1715 | |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 1716 | ssl-default-bind-ciphers <ciphers> |
| 1717 | This setting is only available when support for OpenSSL was built in. It sets |
| 1718 | the default string describing the list of cipher algorithms ("cipher suite") |
Bertrand Jacquin | 8cf7c1e | 2019-02-03 18:35:25 +0000 | [diff] [blame] | 1719 | that are negotiated during the SSL/TLS handshake up to TLSv1.2 for all |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 1720 | "bind" lines which do not explicitly define theirs. The format of the string |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 1721 | is defined in "man 1 ciphers" from OpenSSL man pages. For background |
| 1722 | information and recommendations see e.g. |
| 1723 | (https://wiki.mozilla.org/Security/Server_Side_TLS) and |
| 1724 | (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3 |
| 1725 | cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword. |
| 1726 | Please check the "bind" keyword for more information. |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 1727 | |
| 1728 | ssl-default-bind-ciphersuites <ciphersuites> |
| 1729 | This setting is only available when support for OpenSSL was built in and |
| 1730 | OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string |
| 1731 | describing the list of cipher algorithms ("cipher suite") that are negotiated |
| 1732 | during the TLSv1.3 handshake for all "bind" lines which do not explicitly define |
| 1733 | theirs. The format of the string is defined in |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 1734 | "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For |
| 1735 | cipher configuration for TLSv1.2 and earlier, please check the |
| 1736 | "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 1737 | information. |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 1738 | |
Jerome Magnin | b203ff6 | 2020-04-03 15:28:22 +0200 | [diff] [blame] | 1739 | ssl-default-bind-curves <curves> |
| 1740 | This setting is only available when support for OpenSSL was built in. It sets |
| 1741 | the default string describing the list of elliptic curves algorithms ("curve |
| 1742 | suite") that are negotiated during the SSL/TLS handshake with ECDHE. The format |
| 1743 | of the string is a colon-delimited list of curve name. |
| 1744 | Please check the "bind" keyword for more information. |
| 1745 | |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 1746 | ssl-default-bind-options [<option>]... |
| 1747 | This setting is only available when support for OpenSSL was built in. It sets |
| 1748 | default ssl-options to force on all "bind" lines. Please check the "bind" |
| 1749 | keyword to see available options. |
| 1750 | |
| 1751 | Example: |
| 1752 | global |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 1753 | ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 1754 | |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 1755 | ssl-default-server-ciphers <ciphers> |
| 1756 | This setting is only available when support for OpenSSL was built in. It |
| 1757 | sets the default string describing the list of cipher algorithms that are |
Bertrand Jacquin | 8cf7c1e | 2019-02-03 18:35:25 +0000 | [diff] [blame] | 1758 | negotiated during the SSL/TLS handshake up to TLSv1.2 with the server, |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 1759 | for all "server" lines which do not explicitly define theirs. The format of |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 1760 | the string is defined in "man 1 ciphers" from OpenSSL man pages. For background |
| 1761 | information and recommendations see e.g. |
| 1762 | (https://wiki.mozilla.org/Security/Server_Side_TLS) and |
| 1763 | (https://mozilla.github.io/server-side-tls/ssl-config-generator/). |
| 1764 | For TLSv1.3 cipher configuration, please check the |
| 1765 | "ssl-default-server-ciphersuites" keyword. Please check the "server" keyword |
| 1766 | for more information. |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 1767 | |
| 1768 | ssl-default-server-ciphersuites <ciphersuites> |
| 1769 | This setting is only available when support for OpenSSL was built in and |
| 1770 | OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default |
| 1771 | string describing the list of cipher algorithms that are negotiated during |
| 1772 | the TLSv1.3 handshake with the server, for all "server" lines which do not |
| 1773 | explicitly define theirs. The format of the string is defined in |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 1774 | "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For |
| 1775 | cipher configuration for TLSv1.2 and earlier, please check the |
| 1776 | "ssl-default-server-ciphers" keyword. Please check the "server" keyword for |
| 1777 | more information. |
Willy Tarreau | 610f04b | 2014-02-13 11:36:41 +0100 | [diff] [blame] | 1778 | |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 1779 | ssl-default-server-options [<option>]... |
| 1780 | This setting is only available when support for OpenSSL was built in. It sets |
| 1781 | default ssl-options to force on all "server" lines. Please check the "server" |
| 1782 | keyword to see available options. |
| 1783 | |
Remi Gacogne | 47783ef | 2015-05-29 15:53:22 +0200 | [diff] [blame] | 1784 | ssl-dh-param-file <file> |
| 1785 | This setting is only available when support for OpenSSL was built in. It sets |
| 1786 | the default DH parameters that are used during the SSL/TLS handshake when |
| 1787 | ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1788 | which do not explicitly define theirs. It will be overridden by custom DH |
Remi Gacogne | 47783ef | 2015-05-29 15:53:22 +0200 | [diff] [blame] | 1789 | parameters found in a bind certificate file if any. If custom DH parameters |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 1790 | are not specified either by using ssl-dh-param-file or by setting them |
| 1791 | directly in the certificate file, pre-generated DH parameters of the size |
| 1792 | specified by tune.ssl.default-dh-param will be used. Custom parameters are |
| 1793 | known to be more secure and therefore their use is recommended. |
Remi Gacogne | 47783ef | 2015-05-29 15:53:22 +0200 | [diff] [blame] | 1794 | Custom DH parameters may be generated by using the OpenSSL command |
| 1795 | "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH |
| 1796 | parameters should not be considered secure anymore. |
| 1797 | |
William Lallemand | 8e8581e | 2020-10-20 17:36:46 +0200 | [diff] [blame] | 1798 | ssl-load-extra-del-ext |
| 1799 | This setting allows to configure the way HAProxy does the lookup for the |
| 1800 | extra SSL files. By default HAProxy adds a new extension to the filename. |
William Lallemand | 089c138 | 2020-10-23 17:35:12 +0200 | [diff] [blame] | 1801 | (ex: with "foobar.crt" load "foobar.crt.key"). With this option enabled, |
William Lallemand | 8e8581e | 2020-10-20 17:36:46 +0200 | [diff] [blame] | 1802 | HAProxy removes the extension before adding the new one (ex: with |
William Lallemand | 089c138 | 2020-10-23 17:35:12 +0200 | [diff] [blame] | 1803 | "foobar.crt" load "foobar.key"). |
| 1804 | |
| 1805 | Your crt file must have a ".crt" extension for this option to work. |
William Lallemand | 8e8581e | 2020-10-20 17:36:46 +0200 | [diff] [blame] | 1806 | |
| 1807 | This option is not compatible with bundle extensions (.ecdsa, .rsa. .dsa) |
| 1808 | and won't try to remove them. |
| 1809 | |
| 1810 | This option is disabled by default. See also "ssl-load-extra-files". |
| 1811 | |
William Lallemand | 4c5adbf | 2020-02-24 14:23:22 +0100 | [diff] [blame] | 1812 | ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>* |
William Lallemand | 3af48e7 | 2020-02-03 17:15:52 +0100 | [diff] [blame] | 1813 | This setting alters the way HAProxy will look for unspecified files during |
Jerome Magnin | 587be9c | 2020-09-07 11:55:57 +0200 | [diff] [blame] | 1814 | the loading of the SSL certificates associated to "bind" lines. It does not |
| 1815 | apply to certificates used for client authentication on "server" lines. |
William Lallemand | 3af48e7 | 2020-02-03 17:15:52 +0100 | [diff] [blame] | 1816 | |
| 1817 | By default, HAProxy discovers automatically a lot of files not specified in |
| 1818 | the configuration, and you may want to disable this behavior if you want to |
| 1819 | optimize the startup time. |
| 1820 | |
| 1821 | "none": Only load the files specified in the configuration. Don't try to load |
| 1822 | a certificate bundle if the file does not exist. In the case of a directory, |
| 1823 | it won't try to bundle the certificates if they have the same basename. |
| 1824 | |
| 1825 | "all": This is the default behavior, it will try to load everything, |
William Lallemand | 4c5adbf | 2020-02-24 14:23:22 +0100 | [diff] [blame] | 1826 | bundles, sctl, ocsp, issuer, key. |
William Lallemand | 3af48e7 | 2020-02-03 17:15:52 +0100 | [diff] [blame] | 1827 | |
| 1828 | "bundle": When a file specified in the configuration does not exist, HAProxy |
William Lallemand | f9ff3ec | 2020-10-02 17:57:44 +0200 | [diff] [blame] | 1829 | will try to load a "cert bundle". |
| 1830 | |
| 1831 | Starting from HAProxy 2.3, the bundles are not loaded in the same OpenSSL |
| 1832 | certificate store, instead it will loads each certificate in a separate |
| 1833 | store which is equivalent to declaring multiple "crt". OpenSSL 1.1.1 is |
| 1834 | required to achieve this. Which means that bundles are now used only for |
| 1835 | backward compatibility and are not mandatory anymore to do an hybrid RSA/ECC |
| 1836 | bind configuration.. |
| 1837 | |
| 1838 | To associate these PEM files into a "cert bundle" that is recognized by |
| 1839 | haproxy, they must be named in the following way: All PEM files that are to |
| 1840 | be bundled must have the same base name, with a suffix indicating the key |
| 1841 | type. Currently, three suffixes are supported: rsa, dsa and ecdsa. For |
| 1842 | example, if www.example.com has two PEM files, an RSA file and an ECDSA |
| 1843 | file, they must be named: "example.pem.rsa" and "example.pem.ecdsa". The |
| 1844 | first part of the filename is arbitrary; only the suffix matters. To load |
| 1845 | this bundle into haproxy, specify the base name only: |
| 1846 | |
| 1847 | Example : bind :8443 ssl crt example.pem |
| 1848 | |
| 1849 | Note that the suffix is not given to haproxy; this tells haproxy to look for |
| 1850 | a cert bundle. |
| 1851 | |
| 1852 | HAProxy will load all PEM files in the bundle as if they were configured |
| 1853 | separately in several "crt". |
| 1854 | |
| 1855 | The bundle loading does not have an impact anymore on the directory loading |
| 1856 | since files are loading separately. |
| 1857 | |
| 1858 | On the CLI, bundles are seen as separate files, and the bundle extension is |
| 1859 | required to commit them. |
| 1860 | |
William Dauchy | 57dd6f1 | 2020-10-06 15:22:37 +0200 | [diff] [blame] | 1861 | OCSP files (.ocsp), issuer files (.issuer), Certificate Transparency (.sctl) |
William Lallemand | f9ff3ec | 2020-10-02 17:57:44 +0200 | [diff] [blame] | 1862 | as well as private keys (.key) are supported with multi-cert bundling. |
William Lallemand | 3af48e7 | 2020-02-03 17:15:52 +0100 | [diff] [blame] | 1863 | |
| 1864 | "sctl": Try to load "<basename>.sctl" for each crt keyword. |
| 1865 | |
| 1866 | "ocsp": Try to load "<basename>.ocsp" for each crt keyword. |
| 1867 | |
| 1868 | "issuer": Try to load "<basename>.issuer" if the issuer of the OCSP file is |
| 1869 | not provided in the PEM file. |
| 1870 | |
William Lallemand | 4c5adbf | 2020-02-24 14:23:22 +0100 | [diff] [blame] | 1871 | "key": If the private key was not provided by the PEM file, try to load a |
| 1872 | file "<basename>.key" containing a private key. |
| 1873 | |
William Lallemand | 3af48e7 | 2020-02-03 17:15:52 +0100 | [diff] [blame] | 1874 | The default behavior is "all". |
| 1875 | |
| 1876 | Example: |
| 1877 | ssl-load-extra-files bundle sctl |
| 1878 | ssl-load-extra-files sctl ocsp issuer |
| 1879 | ssl-load-extra-files none |
| 1880 | |
| 1881 | See also: "crt", section 5.1 about bind options. |
| 1882 | |
Emeric Brun | 850efd5 | 2014-01-29 12:24:34 +0100 | [diff] [blame] | 1883 | ssl-server-verify [none|required] |
| 1884 | The default behavior for SSL verify on servers side. If specified to 'none', |
| 1885 | servers certificates are not verified. The default is 'required' except if |
| 1886 | forced using cmdline option '-dV'. |
| 1887 | |
Emmanuel Hocdet | c3b7e74 | 2020-04-22 11:06:19 +0200 | [diff] [blame] | 1888 | ssl-skip-self-issued-ca |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 1889 | Self issued CA, aka x509 root CA, is the anchor for chain validation: as a |
Emmanuel Hocdet | c3b7e74 | 2020-04-22 11:06:19 +0200 | [diff] [blame] | 1890 | server is useless to send it, client must have it. Standard configuration |
| 1891 | need to not include such CA in PEM file. This option allows you to keep such |
| 1892 | CA in PEM file without sending it to the client. Use case is to provide |
| 1893 | issuer for ocsp without the need for '.issuer' file and be able to share it |
| 1894 | with 'issuers-chain-path'. This concerns all certificates without intermediate |
| 1895 | certificates. It's useless for BoringSSL, .issuer is ignored because ocsp |
William Lallemand | 9a1d839 | 2020-08-10 17:28:23 +0200 | [diff] [blame] | 1896 | bits does not need it. Requires at least OpenSSL 1.0.2. |
Emmanuel Hocdet | c3b7e74 | 2020-04-22 11:06:19 +0200 | [diff] [blame] | 1897 | |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 1898 | stats socket [<address:port>|<path>] [param*] |
| 1899 | Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>. |
| 1900 | Connections to this socket will return various statistics outputs and even |
| 1901 | allow some commands to be issued to change some runtime settings. Please |
Willy Tarreau | 1af20c7 | 2017-06-23 16:01:14 +0200 | [diff] [blame] | 1902 | consult section 9.3 "Unix Socket commands" of Management Guide for more |
Kevin Decherf | 949c720 | 2015-10-13 23:26:44 +0200 | [diff] [blame] | 1903 | details. |
Willy Tarreau | 6162db2 | 2009-10-10 17:13:00 +0200 | [diff] [blame] | 1904 | |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 1905 | All parameters supported by "bind" lines are supported, for instance to |
| 1906 | restrict access to some users or their access rights. Please consult |
| 1907 | section 5.1 for more information. |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 1908 | |
| 1909 | stats timeout <timeout, in milliseconds> |
| 1910 | The default timeout on the stats socket is set to 10 seconds. It is possible |
| 1911 | 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] | 1912 | 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] | 1913 | |
| 1914 | stats maxconn <connections> |
| 1915 | By default, the stats socket is limited to 10 concurrent connections. It is |
| 1916 | possible to change this value with "stats maxconn". |
| 1917 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1918 | uid <number> |
Thayne McCombs | cdbcca9 | 2021-01-07 21:24:41 -0700 | [diff] [blame] | 1919 | Changes the process's user ID to <number>. It is recommended that the user ID |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1920 | is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 1921 | be started with superuser privileges in order to be able to switch to another |
| 1922 | one. See also "gid" and "user". |
| 1923 | |
| 1924 | ulimit-n <number> |
| 1925 | Sets the maximum number of per-process file-descriptors to <number>. By |
| 1926 | default, it is automatically computed, so it is recommended not to use this |
| 1927 | option. |
| 1928 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 1929 | unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] |
| 1930 | [ group <group> ] [ gid <gid> ] |
| 1931 | |
| 1932 | Fixes common settings to UNIX listening sockets declared in "bind" statements. |
| 1933 | This is mainly used to simplify declaration of those UNIX sockets and reduce |
| 1934 | the risk of errors, since those settings are most commonly required but are |
| 1935 | also process-specific. The <prefix> setting can be used to force all socket |
| 1936 | path to be relative to that directory. This might be needed to access another |
| 1937 | component's chroot. Note that those paths are resolved before haproxy chroots |
| 1938 | itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid> |
| 1939 | all have the same meaning as their homonyms used by the "bind" statement. If |
| 1940 | both are specified, the "bind" statement has priority, meaning that the |
| 1941 | "unix-bind" settings may be seen as process-wide default settings. |
| 1942 | |
Willy Tarreau | 1d54972 | 2016-02-16 12:41:57 +0100 | [diff] [blame] | 1943 | unsetenv [<name> ...] |
| 1944 | Removes environment variables specified in arguments. This can be useful to |
| 1945 | hide some sensitive information that are occasionally inherited from the |
| 1946 | user's environment during some operations. Variables which did not exist are |
| 1947 | silently ignored so that after the operation, it is certain that none of |
| 1948 | these variables remain. The changes immediately take effect so that the next |
| 1949 | line in the configuration file will not see these variables. See also |
| 1950 | "setenv", "presetenv", and "resetenv". |
| 1951 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1952 | user <user name> |
| 1953 | Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. |
| 1954 | See also "uid" and "group". |
| 1955 | |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 1956 | node <name> |
| 1957 | Only letters, digits, hyphen and underscore are allowed, like in DNS names. |
| 1958 | |
| 1959 | This statement is useful in HA configurations where two or more processes or |
| 1960 | servers share the same IP address. By setting a different node-name on all |
| 1961 | nodes, it becomes easy to immediately spot what server is handling the |
| 1962 | traffic. |
| 1963 | |
| 1964 | description <text> |
| 1965 | Add a text that describes the instance. |
| 1966 | |
| 1967 | Please note that it is required to escape certain characters (# for example) |
| 1968 | and this text is inserted into a html page so you should avoid using |
| 1969 | "<" and ">" characters. |
| 1970 | |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1971 | 51degrees-data-file <file path> |
| 1972 | The path of the 51Degrees data file to provide device detection services. The |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 1973 | file should be unzipped and accessible by HAProxy with relevant permissions. |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1974 | |
Dragan Dosen | ae6d39a | 2015-06-29 16:43:27 +0200 | [diff] [blame] | 1975 | Please note that this option is only available when haproxy has been |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1976 | compiled with USE_51DEGREES. |
| 1977 | |
Ben Shillito | f25e8e5 | 2016-12-02 14:25:37 +0000 | [diff] [blame] | 1978 | 51degrees-property-name-list [<string> ...] |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1979 | A list of 51Degrees property names to be load from the dataset. A full list |
| 1980 | of names is available on the 51Degrees website: |
| 1981 | https://51degrees.com/resources/property-dictionary |
| 1982 | |
Dragan Dosen | ae6d39a | 2015-06-29 16:43:27 +0200 | [diff] [blame] | 1983 | Please note that this option is only available when haproxy has been |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1984 | compiled with USE_51DEGREES. |
| 1985 | |
Dragan Dosen | 93b38d9 | 2015-06-29 16:43:25 +0200 | [diff] [blame] | 1986 | 51degrees-property-separator <char> |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1987 | A char that will be appended to every property value in a response header |
| 1988 | containing 51Degrees results. If not set that will be set as ','. |
| 1989 | |
Dragan Dosen | ae6d39a | 2015-06-29 16:43:27 +0200 | [diff] [blame] | 1990 | Please note that this option is only available when haproxy has been |
| 1991 | compiled with USE_51DEGREES. |
| 1992 | |
| 1993 | 51degrees-cache-size <number> |
| 1994 | Sets the size of the 51Degrees converter cache to <number> entries. This |
| 1995 | is an LRU cache which reminds previous device detections and their results. |
| 1996 | By default, this cache is disabled. |
| 1997 | |
| 1998 | Please note that this option is only available when haproxy has been |
Thomas Holmes | db04f19 | 2015-05-18 13:21:39 +0100 | [diff] [blame] | 1999 | compiled with USE_51DEGREES. |
| 2000 | |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 2001 | wurfl-data-file <file path> |
| 2002 | The path of the WURFL data file to provide device detection services. The |
| 2003 | file should be accessible by HAProxy with relevant permissions. |
| 2004 | |
| 2005 | Please note that this option is only available when haproxy has been compiled |
| 2006 | with USE_WURFL=1. |
| 2007 | |
| 2008 | wurfl-information-list [<capability>]* |
| 2009 | A space-delimited list of WURFL capabilities, virtual capabilities, property |
| 2010 | names we plan to use in injected headers. A full list of capability and |
| 2011 | virtual capability names is available on the Scientiamobile website : |
| 2012 | |
| 2013 | https://www.scientiamobile.com/wurflCapability |
| 2014 | |
| 2015 | Valid WURFL properties are: |
| 2016 | - wurfl_id Contains the device ID of the matched device. |
| 2017 | |
| 2018 | - wurfl_root_id Contains the device root ID of the matched |
| 2019 | device. |
| 2020 | |
| 2021 | - wurfl_isdevroot Tells if the matched device is a root device. |
| 2022 | Possible values are "TRUE" or "FALSE". |
| 2023 | |
| 2024 | - wurfl_useragent The original useragent coming with this |
| 2025 | particular web request. |
| 2026 | |
| 2027 | - wurfl_api_version Contains a string representing the currently |
| 2028 | used Libwurfl API version. |
| 2029 | |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 2030 | - wurfl_info A string containing information on the parsed |
| 2031 | wurfl.xml and its full path. |
| 2032 | |
| 2033 | - wurfl_last_load_time Contains the UNIX timestamp of the last time |
| 2034 | WURFL has been loaded successfully. |
| 2035 | |
| 2036 | - wurfl_normalized_useragent The normalized useragent. |
| 2037 | |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 2038 | Please note that this option is only available when haproxy has been compiled |
| 2039 | with USE_WURFL=1. |
| 2040 | |
| 2041 | wurfl-information-list-separator <char> |
| 2042 | A char that will be used to separate values in a response header containing |
| 2043 | WURFL results. If not set that a comma (',') will be used by default. |
| 2044 | |
| 2045 | Please note that this option is only available when haproxy has been compiled |
| 2046 | with USE_WURFL=1. |
| 2047 | |
| 2048 | wurfl-patch-file [<file path>] |
| 2049 | A list of WURFL patch file paths. Note that patches are loaded during startup |
| 2050 | thus before the chroot. |
| 2051 | |
| 2052 | Please note that this option is only available when haproxy has been compiled |
| 2053 | with USE_WURFL=1. |
| 2054 | |
paulborile | bad132c | 2019-04-18 11:57:04 +0200 | [diff] [blame] | 2055 | wurfl-cache-size <size> |
| 2056 | Sets the WURFL Useragent cache size. For faster lookups, already processed user |
| 2057 | agents are kept in a LRU cache : |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 2058 | - "0" : no cache is used. |
paulborile | bad132c | 2019-04-18 11:57:04 +0200 | [diff] [blame] | 2059 | - <size> : size of lru cache in elements. |
Willy Tarreau | b3cc9f2 | 2019-04-19 16:03:32 +0200 | [diff] [blame] | 2060 | |
| 2061 | Please note that this option is only available when haproxy has been compiled |
| 2062 | with USE_WURFL=1. |
| 2063 | |
William Dauchy | 0fec3ab | 2019-10-27 20:08:11 +0100 | [diff] [blame] | 2064 | strict-limits |
William Dauchy | a519460 | 2020-03-28 19:29:58 +0100 | [diff] [blame] | 2065 | Makes process fail at startup when a setrlimit fails. Haproxy tries to set the |
| 2066 | best setrlimit according to what has been calculated. If it fails, it will |
| 2067 | emit a warning. This option is here to guarantee an explicit failure of |
| 2068 | haproxy when those limits fail. It is enabled by default. It may still be |
| 2069 | forcibly disabled by prefixing it with the "no" keyword. |
William Dauchy | 0fec3ab | 2019-10-27 20:08:11 +0100 | [diff] [blame] | 2070 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 2071 | 3.2. Performance tuning |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2072 | ----------------------- |
| 2073 | |
Willy Tarreau | beb859a | 2018-11-22 18:07:59 +0100 | [diff] [blame] | 2074 | busy-polling |
| 2075 | In some situations, especially when dealing with low latency on processors |
| 2076 | supporting a variable frequency or when running inside virtual machines, each |
| 2077 | time the process waits for an I/O using the poller, the processor goes back |
| 2078 | to sleep or is offered to another VM for a long time, and it causes |
| 2079 | excessively high latencies. This option provides a solution preventing the |
| 2080 | processor from sleeping by always using a null timeout on the pollers. This |
| 2081 | results in a significant latency reduction (30 to 100 microseconds observed) |
| 2082 | at the expense of a risk to overheat the processor. It may even be used with |
| 2083 | threads, in which case improperly bound threads may heavily conflict, |
| 2084 | resulting in a worse performance and high values for the CPU stolen fields |
| 2085 | in "show info" output, indicating which threads are misconfigured. It is |
| 2086 | important not to let the process run on the same processor as the network |
| 2087 | interrupts when this option is used. It is also better to avoid using it on |
| 2088 | multiple CPU threads sharing the same core. This option is disabled by |
| 2089 | default. If it has been enabled, it may still be forcibly disabled by |
| 2090 | prefixing it with the "no" keyword. It is ignored by the "select" and |
| 2091 | "poll" pollers. |
| 2092 | |
William Dauchy | 3894d97 | 2019-12-28 15:36:02 +0100 | [diff] [blame] | 2093 | This option is automatically disabled on old processes in the context of |
| 2094 | seamless reload; it avoids too much cpu conflicts when multiple processes |
| 2095 | stay around for some time waiting for the end of their current connections. |
| 2096 | |
Willy Tarreau | 1746eec | 2014-04-25 10:46:47 +0200 | [diff] [blame] | 2097 | max-spread-checks <delay in milliseconds> |
| 2098 | By default, haproxy tries to spread the start of health checks across the |
| 2099 | smallest health check interval of all the servers in a farm. The principle is |
| 2100 | to avoid hammering services running on the same server. But when using large |
| 2101 | check intervals (10 seconds or more), the last servers in the farm take some |
| 2102 | time before starting to be tested, which can be a problem. This parameter is |
| 2103 | used to enforce an upper bound on delay between the first and the last check, |
| 2104 | even if the servers' check intervals are larger. When servers run with |
| 2105 | shorter intervals, their intervals will be respected though. |
| 2106 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2107 | maxconn <number> |
| 2108 | Sets the maximum per-process number of concurrent connections to <number>. It |
| 2109 | is equivalent to the command-line argument "-n". Proxies will stop accepting |
| 2110 | connections when this limit is reached. The "ulimit-n" parameter is |
Willy Tarreau | 8274e10 | 2014-06-19 15:31:25 +0200 | [diff] [blame] | 2111 | automatically adjusted according to this value. See also "ulimit-n". Note: |
| 2112 | the "select" poller cannot reliably use more than 1024 file descriptors on |
| 2113 | some platforms. If your platform only supports select and reports "select |
| 2114 | FAILED" on startup, you need to reduce maxconn until it works (slightly |
Willy Tarreau | b28f344 | 2019-03-04 08:13:43 +0100 | [diff] [blame] | 2115 | below 500 in general). If this value is not set, it will automatically be |
| 2116 | calculated based on the current file descriptors limit reported by the |
| 2117 | "ulimit -n" command, possibly reduced to a lower value if a memory limit |
| 2118 | is enforced, based on the buffer size, memory allocated to compression, SSL |
| 2119 | cache size, and use or not of SSL and the associated maxsslconn (which can |
| 2120 | also be automatic). |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2121 | |
Willy Tarreau | 81c25d0 | 2011-09-07 15:17:21 +0200 | [diff] [blame] | 2122 | maxconnrate <number> |
| 2123 | Sets the maximum per-process number of connections per second to <number>. |
| 2124 | Proxies will stop accepting connections when this limit is reached. It can be |
| 2125 | used to limit the global capacity regardless of each frontend capacity. It is |
| 2126 | important to note that this can only be used as a service protection measure, |
| 2127 | as there will not necessarily be a fair share between frontends when the |
| 2128 | limit is reached, so it's a good idea to also limit each frontend to some |
| 2129 | value close to its expected share. Also, lowering tune.maxaccept can improve |
| 2130 | fairness. |
| 2131 | |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 2132 | maxcomprate <number> |
| 2133 | Sets the maximum per-process input compression rate to <number> kilobytes |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2134 | per second. For each session, if the maximum is reached, the compression |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 2135 | level will be decreased during the session. If the maximum is reached at the |
| 2136 | beginning of a session, the session will not compress at all. If the maximum |
| 2137 | is not reached, the compression level will be increased up to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2138 | tune.comp.maxlevel. A value of zero means there is no limit, this is the |
William Lallemand | d85f917 | 2012-11-09 17:05:39 +0100 | [diff] [blame] | 2139 | default value. |
| 2140 | |
William Lallemand | 072a2bf | 2012-11-20 17:01:01 +0100 | [diff] [blame] | 2141 | maxcompcpuusage <number> |
| 2142 | Sets the maximum CPU usage HAProxy can reach before stopping the compression |
| 2143 | for new requests or decreasing the compression level of current requests. |
| 2144 | It works like 'maxcomprate' but measures CPU usage instead of incoming data |
| 2145 | bandwidth. The value is expressed in percent of the CPU used by haproxy. In |
| 2146 | case of multiple processes (nbproc > 1), each process manages its individual |
| 2147 | usage. A value of 100 disable the limit. The default value is 100. Setting |
| 2148 | a lower value will prevent the compression work from slowing the whole |
| 2149 | process down and from introducing high latencies. |
| 2150 | |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 2151 | maxpipes <number> |
| 2152 | Sets the maximum per-process number of pipes to <number>. Currently, pipes |
| 2153 | are only used by kernel-based tcp splicing. Since a pipe contains two file |
| 2154 | descriptors, the "ulimit-n" value will be increased accordingly. The default |
| 2155 | value is maxconn/4, which seems to be more than enough for most heavy usages. |
| 2156 | The splice code dynamically allocates and releases pipes, and can fall back |
| 2157 | to standard copy, so setting this value too low may only impact performance. |
| 2158 | |
Willy Tarreau | 93e7c00 | 2013-10-07 18:51:07 +0200 | [diff] [blame] | 2159 | maxsessrate <number> |
| 2160 | Sets the maximum per-process number of sessions per second to <number>. |
| 2161 | Proxies will stop accepting connections when this limit is reached. It can be |
| 2162 | used to limit the global capacity regardless of each frontend capacity. It is |
| 2163 | important to note that this can only be used as a service protection measure, |
| 2164 | as there will not necessarily be a fair share between frontends when the |
| 2165 | limit is reached, so it's a good idea to also limit each frontend to some |
| 2166 | value close to its expected share. Also, lowering tune.maxaccept can improve |
| 2167 | fairness. |
| 2168 | |
Willy Tarreau | 403edff | 2012-09-06 11:58:37 +0200 | [diff] [blame] | 2169 | maxsslconn <number> |
| 2170 | Sets the maximum per-process number of concurrent SSL connections to |
| 2171 | <number>. By default there is no SSL-specific limit, which means that the |
| 2172 | global maxconn setting will apply to all connections. Setting this limit |
| 2173 | avoids having openssl use too much memory and crash when malloc returns NULL |
| 2174 | (since it unfortunately does not reliably check for such conditions). Note |
| 2175 | that the limit applies both to incoming and outgoing connections, so one |
| 2176 | connection which is deciphered then ciphered accounts for 2 SSL connections. |
Willy Tarreau | d025648 | 2015-01-15 21:45:22 +0100 | [diff] [blame] | 2177 | If this value is not set, but a memory limit is enforced, this value will be |
| 2178 | automatically computed based on the memory limit, maxconn, the buffer size, |
| 2179 | memory allocated to compression, SSL cache size, and use of SSL in either |
| 2180 | frontends, backends or both. If neither maxconn nor maxsslconn are specified |
| 2181 | when there is a memory limit, haproxy will automatically adjust these values |
| 2182 | so that 100% of the connections can be made over SSL with no risk, and will |
| 2183 | consider the sides where it is enabled (frontend, backend, both). |
Willy Tarreau | 403edff | 2012-09-06 11:58:37 +0200 | [diff] [blame] | 2184 | |
Willy Tarreau | e43d532 | 2013-10-07 20:01:52 +0200 | [diff] [blame] | 2185 | maxsslrate <number> |
| 2186 | Sets the maximum per-process number of SSL sessions per second to <number>. |
| 2187 | SSL listeners will stop accepting connections when this limit is reached. It |
| 2188 | can be used to limit the global SSL CPU usage regardless of each frontend |
| 2189 | capacity. It is important to note that this can only be used as a service |
| 2190 | protection measure, as there will not necessarily be a fair share between |
| 2191 | frontends when the limit is reached, so it's a good idea to also limit each |
| 2192 | frontend to some value close to its expected share. It is also important to |
| 2193 | note that the sessions are accounted before they enter the SSL stack and not |
| 2194 | after, which also protects the stack against bad handshakes. Also, lowering |
| 2195 | tune.maxaccept can improve fairness. |
| 2196 | |
William Lallemand | 9d5f548 | 2012-11-07 16:12:57 +0100 | [diff] [blame] | 2197 | maxzlibmem <number> |
| 2198 | Sets the maximum amount of RAM in megabytes per process usable by the zlib. |
| 2199 | When the maximum amount is reached, future sessions will not compress as long |
| 2200 | as RAM is unavailable. When sets to 0, there is no limit. |
William Lallemand | e3a7d99 | 2012-11-20 11:25:20 +0100 | [diff] [blame] | 2201 | The default value is 0. The value is available in bytes on the UNIX socket |
| 2202 | with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is |
| 2203 | "ZlibMemUsage" in bytes. |
| 2204 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2205 | noepoll |
| 2206 | Disables the use of the "epoll" event polling system on Linux. It is |
| 2207 | equivalent to the command-line argument "-de". The next polling system |
Willy Tarreau | e9f49e7 | 2012-11-11 17:42:00 +0100 | [diff] [blame] | 2208 | used will generally be "poll". See also "nopoll". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2209 | |
| 2210 | nokqueue |
| 2211 | Disables the use of the "kqueue" event polling system on BSD. It is |
| 2212 | equivalent to the command-line argument "-dk". The next polling system |
| 2213 | used will generally be "poll". See also "nopoll". |
| 2214 | |
Emmanuel Hocdet | 0ba4f48 | 2019-04-08 16:53:32 +0000 | [diff] [blame] | 2215 | noevports |
| 2216 | Disables the use of the event ports event polling system on SunOS systems |
| 2217 | derived from Solaris 10 and later. It is equivalent to the command-line |
| 2218 | argument "-dv". The next polling system used will generally be "poll". See |
| 2219 | also "nopoll". |
| 2220 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2221 | nopoll |
| 2222 | Disables the use of the "poll" event polling system. It is equivalent to the |
| 2223 | command-line argument "-dp". The next polling system used will be "select". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 2224 | It should never be needed to disable "poll" since it's available on all |
Emmanuel Hocdet | 0ba4f48 | 2019-04-08 16:53:32 +0000 | [diff] [blame] | 2225 | platforms supported by HAProxy. See also "nokqueue", "noepoll" and |
| 2226 | "noevports". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2227 | |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 2228 | nosplice |
| 2229 | Disables the use of kernel tcp splicing between sockets on Linux. It is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2230 | equivalent to the command line argument "-dS". Data will then be copied |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 2231 | 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] | 2232 | 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] | 2233 | 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not |
| 2234 | be used. This option makes it easier to globally disable kernel splicing in |
| 2235 | case of doubt. See also "option splice-auto", "option splice-request" and |
| 2236 | "option splice-response". |
| 2237 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 2238 | nogetaddrinfo |
| 2239 | Disables the use of getaddrinfo(3) for name resolving. It is equivalent to |
| 2240 | the command line argument "-dG". Deprecated gethostbyname(3) will be used. |
| 2241 | |
Lukas Tribus | a0bcbdc | 2016-09-12 21:42:20 +0000 | [diff] [blame] | 2242 | noreuseport |
| 2243 | Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the |
| 2244 | command line argument "-dR". |
| 2245 | |
Willy Tarreau | ca3afc2 | 2021-05-05 18:33:19 +0200 | [diff] [blame] | 2246 | profiling.memory { on | off } |
| 2247 | Enables ('on') or disables ('off') per-function memory profiling. This will |
| 2248 | keep usage statistics of malloc/calloc/realloc/free calls anywhere in the |
| 2249 | process (including libraries) which will be reported on the CLI using the |
| 2250 | "show profiling" command. This is essentially meant to be used when an |
| 2251 | abnormal memory usage is observed that cannot be explained by the pools and |
| 2252 | other info are required. The performance hit will typically be around 1%, |
| 2253 | maybe a bit more on highly threaded machines, so it is normally suitable for |
| 2254 | use in production. The same may be achieved at run time on the CLI using the |
| 2255 | "set profiling memory" command, please consult the management manual. |
| 2256 | |
Willy Tarreau | d2d3348 | 2019-04-25 17:09:07 +0200 | [diff] [blame] | 2257 | profiling.tasks { auto | on | off } |
| 2258 | Enables ('on') or disables ('off') per-task CPU profiling. When set to 'auto' |
| 2259 | the profiling automatically turns on a thread when it starts to suffer from |
| 2260 | an average latency of 1000 microseconds or higher as reported in the |
| 2261 | "avg_loop_us" activity field, and automatically turns off when the latency |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2262 | returns below 990 microseconds (this value is an average over the last 1024 |
Willy Tarreau | d2d3348 | 2019-04-25 17:09:07 +0200 | [diff] [blame] | 2263 | loops so it does not vary quickly and tends to significantly smooth short |
| 2264 | spikes). It may also spontaneously trigger from time to time on overloaded |
| 2265 | systems, containers, or virtual machines, or when the system swaps (which |
| 2266 | must absolutely never happen on a load balancer). |
| 2267 | |
| 2268 | CPU profiling per task can be very convenient to report where the time is |
| 2269 | spent and which requests have what effect on which other request. Enabling |
| 2270 | it will typically affect the overall's performance by less than 1%, thus it |
| 2271 | is recommended to leave it to the default 'auto' value so that it only |
| 2272 | operates when a problem is identified. This feature requires a system |
Willy Tarreau | 75c62c2 | 2018-11-22 11:02:09 +0100 | [diff] [blame] | 2273 | supporting the clock_gettime(2) syscall with clock identifiers |
| 2274 | CLOCK_MONOTONIC and CLOCK_THREAD_CPUTIME_ID, otherwise the reported time will |
| 2275 | be zero. This option may be changed at run time using "set profiling" on the |
| 2276 | CLI. |
| 2277 | |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 2278 | spread-checks <0..50, in percent> |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 2279 | Sometimes it is desirable to avoid sending agent and health checks to |
| 2280 | servers at exact intervals, for instance when many logical servers are |
| 2281 | located on the same physical server. With the help of this parameter, it |
| 2282 | becomes possible to add some randomness in the check interval between 0 |
| 2283 | and +/- 50%. A value between 2 and 5 seems to show good results. The |
| 2284 | default value remains at 0. |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 2285 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2286 | ssl-engine <name> [algo <comma-separated list of algorithms>] |
Grant Zhang | 872f9c2 | 2017-01-21 01:10:18 +0000 | [diff] [blame] | 2287 | Sets the OpenSSL engine to <name>. List of valid values for <name> may be |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2288 | obtained using the command "openssl engine". This statement may be used |
Grant Zhang | 872f9c2 | 2017-01-21 01:10:18 +0000 | [diff] [blame] | 2289 | multiple times, it will simply enable multiple crypto engines. Referencing an |
| 2290 | unsupported engine will prevent haproxy from starting. Note that many engines |
| 2291 | will lead to lower HTTPS performance than pure software with recent |
| 2292 | processors. The optional command "algo" sets the default algorithms an ENGINE |
| 2293 | will supply using the OPENSSL function ENGINE_set_default_string(). A value |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2294 | of "ALL" uses the engine for all cryptographic operations. If no list of |
| 2295 | algo is specified then the value of "ALL" is used. A comma-separated list |
Grant Zhang | 872f9c2 | 2017-01-21 01:10:18 +0000 | [diff] [blame] | 2296 | of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND, |
| 2297 | CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that |
| 2298 | openssl configuration file uses: |
| 2299 | https://www.openssl.org/docs/man1.0.2/apps/config.html |
| 2300 | |
Grant Zhang | fa6c7ee | 2017-01-14 01:42:15 +0000 | [diff] [blame] | 2301 | ssl-mode-async |
| 2302 | Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS |
Emeric Brun | 3854e01 | 2017-05-17 20:42:48 +0200 | [diff] [blame] | 2303 | I/O operations if asynchronous capable SSL engines are used. The current |
Emeric Brun | b5e42a8 | 2017-06-06 12:35:14 +0000 | [diff] [blame] | 2304 | implementation supports a maximum of 32 engines. The Openssl ASYNC API |
| 2305 | doesn't support moving read/write buffers and is not compliant with |
| 2306 | haproxy's buffer management. So the asynchronous mode is disabled on |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2307 | read/write operations (it is only enabled during initial and renegotiation |
Emeric Brun | b5e42a8 | 2017-06-06 12:35:14 +0000 | [diff] [blame] | 2308 | handshakes). |
Grant Zhang | fa6c7ee | 2017-01-14 01:42:15 +0000 | [diff] [blame] | 2309 | |
Willy Tarreau | 33cb065 | 2014-12-23 22:52:37 +0100 | [diff] [blame] | 2310 | tune.buffers.limit <number> |
| 2311 | Sets a hard limit on the number of buffers which may be allocated per process. |
| 2312 | The default value is zero which means unlimited. The minimum non-zero value |
| 2313 | will always be greater than "tune.buffers.reserve" and should ideally always |
| 2314 | be about twice as large. Forcing this value can be particularly useful to |
| 2315 | limit the amount of memory a process may take, while retaining a sane |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2316 | behavior. When this limit is reached, sessions which need a buffer wait for |
Willy Tarreau | 33cb065 | 2014-12-23 22:52:37 +0100 | [diff] [blame] | 2317 | another one to be released by another session. Since buffers are dynamically |
| 2318 | allocated and released, the waiting time is very short and not perceptible |
| 2319 | provided that limits remain reasonable. In fact sometimes reducing the limit |
| 2320 | may even increase performance by increasing the CPU cache's efficiency. Tests |
| 2321 | have shown good results on average HTTP traffic with a limit to 1/10 of the |
| 2322 | expected global maxconn setting, which also significantly reduces memory |
| 2323 | usage. The memory savings come from the fact that a number of connections |
| 2324 | will not allocate 2*tune.bufsize. It is best not to touch this value unless |
| 2325 | advised to do so by an haproxy core developer. |
| 2326 | |
Willy Tarreau | 1058ae7 | 2014-12-23 22:40:40 +0100 | [diff] [blame] | 2327 | tune.buffers.reserve <number> |
| 2328 | Sets the number of buffers which are pre-allocated and reserved for use only |
| 2329 | during memory shortage conditions resulting in failed memory allocations. The |
| 2330 | minimum value is 2 and is also the default. There is no reason a user would |
| 2331 | want to change this value, it's mostly aimed at haproxy core developers. |
| 2332 | |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 2333 | tune.bufsize <number> |
| 2334 | Sets the buffer size to this size (in bytes). Lower values allow more |
| 2335 | sessions to coexist in the same amount of RAM, and higher values allow some |
| 2336 | applications with very large cookies to work. The default value is 16384 and |
| 2337 | can be changed at build time. It is strongly recommended not to change this |
| 2338 | from the default value, as very low values will break some services such as |
| 2339 | statistics, and values larger than default size will increase memory usage, |
| 2340 | possibly causing the system to run out of memory. At least the global maxconn |
Willy Tarreau | 45a66cc | 2017-11-24 11:28:00 +0100 | [diff] [blame] | 2341 | parameter should be decreased by the same factor as this one is increased. In |
| 2342 | addition, use of HTTP/2 mandates that this value must be 16384 or more. If an |
| 2343 | HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will |
Dmitry Sivachenko | f6f4f7b | 2012-10-21 18:10:25 +0400 | [diff] [blame] | 2344 | return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger |
Willy Tarreau | c77d364 | 2018-12-12 06:19:42 +0100 | [diff] [blame] | 2345 | than this size, haproxy will return HTTP 502 (Bad Gateway). Note that the |
| 2346 | value set using this parameter will automatically be rounded up to the next |
| 2347 | multiple of 8 on 32-bit machines and 16 on 64-bit machines. |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 2348 | |
Christopher Faulet | bb9fb8b | 2020-11-25 17:20:57 +0100 | [diff] [blame] | 2349 | tune.chksize <number> (deprecated) |
| 2350 | This option is deprecated and ignored. |
Willy Tarreau | 43961d5 | 2010-10-04 20:39:20 +0200 | [diff] [blame] | 2351 | |
William Lallemand | f374783 | 2012-11-09 12:33:10 +0100 | [diff] [blame] | 2352 | tune.comp.maxlevel <number> |
| 2353 | Sets the maximum compression level. The compression level affects CPU |
| 2354 | usage during compression. This value affects CPU usage during compression. |
| 2355 | Each session using compression initializes the compression algorithm with |
| 2356 | this value. The default value is 1. |
| 2357 | |
Willy Tarreau | c299e1e | 2019-02-27 11:35:12 +0100 | [diff] [blame] | 2358 | tune.fail-alloc |
| 2359 | If compiled with DEBUG_FAIL_ALLOC, gives the percentage of chances an |
| 2360 | allocation attempt fails. Must be between 0 (no failure) and 100 (no |
| 2361 | success). This is useful to debug and make sure memory failures are handled |
| 2362 | gracefully. |
| 2363 | |
Willy Tarreau | bc52bec | 2020-06-18 08:58:47 +0200 | [diff] [blame] | 2364 | tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ] |
| 2365 | Enables ('on') or disables ('off') the edge-triggered polling mode for FDs |
| 2366 | that support it. This is currently only support with epoll. It may noticeably |
| 2367 | reduce the number of epoll_ctl() calls and slightly improve performance in |
| 2368 | certain scenarios. This is still experimental, it may result in frozen |
| 2369 | connections if bugs are still present, and is disabled by default. |
| 2370 | |
Willy Tarreau | fe20e5b | 2017-07-27 11:42:14 +0200 | [diff] [blame] | 2371 | tune.h2.header-table-size <number> |
| 2372 | Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and |
| 2373 | cannot be larger than 65536 bytes. A larger value may help certain clients |
| 2374 | send more compact requests, depending on their capabilities. This amount of |
| 2375 | memory is consumed for each HTTP/2 connection. It is recommended not to |
| 2376 | change it. |
| 2377 | |
Willy Tarreau | e6baec0 | 2017-07-27 11:45:11 +0200 | [diff] [blame] | 2378 | tune.h2.initial-window-size <number> |
| 2379 | Sets the HTTP/2 initial window size, which is the number of bytes the client |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2380 | can upload before waiting for an acknowledgment from haproxy. This setting |
| 2381 | only affects payload contents (i.e. the body of POST requests), not headers. |
Willy Tarreau | e6baec0 | 2017-07-27 11:45:11 +0200 | [diff] [blame] | 2382 | The default value is 65535, which roughly allows up to 5 Mbps of upload |
| 2383 | bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps |
| 2384 | over a 1-ms local network. It can make sense to increase this value to allow |
| 2385 | faster uploads, or to reduce it to increase fairness when dealing with many |
| 2386 | clients. It doesn't affect resource usage. |
| 2387 | |
Willy Tarreau | 5242ef8 | 2017-07-27 11:47:28 +0200 | [diff] [blame] | 2388 | tune.h2.max-concurrent-streams <number> |
| 2389 | Sets the HTTP/2 maximum number of concurrent streams per connection (ie the |
| 2390 | number of outstanding requests on a single connection). The default value is |
| 2391 | 100. A larger one may slightly improve page load time for complex sites when |
| 2392 | visited over high latency networks, but increases the amount of resources a |
| 2393 | single client may allocate. A value of zero disables the limit so a single |
| 2394 | client may create as many streams as allocatable by haproxy. It is highly |
| 2395 | recommended not to change this value. |
| 2396 | |
Willy Tarreau | a24b35c | 2019-02-21 13:24:36 +0100 | [diff] [blame] | 2397 | tune.h2.max-frame-size <number> |
| 2398 | Sets the HTTP/2 maximum frame size that haproxy announces it is willing to |
| 2399 | receive to its peers. The default value is the largest between 16384 and the |
| 2400 | buffer size (tune.bufsize). In any case, haproxy will not announce support |
| 2401 | for frame sizes larger than buffers. The main purpose of this setting is to |
| 2402 | allow to limit the maximum frame size setting when using large buffers. Too |
| 2403 | large frame sizes might have performance impact or cause some peers to |
| 2404 | misbehave. It is highly recommended not to change this value. |
| 2405 | |
Willy Tarreau | 193b8c6 | 2012-11-22 00:17:38 +0100 | [diff] [blame] | 2406 | tune.http.cookielen <number> |
| 2407 | Sets the maximum length of captured cookies. This is the maximum value that |
| 2408 | the "capture cookie xxx len yyy" will be allowed to take, and any upper value |
| 2409 | will automatically be truncated to this one. It is important not to set too |
| 2410 | high a value because all cookie captures still allocate this size whatever |
| 2411 | their configured value (they share a same pool). This value is per request |
| 2412 | per response, so the memory allocated is twice this value per connection. |
| 2413 | When not specified, the limit is set to 63 characters. It is recommended not |
| 2414 | to change this value. |
| 2415 | |
Stéphane Cottin | 23e9e93 | 2017-05-18 08:58:41 +0200 | [diff] [blame] | 2416 | tune.http.logurilen <number> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2417 | Sets the maximum length of request URI in logs. This prevents truncating long |
| 2418 | request URIs with valuable query strings in log lines. This is not related |
Stéphane Cottin | 23e9e93 | 2017-05-18 08:58:41 +0200 | [diff] [blame] | 2419 | to syslog limits. If you increase this limit, you may also increase the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2420 | 'log ... len yyy' parameter. Your syslog daemon may also need specific |
Stéphane Cottin | 23e9e93 | 2017-05-18 08:58:41 +0200 | [diff] [blame] | 2421 | configuration directives too. |
| 2422 | The default value is 1024. |
| 2423 | |
Willy Tarreau | ac1932d | 2011-10-24 19:14:41 +0200 | [diff] [blame] | 2424 | tune.http.maxhdr <number> |
| 2425 | Sets the maximum number of headers in a request. When a request comes with a |
| 2426 | number of headers greater than this value (including the first line), it is |
| 2427 | rejected with a "400 Bad Request" status code. Similarly, too large responses |
| 2428 | are blocked with "502 Bad Gateway". The default value is 101, which is enough |
| 2429 | for all usages, considering that the widely deployed Apache server uses the |
| 2430 | same limit. It can be useful to push this limit further to temporarily allow |
Christopher Faulet | 50174f3 | 2017-06-21 16:31:35 +0200 | [diff] [blame] | 2431 | a buggy application to work by the time it gets fixed. The accepted range is |
| 2432 | 1..32767. Keep in mind that each new header consumes 32bits of memory for |
| 2433 | each session, so don't push this limit too high. |
Willy Tarreau | ac1932d | 2011-10-24 19:14:41 +0200 | [diff] [blame] | 2434 | |
Willy Tarreau | 76cc699 | 2020-07-01 18:49:24 +0200 | [diff] [blame] | 2435 | tune.idle-pool.shared { on | off } |
| 2436 | Enables ('on') or disables ('off') sharing of idle connection pools between |
| 2437 | threads for a same server. The default is to share them between threads in |
| 2438 | order to minimize the number of persistent connections to a server, and to |
| 2439 | optimize the connection reuse rate. But to help with debugging or when |
| 2440 | suspecting a bug in HAProxy around connection reuse, it can be convenient to |
| 2441 | forcefully disable this idle pool sharing between multiple threads, and force |
Willy Tarreau | 0784db8 | 2021-02-19 11:45:22 +0100 | [diff] [blame] | 2442 | this option to "off". The default is on. It is strongly recommended against |
| 2443 | disabling this option without setting a conservative value on "pool-low-conn" |
| 2444 | for all servers relying on connection reuse to achieve a high performance |
| 2445 | level, otherwise connections might be closed very often as the thread count |
| 2446 | increases. |
Willy Tarreau | 76cc699 | 2020-07-01 18:49:24 +0200 | [diff] [blame] | 2447 | |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 2448 | tune.idletimer <timeout> |
| 2449 | Sets the duration after which haproxy will consider that an empty buffer is |
| 2450 | probably associated with an idle stream. This is used to optimally adjust |
| 2451 | some packet sizes while forwarding large and small data alternatively. The |
| 2452 | decision to use splice() or to send large buffers in SSL is modulated by this |
| 2453 | parameter. The value is in milliseconds between 0 and 65535. A value of zero |
| 2454 | means that haproxy will not try to detect idle streams. The default is 1000, |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2455 | which seems to correctly detect end user pauses (e.g. read a page before |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2456 | clicking). There should be no reason for changing this value. Please check |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 2457 | tune.ssl.maxrecord below. |
| 2458 | |
Willy Tarreau | 7ac908b | 2019-02-27 12:02:18 +0100 | [diff] [blame] | 2459 | tune.listener.multi-queue { on | off } |
| 2460 | Enables ('on') or disables ('off') the listener's multi-queue accept which |
| 2461 | spreads the incoming traffic to all threads a "bind" line is allowed to run |
| 2462 | on instead of taking them for itself. This provides a smoother traffic |
| 2463 | distribution and scales much better, especially in environments where threads |
| 2464 | may be unevenly loaded due to external activity (network interrupts colliding |
| 2465 | with one thread for example). This option is enabled by default, but it may |
| 2466 | be forcefully disabled for troubleshooting or for situations where it is |
| 2467 | estimated that the operating system already provides a good enough |
| 2468 | distribution and connections are extremely short-lived. |
| 2469 | |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 2470 | tune.lua.forced-yield <number> |
| 2471 | This directive forces the Lua engine to execute a yield each <number> of |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 2472 | instructions executed. This permits interrupting a long script and allows the |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 2473 | HAProxy scheduler to process other tasks like accepting connections or |
| 2474 | forwarding traffic. The default value is 10000 instructions. If HAProxy often |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2475 | executes some Lua code but more responsiveness is required, this value can be |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 2476 | lowered. If the Lua code is quite long and its result is absolutely required |
| 2477 | to process the data, the <number> can be increased. |
| 2478 | |
Willy Tarreau | 32f61e2 | 2015-03-18 17:54:59 +0100 | [diff] [blame] | 2479 | tune.lua.maxmem |
| 2480 | Sets the maximum amount of RAM in megabytes per process usable by Lua. By |
| 2481 | default it is zero which means unlimited. It is important to set a limit to |
| 2482 | ensure that a bug in a script will not result in the system running out of |
| 2483 | memory. |
| 2484 | |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 2485 | tune.lua.session-timeout <timeout> |
| 2486 | This is the execution timeout for the Lua sessions. This is useful for |
Thierry FOURNIER | 7dd784b | 2015-10-01 14:49:33 +0200 | [diff] [blame] | 2487 | preventing infinite loops or spending too much time in Lua. This timeout |
| 2488 | counts only the pure Lua runtime. If the Lua does a sleep, the sleep is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2489 | not taken in account. The default timeout is 4s. |
Thierry FOURNIER | 90da191 | 2015-03-05 11:17:06 +0100 | [diff] [blame] | 2490 | |
| 2491 | tune.lua.task-timeout <timeout> |
| 2492 | Purpose is the same as "tune.lua.session-timeout", but this timeout is |
| 2493 | dedicated to the tasks. By default, this timeout isn't set because a task may |
| 2494 | remain alive during of the lifetime of HAProxy. For example, a task used to |
| 2495 | check servers. |
| 2496 | |
Thierry FOURNIER | 7dd784b | 2015-10-01 14:49:33 +0200 | [diff] [blame] | 2497 | tune.lua.service-timeout <timeout> |
| 2498 | This is the execution timeout for the Lua services. This is useful for |
| 2499 | preventing infinite loops or spending too much time in Lua. This timeout |
| 2500 | counts only the pure Lua runtime. If the Lua does a sleep, the sleep is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2501 | not taken in account. The default timeout is 4s. |
Thierry FOURNIER | 7dd784b | 2015-10-01 14:49:33 +0200 | [diff] [blame] | 2502 | |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 2503 | tune.maxaccept <number> |
Willy Tarreau | 16a2147 | 2012-11-19 12:39:59 +0100 | [diff] [blame] | 2504 | Sets the maximum number of consecutive connections a process may accept in a |
| 2505 | row before switching to other work. In single process mode, higher numbers |
Willy Tarreau | 6616132 | 2021-02-19 15:50:27 +0100 | [diff] [blame] | 2506 | used to give better performance at high connection rates, though this is not |
| 2507 | the case anymore with the multi-queue. This value applies individually to |
| 2508 | each listener, so that the number of processes a listener is bound to is |
| 2509 | taken into account. This value defaults to 4 which showed best results. If a |
| 2510 | significantly higher value was inherited from an ancient config, it might be |
| 2511 | worth removing it as it will both increase performance and lower response |
| 2512 | time. In multi-process mode, it is divided by twice the number of processes |
| 2513 | the listener is bound to. Setting this value to -1 completely disables the |
| 2514 | limitation. It should normally not be needed to tweak this value. |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 2515 | |
| 2516 | tune.maxpollevents <number> |
| 2517 | Sets the maximum amount of events that can be processed at once in a call to |
| 2518 | the polling system. The default value is adapted to the operating system. It |
| 2519 | has been noticed that reducing it below 200 tends to slightly decrease |
| 2520 | latency at the expense of network bandwidth, and increasing it above 200 |
| 2521 | tends to trade latency for slightly increased bandwidth. |
| 2522 | |
Willy Tarreau | 27a674e | 2009-08-17 07:23:33 +0200 | [diff] [blame] | 2523 | tune.maxrewrite <number> |
| 2524 | Sets the reserved buffer space to this size in bytes. The reserved space is |
| 2525 | used for header rewriting or appending. The first reads on sockets will never |
| 2526 | fill more than bufsize-maxrewrite. Historically it has defaulted to half of |
| 2527 | bufsize, though that does not make much sense since there are rarely large |
| 2528 | numbers of headers to add. Setting it too high prevents processing of large |
| 2529 | requests or responses. Setting it too low prevents addition of new headers |
| 2530 | to already large requests or to POST requests. It is generally wise to set it |
| 2531 | to about 1024. It is automatically readjusted to half of bufsize if it is |
| 2532 | larger than that. This means you don't have to worry about it when changing |
| 2533 | bufsize. |
| 2534 | |
Willy Tarreau | f3045d2 | 2015-04-29 16:24:50 +0200 | [diff] [blame] | 2535 | tune.pattern.cache-size <number> |
| 2536 | Sets the size of the pattern lookup cache to <number> entries. This is an LRU |
| 2537 | cache which reminds previous lookups and their results. It is used by ACLs |
| 2538 | and maps on slow pattern lookups, namely the ones using the "sub", "reg", |
| 2539 | "dir", "dom", "end", "bin" match methods as well as the case-insensitive |
| 2540 | strings. It applies to pattern expressions which means that it will be able |
| 2541 | to memorize the result of a lookup among all the patterns specified on a |
| 2542 | configuration line (including all those loaded from files). It automatically |
| 2543 | invalidates entries which are updated using HTTP actions or on the CLI. The |
| 2544 | default cache size is set to 10000 entries, which limits its footprint to |
Willy Tarreau | 403bfbb | 2019-10-23 06:59:31 +0200 | [diff] [blame] | 2545 | about 5 MB per process/thread on 32-bit systems and 8 MB per process/thread |
| 2546 | on 64-bit systems, as caches are thread/process local. There is a very low |
Willy Tarreau | f3045d2 | 2015-04-29 16:24:50 +0200 | [diff] [blame] | 2547 | risk of collision in this cache, which is in the order of the size of the |
| 2548 | cache divided by 2^64. Typically, at 10000 requests per second with the |
| 2549 | default cache size of 10000 entries, there's 1% chance that a brute force |
| 2550 | attack could cause a single collision after 60 years, or 0.1% after 6 years. |
| 2551 | This is considered much lower than the risk of a memory corruption caused by |
| 2552 | aging components. If this is not acceptable, the cache can be disabled by |
| 2553 | setting this parameter to 0. |
| 2554 | |
Willy Tarreau | bd9a0a7 | 2011-10-23 21:14:29 +0200 | [diff] [blame] | 2555 | tune.pipesize <number> |
| 2556 | Sets the kernel pipe buffer size to this size (in bytes). By default, pipes |
| 2557 | are the default size for the system. But sometimes when using TCP splicing, |
| 2558 | it can improve performance to increase pipe sizes, especially if it is |
| 2559 | suspected that pipes are not filled and that many calls to splice() are |
| 2560 | performed. This has an impact on the kernel's memory footprint, so this must |
| 2561 | not be changed if impacts are not understood. |
| 2562 | |
Olivier Houchard | 88698d9 | 2019-04-16 19:07:22 +0200 | [diff] [blame] | 2563 | tune.pool-high-fd-ratio <number> |
| 2564 | This setting sets the max number of file descriptors (in percentage) used by |
| 2565 | haproxy globally against the maximum number of file descriptors haproxy can |
| 2566 | use before we start killing idle connections when we can't reuse a connection |
| 2567 | and we have to create a new one. The default is 25 (one quarter of the file |
| 2568 | descriptor will mean that roughly half of the maximum front connections can |
| 2569 | keep an idle connection behind, anything beyond this probably doesn't make |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2570 | much sense in the general case when targeting connection reuse). |
Olivier Houchard | 88698d9 | 2019-04-16 19:07:22 +0200 | [diff] [blame] | 2571 | |
Willy Tarreau | 83ca305 | 2020-07-01 18:30:16 +0200 | [diff] [blame] | 2572 | tune.pool-low-fd-ratio <number> |
| 2573 | This setting sets the max number of file descriptors (in percentage) used by |
| 2574 | haproxy globally against the maximum number of file descriptors haproxy can |
| 2575 | use before we stop putting connection into the idle pool for reuse. The |
| 2576 | default is 20. |
| 2577 | |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 2578 | tune.rcvbuf.client <number> |
| 2579 | tune.rcvbuf.server <number> |
| 2580 | Forces the kernel socket receive buffer size on the client or the server side |
| 2581 | to the specified value in bytes. This value applies to all TCP/HTTP frontends |
| 2582 | and backends. It should normally never be set, and the default size (0) lets |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2583 | the kernel auto-tune this value depending on the amount of available memory. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2584 | However it can sometimes help to set it to very low values (e.g. 4096) in |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 2585 | order to save kernel memory by preventing it from buffering too large amounts |
| 2586 | of received data. Lower values will significantly increase CPU usage though. |
| 2587 | |
Willy Tarreau | b22fc30 | 2015-12-14 12:04:35 +0100 | [diff] [blame] | 2588 | tune.recv_enough <number> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2589 | HAProxy uses some hints to detect that a short read indicates the end of the |
Willy Tarreau | b22fc30 | 2015-12-14 12:04:35 +0100 | [diff] [blame] | 2590 | socket buffers. One of them is that a read returns more than <recv_enough> |
| 2591 | bytes, which defaults to 10136 (7 segments of 1448 each). This default value |
| 2592 | may be changed by this setting to better deal with workloads involving lots |
| 2593 | of short messages such as telnet or SSH sessions. |
| 2594 | |
Olivier Houchard | 1599b80 | 2018-05-24 18:59:04 +0200 | [diff] [blame] | 2595 | tune.runqueue-depth <number> |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2596 | Sets the maximum amount of task that can be processed at once when running |
Willy Tarreau | 060a761 | 2021-03-10 11:06:26 +0100 | [diff] [blame] | 2597 | tasks. The default value depends on the number of threads but sits between 35 |
| 2598 | and 280, which tend to show the highest request rates and lowest latencies. |
| 2599 | Increasing it may incur latency when dealing with I/Os, making it too small |
| 2600 | can incur extra overhead. Higher thread counts benefit from lower values. |
| 2601 | When experimenting with much larger values, it may be useful to also enable |
| 2602 | tune.sched.low-latency and possibly tune.fd.edge-triggered to limit the |
| 2603 | maximum latency to the lowest possible. |
Willy Tarreau | e7723bd | 2020-06-24 11:11:02 +0200 | [diff] [blame] | 2604 | |
| 2605 | tune.sched.low-latency { on | off } |
| 2606 | Enables ('on') or disables ('off') the low-latency task scheduler. By default |
| 2607 | haproxy processes tasks from several classes one class at a time as this is |
| 2608 | the most efficient. But when running with large values of tune.runqueue-depth |
| 2609 | this can have a measurable effect on request or connection latency. When this |
| 2610 | low-latency setting is enabled, tasks of lower priority classes will always |
| 2611 | be executed before other ones if they exist. This will permit to lower the |
| 2612 | maximum latency experienced by new requests or connections in the middle of |
| 2613 | massive traffic, at the expense of a higher impact on this large traffic. |
| 2614 | For regular usage it is better to leave this off. The default value is off. |
Olivier Houchard | 1599b80 | 2018-05-24 18:59:04 +0200 | [diff] [blame] | 2615 | |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 2616 | tune.sndbuf.client <number> |
| 2617 | tune.sndbuf.server <number> |
| 2618 | Forces the kernel socket send buffer size on the client or the server side to |
| 2619 | the specified value in bytes. This value applies to all TCP/HTTP frontends |
| 2620 | and backends. It should normally never be set, and the default size (0) lets |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2621 | the kernel auto-tune this value depending on the amount of available memory. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2622 | However it can sometimes help to set it to very low values (e.g. 4096) in |
Willy Tarreau | e803de2 | 2010-01-21 17:43:04 +0100 | [diff] [blame] | 2623 | order to save kernel memory by preventing it from buffering too large amounts |
| 2624 | of received data. Lower values will significantly increase CPU usage though. |
| 2625 | Another use case is to prevent write timeouts with extremely slow clients due |
| 2626 | to the kernel waiting for a large part of the buffer to be read before |
| 2627 | notifying haproxy again. |
| 2628 | |
Willy Tarreau | 6ec58db | 2012-11-16 16:32:15 +0100 | [diff] [blame] | 2629 | tune.ssl.cachesize <number> |
Emeric Brun | af9619d | 2012-11-28 18:47:52 +0100 | [diff] [blame] | 2630 | Sets the size of the global SSL session cache, in a number of blocks. A block |
William Dauchy | 9a4bbfe | 2021-02-12 15:58:46 +0100 | [diff] [blame] | 2631 | is large enough to contain an encoded session without peer certificate. An |
| 2632 | encoded session with peer certificate is stored in multiple blocks depending |
| 2633 | on the size of the peer certificate. A block uses approximately 200 bytes of |
| 2634 | memory (based on `sizeof(struct sh_ssl_sess_hdr) + SHSESS_BLOCK_MIN_SIZE` |
| 2635 | calculation used for `shctx_init` function). The default value may be forced |
| 2636 | at build time, otherwise defaults to 20000. When the cache is full, the most |
| 2637 | idle entries are purged and reassigned. Higher values reduce the occurrence |
| 2638 | of such a purge, hence the number of CPU-intensive SSL handshakes by ensuring |
| 2639 | that all users keep their session as long as possible. All entries are |
| 2640 | pre-allocated upon startup and are shared between all processes if "nbproc" |
| 2641 | is greater than 1. Setting this value to 0 disables the SSL session cache. |
Willy Tarreau | 6ec58db | 2012-11-16 16:32:15 +0100 | [diff] [blame] | 2642 | |
Emeric Brun | 8dc6039 | 2014-05-09 13:52:00 +0200 | [diff] [blame] | 2643 | tune.ssl.force-private-cache |
Lukas Tribus | 2793578 | 2018-10-01 02:00:16 +0200 | [diff] [blame] | 2644 | This option disables SSL session cache sharing between all processes. It |
Emeric Brun | 8dc6039 | 2014-05-09 13:52:00 +0200 | [diff] [blame] | 2645 | should normally not be used since it will force many renegotiations due to |
| 2646 | clients hitting a random process. But it may be required on some operating |
| 2647 | systems where none of the SSL cache synchronization method may be used. In |
| 2648 | this case, adding a first layer of hash-based load balancing before the SSL |
| 2649 | layer might limit the impact of the lack of session sharing. |
| 2650 | |
William Lallemand | 7d42ef5 | 2020-07-06 11:41:30 +0200 | [diff] [blame] | 2651 | tune.ssl.keylog { on | off } |
| 2652 | This option activates the logging of the TLS keys. It should be used with |
| 2653 | care as it will consume more memory per SSL session and could decrease |
| 2654 | performances. This is disabled by default. |
| 2655 | |
| 2656 | These sample fetches should be used to generate the SSLKEYLOGFILE that is |
| 2657 | required to decipher traffic with wireshark. |
| 2658 | |
| 2659 | https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format |
| 2660 | |
| 2661 | The SSLKEYLOG is a series of lines which are formatted this way: |
| 2662 | |
| 2663 | <Label> <space> <ClientRandom> <space> <Secret> |
| 2664 | |
| 2665 | The ClientRandom is provided by the %[ssl_fc_client_random,hex] sample |
| 2666 | fetch, the secret and the Label could be find in the array below. You need |
| 2667 | to generate a SSLKEYLOGFILE with all the labels in this array. |
| 2668 | |
| 2669 | The following sample fetches are hexadecimal strings and does not need to be |
| 2670 | converted. |
| 2671 | |
| 2672 | SSLKEYLOGFILE Label | Sample fetches for the Secrets |
| 2673 | --------------------------------|----------------------------------------- |
| 2674 | CLIENT_EARLY_TRAFFIC_SECRET | %[ssl_fc_client_early_traffic_secret] |
| 2675 | CLIENT_HANDSHAKE_TRAFFIC_SECRET | %[ssl_fc_client_handshake_traffic_secret] |
| 2676 | SERVER_HANDSHAKE_TRAFFIC_SECRET | %[ssl_fc_server_handshake_traffic_secret] |
| 2677 | CLIENT_TRAFFIC_SECRET_0 | %[ssl_fc_client_traffic_secret_0] |
| 2678 | SERVER_TRAFFIC_SECRET_0 | %[ssl_fc_server_traffic_secret_0] |
William Lallemand | d742b6c | 2020-07-07 10:14:56 +0200 | [diff] [blame] | 2679 | EXPORTER_SECRET | %[ssl_fc_exporter_secret] |
| 2680 | EARLY_EXPORTER_SECRET | %[ssl_fc_early_exporter_secret] |
William Lallemand | 7d42ef5 | 2020-07-06 11:41:30 +0200 | [diff] [blame] | 2681 | |
| 2682 | This is only available with OpenSSL 1.1.1, and useful with TLS1.3 session. |
| 2683 | |
| 2684 | If you want to generate the content of a SSLKEYLOGFILE with TLS < 1.3, you |
| 2685 | only need this line: |
| 2686 | |
| 2687 | "CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]" |
| 2688 | |
Emeric Brun | 4f65bff | 2012-11-16 15:11:00 +0100 | [diff] [blame] | 2689 | tune.ssl.lifetime <timeout> |
| 2690 | 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] | 2691 | 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] | 2692 | does not guarantee that sessions will last that long, because if the cache is |
| 2693 | full, the longest idle sessions will be purged despite their configured |
| 2694 | lifetime. The real usefulness of this setting is to prevent sessions from |
| 2695 | being used for too long. |
| 2696 | |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 2697 | tune.ssl.maxrecord <number> |
| 2698 | Sets the maximum amount of bytes passed to SSL_write() at a time. Default |
| 2699 | value 0 means there is no limit. Over SSL/TLS, the client can decipher the |
| 2700 | data only once it has received a full record. With large records, it means |
| 2701 | that clients might have to download up to 16kB of data before starting to |
| 2702 | process them. Limiting the value can improve page load times on browsers |
| 2703 | located over high latency or low bandwidth networks. It is suggested to find |
| 2704 | optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over |
| 2705 | Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled), |
| 2706 | keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and |
| 2707 | 2859 gave good results during tests. Use "strace -e trace=write" to find the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2708 | best value. HAProxy will automatically switch to this setting after an idle |
Willy Tarreau | 7e31273 | 2014-02-12 16:35:14 +0100 | [diff] [blame] | 2709 | stream has been detected (see tune.idletimer above). |
Willy Tarreau | bfd5946 | 2013-02-21 07:46:09 +0100 | [diff] [blame] | 2710 | |
Remi Gacogne | f46cd6e | 2014-06-12 14:58:40 +0200 | [diff] [blame] | 2711 | tune.ssl.default-dh-param <number> |
| 2712 | Sets the maximum size of the Diffie-Hellman parameters used for generating |
| 2713 | the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The |
| 2714 | final size will try to match the size of the server's RSA (or DSA) key (e.g, |
| 2715 | a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed |
Willy Tarreau | 3ba77d2 | 2020-05-08 09:31:18 +0200 | [diff] [blame] | 2716 | this maximum value. Default value if 2048. Only 1024 or higher values are |
Remi Gacogne | f46cd6e | 2014-06-12 14:58:40 +0200 | [diff] [blame] | 2717 | allowed. Higher values will increase the CPU load, and values greater than |
| 2718 | 1024 bits are not supported by Java 7 and earlier clients. This value is not |
Remi Gacogne | 47783ef | 2015-05-29 15:53:22 +0200 | [diff] [blame] | 2719 | used if static Diffie-Hellman parameters are supplied either directly |
| 2720 | in the certificate file or by using the ssl-dh-param-file parameter. |
Remi Gacogne | f46cd6e | 2014-06-12 14:58:40 +0200 | [diff] [blame] | 2721 | |
Christopher Faulet | 31af49d | 2015-06-09 17:29:50 +0200 | [diff] [blame] | 2722 | tune.ssl.ssl-ctx-cache-size <number> |
| 2723 | Sets the size of the cache used to store generated certificates to <number> |
| 2724 | entries. This is a LRU cache. Because generating a SSL certificate |
| 2725 | dynamically is expensive, they are cached. The default cache size is set to |
| 2726 | 1000 entries. |
| 2727 | |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 2728 | tune.ssl.capture-cipherlist-size <number> |
| 2729 | Sets the maximum size of the buffer used for capturing client-hello cipher |
| 2730 | list. If the value is 0 (default value) the capture is disabled, otherwise |
| 2731 | a buffer is allocated for each SSL/TLS connection. |
| 2732 | |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 2733 | tune.vars.global-max-size <size> |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 2734 | tune.vars.proc-max-size <size> |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 2735 | tune.vars.reqres-max-size <size> |
| 2736 | tune.vars.sess-max-size <size> |
| 2737 | tune.vars.txn-max-size <size> |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 2738 | These five tunes help to manage the maximum amount of memory used by the |
| 2739 | variables system. "global" limits the overall amount of memory available for |
| 2740 | all scopes. "proc" limits the memory for the process scope, "sess" limits the |
| 2741 | memory for the session scope, "txn" for the transaction scope, and "reqres" |
| 2742 | limits the memory for each request or response processing. |
| 2743 | Memory accounting is hierarchical, meaning more coarse grained limits include |
| 2744 | the finer grained ones: "proc" includes "sess", "sess" includes "txn", and |
| 2745 | "txn" includes "reqres". |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 2746 | |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 2747 | For example, when "tune.vars.sess-max-size" is limited to 100, |
| 2748 | "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed |
| 2749 | 100 either. If we create a variable "txn.var" that contains 100 bytes, |
| 2750 | all available space is consumed. |
| 2751 | Notice that exceeding the limits at runtime will not result in an error |
| 2752 | message, but values might be cut off or corrupted. So make sure to accurately |
| 2753 | plan for the amount of space needed to store all your variables. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 2754 | |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 2755 | tune.zlib.memlevel <number> |
| 2756 | Sets the memLevel parameter in zlib initialization for each session. It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 2757 | defines how much memory should be allocated for the internal compression |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 2758 | state. A value of 1 uses minimum memory but is slow and reduces compression |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2759 | ratio, a value of 9 uses maximum memory for optimal speed. Can be a value |
William Lallemand | a509e4c | 2012-11-07 16:54:34 +0100 | [diff] [blame] | 2760 | between 1 and 9. The default value is 8. |
| 2761 | |
| 2762 | tune.zlib.windowsize <number> |
| 2763 | Sets the window size (the size of the history buffer) as a parameter of the |
| 2764 | zlib initialization for each session. Larger values of this parameter result |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 2765 | in better compression at the expense of memory usage. Can be a value between |
| 2766 | 8 and 15. The default value is 15. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2767 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 2768 | 3.3. Debugging |
| 2769 | -------------- |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2770 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2771 | quiet |
| 2772 | Do not display any message during startup. It is equivalent to the command- |
| 2773 | line argument "-q". |
| 2774 | |
Willy Tarreau | 3eb10b8 | 2020-04-15 16:42:39 +0200 | [diff] [blame] | 2775 | zero-warning |
| 2776 | When this option is set, haproxy will refuse to start if any warning was |
| 2777 | emitted while processing the configuration. It is highly recommended to set |
| 2778 | this option on configurations that are not changed often, as it helps detect |
| 2779 | subtle mistakes and keep the configuration clean and forward-compatible. Note |
| 2780 | that "haproxy -c" will also report errors in such a case. This option is |
| 2781 | equivalent to command line argument "-dW". |
| 2782 | |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2783 | |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2784 | 3.4. Userlists |
| 2785 | -------------- |
| 2786 | It is possible to control access to frontend/backend/listen sections or to |
| 2787 | http stats by allowing only authenticated and authorized users. To do this, |
| 2788 | it is required to create at least one userlist and to define users. |
| 2789 | |
| 2790 | userlist <listname> |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 2791 | Creates new userlist with name <listname>. Many independent userlists can be |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2792 | used to store authentication & authorization data for independent customers. |
| 2793 | |
| 2794 | group <groupname> [users <user>,<user>,(...)] |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 2795 | 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] | 2796 | attach users to this group by using a comma separated list of names |
| 2797 | proceeded by "users" keyword. |
| 2798 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2799 | user <username> [password|insecure-password <password>] |
| 2800 | [groups <group>,<group>,(...)] |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2801 | Adds user <username> to the current userlist. Both secure (encrypted) and |
| 2802 | insecure (unencrypted) passwords can be used. Encrypted passwords are |
Daniel Schneller | d06f31c | 2017-11-06 16:51:04 +0100 | [diff] [blame] | 2803 | evaluated using the crypt(3) function, so depending on the system's |
| 2804 | capabilities, different algorithms are supported. For example, modern Glibc |
| 2805 | based Linux systems support MD5, SHA-256, SHA-512, and, of course, the |
| 2806 | classic DES-based method of encrypting passwords. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2807 | |
Daniel Schneller | d06f31c | 2017-11-06 16:51:04 +0100 | [diff] [blame] | 2808 | Attention: Be aware that using encrypted passwords might cause significantly |
| 2809 | increased CPU usage, depending on the number of requests, and the algorithm |
| 2810 | used. For any of the hashed variants, the password for each request must |
| 2811 | be processed through the chosen algorithm, before it can be compared to the |
| 2812 | value specified in the config file. Most current algorithms are deliberately |
| 2813 | designed to be expensive to compute to achieve resistance against brute |
| 2814 | force attacks. They do not simply salt/hash the clear text password once, |
| 2815 | but thousands of times. This can quickly become a major factor in haproxy's |
| 2816 | overall CPU consumption! |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2817 | |
| 2818 | Example: |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2819 | userlist L1 |
| 2820 | group G1 users tiger,scott |
| 2821 | group G2 users xdb,scott |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2822 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2823 | user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91 |
| 2824 | user scott insecure-password elgato |
| 2825 | user xdb insecure-password hello |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2826 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2827 | userlist L2 |
| 2828 | group G1 |
| 2829 | group G2 |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2830 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 2831 | user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1 |
| 2832 | user scott insecure-password elgato groups G1,G2 |
| 2833 | user xdb insecure-password hello groups G2 |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 2834 | |
| 2835 | Please note that both lists are functionally identical. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 2836 | |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2837 | |
| 2838 | 3.5. Peers |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 2839 | ---------- |
Emeric Brun | 9490095 | 2015-06-11 18:25:54 +0200 | [diff] [blame] | 2840 | It is possible to propagate entries of any data-types in stick-tables between |
| 2841 | several haproxy instances over TCP connections in a multi-master fashion. Each |
| 2842 | instance pushes its local updates and insertions to remote peers. The pushed |
| 2843 | values overwrite remote ones without aggregation. Interrupted exchanges are |
| 2844 | automatically detected and recovered from the last known point. |
| 2845 | In addition, during a soft restart, the old process connects to the new one |
| 2846 | using such a TCP connection to push all its entries before the new process |
| 2847 | tries to connect to other peers. That ensures very fast replication during a |
| 2848 | reload, it typically takes a fraction of a second even for large tables. |
| 2849 | Note that Server IDs are used to identify servers remotely, so it is important |
| 2850 | that configurations look similar or at least that the same IDs are forced on |
| 2851 | each server on all participants. |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2852 | |
| 2853 | peers <peersect> |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 2854 | 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] | 2855 | which is referenced by one or more stick-tables. |
| 2856 | |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2857 | bind [<address>]:<port_range> [, ...] [param*] |
| 2858 | Defines the binding parameters of the local peer of this "peers" section. |
| 2859 | Such lines are not supported with "peer" line in the same "peers" section. |
| 2860 | |
Willy Tarreau | 77e4bd1 | 2015-05-01 20:02:17 +0200 | [diff] [blame] | 2861 | disabled |
| 2862 | Disables a peers section. It disables both listening and any synchronization |
| 2863 | related to this section. This is provided to disable synchronization of stick |
| 2864 | tables without having to comment out all "peers" references. |
| 2865 | |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2866 | default-bind [param*] |
| 2867 | Defines the binding parameters for the local peer, excepted its address. |
| 2868 | |
| 2869 | default-server [param*] |
| 2870 | Change default options for a server in a "peers" section. |
| 2871 | |
| 2872 | Arguments: |
| 2873 | <param*> is a list of parameters for this server. The "default-server" |
| 2874 | keyword accepts an important number of options and has a complete |
| 2875 | section dedicated to it. Please refer to section 5 for more |
| 2876 | details. |
| 2877 | |
| 2878 | |
| 2879 | See also: "server" and section 5 about server options |
| 2880 | |
Willy Tarreau | 77e4bd1 | 2015-05-01 20:02:17 +0200 | [diff] [blame] | 2881 | enable |
| 2882 | This re-enables a disabled peers section which was previously disabled. |
| 2883 | |
Jan Wagner | 3e67860 | 2020-12-17 22:22:32 +0100 | [diff] [blame] | 2884 | log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>] |
Frédéric Lécaille | b6f759b | 2019-11-05 09:57:45 +0100 | [diff] [blame] | 2885 | <facility> [<level> [<minlevel>]] |
| 2886 | "peers" sections support the same "log" keyword as for the proxies to |
| 2887 | log information about the "peers" listener. See "log" option for proxies for |
| 2888 | more details. |
| 2889 | |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2890 | peer <peername> <ip>:<port> [param*] |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2891 | Defines a peer inside a peers section. |
| 2892 | If <peername> is set to the local peer name (by default hostname, or forced |
Dragan Dosen | 13cd54c | 2020-06-18 18:24:05 +0200 | [diff] [blame] | 2893 | using "-L" command line option or "localpeer" global configuration setting), |
| 2894 | haproxy will listen for incoming remote peer connection on <ip>:<port>. |
| 2895 | Otherwise, <ip>:<port> defines where to connect to in order to join the |
| 2896 | remote peer, and <peername> is used at the protocol level to identify and |
| 2897 | validate the remote peer on the server side. |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2898 | |
| 2899 | During a soft restart, local peer <ip>:<port> is used by the old instance to |
| 2900 | connect the new one and initiate a complete replication (teaching process). |
| 2901 | |
| 2902 | It is strongly recommended to have the exact same peers declaration on all |
Dragan Dosen | 13cd54c | 2020-06-18 18:24:05 +0200 | [diff] [blame] | 2903 | peers and to only rely on the "-L" command line argument or the "localpeer" |
| 2904 | global configuration setting to change the local peer name. This makes it |
| 2905 | easier to maintain coherent configuration files across all peers. |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2906 | |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 2907 | You may want to reference some environment variables in the address |
| 2908 | parameter, see section 2.3 about environment variables. |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 2909 | |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2910 | Note: "peer" keyword may transparently be replaced by "server" keyword (see |
| 2911 | "server" keyword explanation below). |
| 2912 | |
| 2913 | server <peername> [<ip>:<port>] [param*] |
Michael Prokop | 4438c60 | 2019-05-24 10:25:45 +0200 | [diff] [blame] | 2914 | As previously mentioned, "peer" keyword may be replaced by "server" keyword |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2915 | with a support for all "server" parameters found in 5.2 paragraph. |
| 2916 | If the underlying peer is local, <ip>:<port> parameters must not be present. |
| 2917 | These parameters must be provided on a "bind" line (see "bind" keyword |
| 2918 | of this "peers" section). |
| 2919 | Some of these parameters are irrelevant for "peers" sections. |
| 2920 | |
| 2921 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 2922 | Example: |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2923 | # The old way. |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2924 | peers mypeers |
Willy Tarreau | f7b30a9 | 2010-12-06 22:59:17 +0100 | [diff] [blame] | 2925 | peer haproxy1 192.168.0.1:1024 |
| 2926 | peer haproxy2 192.168.0.2:1024 |
| 2927 | peer haproxy3 10.2.0.1:1024 |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2928 | |
| 2929 | backend mybackend |
| 2930 | mode tcp |
| 2931 | balance roundrobin |
| 2932 | stick-table type ip size 20k peers mypeers |
| 2933 | stick on src |
| 2934 | |
Willy Tarreau | f7b30a9 | 2010-12-06 22:59:17 +0100 | [diff] [blame] | 2935 | server srv1 192.168.0.30:80 |
| 2936 | server srv2 192.168.0.31:80 |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2937 | |
Frédéric Lécaille | 2f167b3 | 2019-01-11 14:13:54 +0100 | [diff] [blame] | 2938 | Example: |
| 2939 | peers mypeers |
| 2940 | bind 127.0.0.11:10001 ssl crt mycerts/pem |
| 2941 | default-server ssl verify none |
| 2942 | server hostA 127.0.0.10:10000 |
| 2943 | server hostB #local peer |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 2944 | |
Frédéric Lécaille | 4f5b77c | 2019-03-18 14:05:58 +0100 | [diff] [blame] | 2945 | |
| 2946 | table <tablename> type {ip | integer | string [len <length>] | binary [len <length>]} |
| 2947 | size <size> [expire <expire>] [nopurge] [store <data_type>]* |
| 2948 | |
| 2949 | Configure a stickiness table for the current section. This line is parsed |
| 2950 | exactly the same way as the "stick-table" keyword in others section, except |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 2951 | for the "peers" argument which is not required here and with an additional |
Frédéric Lécaille | 4f5b77c | 2019-03-18 14:05:58 +0100 | [diff] [blame] | 2952 | mandatory first parameter to designate the stick-table. Contrary to others |
| 2953 | sections, there may be several "table" lines in "peers" sections (see also |
| 2954 | "stick-table" keyword). |
| 2955 | |
| 2956 | Also be aware of the fact that "peers" sections have their own stick-table |
| 2957 | namespaces to avoid collisions between stick-table names identical in |
| 2958 | different "peers" section. This is internally handled prepending the "peers" |
| 2959 | sections names to the name of the stick-tables followed by a '/' character. |
| 2960 | If somewhere else in the configuration file you have to refer to such |
| 2961 | stick-tables declared in "peers" sections you must use the prefixed version |
| 2962 | of the stick-table name as follows: |
| 2963 | |
| 2964 | peers mypeers |
| 2965 | peer A ... |
| 2966 | peer B ... |
| 2967 | table t1 ... |
| 2968 | |
| 2969 | frontend fe1 |
| 2970 | tcp-request content track-sc0 src table mypeers/t1 |
| 2971 | |
| 2972 | This is also this prefixed version of the stick-table names which must be |
| 2973 | used to refer to stick-tables through the CLI. |
| 2974 | |
| 2975 | About "peers" protocol, as only "peers" belonging to the same section may |
| 2976 | communicate with each others, there is no need to do such a distinction. |
| 2977 | Several "peers" sections may declare stick-tables with the same name. |
| 2978 | This is shorter version of the stick-table name which is sent over the network. |
| 2979 | There is only a '/' character as prefix to avoid stick-table name collisions between |
| 2980 | stick-tables declared as backends and stick-table declared in "peers" sections |
| 2981 | as follows in this weird but supported configuration: |
| 2982 | |
| 2983 | peers mypeers |
| 2984 | peer A ... |
| 2985 | peer B ... |
| 2986 | table t1 type string size 10m store gpc0 |
| 2987 | |
| 2988 | backend t1 |
| 2989 | stick-table type string size 10m store gpc0 peers mypeers |
| 2990 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 2991 | Here "t1" table declared in "mypeers" section has "mypeers/t1" as global name. |
Frédéric Lécaille | 4f5b77c | 2019-03-18 14:05:58 +0100 | [diff] [blame] | 2992 | "t1" table declared as a backend as "t1" as global name. But at peer protocol |
| 2993 | level the former table is named "/t1", the latter is again named "t1". |
| 2994 | |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 2995 | 3.6. Mailers |
| 2996 | ------------ |
| 2997 | It is possible to send email alerts when the state of servers changes. |
| 2998 | If configured email alerts are sent to each mailer that is configured |
| 2999 | in a mailers section. Email is sent to mailers using SMTP. |
| 3000 | |
Pieter Baauw | 386a127 | 2015-08-16 15:26:24 +0200 | [diff] [blame] | 3001 | mailers <mailersect> |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 3002 | Creates a new mailer list with the name <mailersect>. It is an |
| 3003 | independent section which is referenced by one or more proxies. |
| 3004 | |
| 3005 | mailer <mailername> <ip>:<port> |
| 3006 | Defines a mailer inside a mailers section. |
| 3007 | |
| 3008 | Example: |
| 3009 | mailers mymailers |
| 3010 | mailer smtp1 192.168.0.1:587 |
| 3011 | mailer smtp2 192.168.0.2:587 |
| 3012 | |
| 3013 | backend mybackend |
| 3014 | mode tcp |
| 3015 | balance roundrobin |
| 3016 | |
| 3017 | email-alert mailers mymailers |
| 3018 | email-alert from test1@horms.org |
| 3019 | email-alert to test2@horms.org |
| 3020 | |
| 3021 | server srv1 192.168.0.30:80 |
| 3022 | server srv2 192.168.0.31:80 |
| 3023 | |
Pieter Baauw | 235fcfc | 2016-02-13 15:33:40 +0100 | [diff] [blame] | 3024 | timeout mail <time> |
| 3025 | Defines the time available for a mail/connection to be made and send to |
| 3026 | the mail-server. If not defined the default value is 10 seconds. To allow |
| 3027 | for at least two SYN-ACK packets to be send during initial TCP handshake it |
| 3028 | is advised to keep this value above 4 seconds. |
| 3029 | |
| 3030 | Example: |
| 3031 | mailers mymailers |
| 3032 | timeout mail 20s |
| 3033 | mailer smtp1 192.168.0.1:587 |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 3034 | |
William Lallemand | c951552 | 2019-06-12 16:32:11 +0200 | [diff] [blame] | 3035 | 3.7. Programs |
| 3036 | ------------- |
| 3037 | In master-worker mode, it is possible to launch external binaries with the |
| 3038 | master, these processes are called programs. These programs are launched and |
| 3039 | managed the same way as the workers. |
| 3040 | |
| 3041 | During a reload of HAProxy, those processes are dealing with the same |
| 3042 | sequence as a worker: |
| 3043 | |
| 3044 | - the master is re-executed |
| 3045 | - the master sends a SIGUSR1 signal to the program |
| 3046 | - if "option start-on-reload" is not disabled, the master launches a new |
| 3047 | instance of the program |
| 3048 | |
| 3049 | During a stop, or restart, a SIGTERM is sent to the programs. |
| 3050 | |
| 3051 | program <name> |
| 3052 | This is a new program section, this section will create an instance <name> |
| 3053 | which is visible in "show proc" on the master CLI. (See "9.4. Master CLI" in |
| 3054 | the management guide). |
| 3055 | |
| 3056 | command <command> [arguments*] |
| 3057 | Define the command to start with optional arguments. The command is looked |
| 3058 | up in the current PATH if it does not include an absolute path. This is a |
| 3059 | mandatory option of the program section. Arguments containing spaces must |
| 3060 | be enclosed in quotes or double quotes or be prefixed by a backslash. |
| 3061 | |
Andrew Heberle | 9723696 | 2019-07-12 11:50:26 +0800 | [diff] [blame] | 3062 | user <user name> |
| 3063 | Changes the executed command user ID to the <user name> from /etc/passwd. |
| 3064 | See also "group". |
| 3065 | |
| 3066 | group <group name> |
| 3067 | Changes the executed command group ID to the <group name> from /etc/group. |
| 3068 | See also "user". |
| 3069 | |
William Lallemand | c951552 | 2019-06-12 16:32:11 +0200 | [diff] [blame] | 3070 | option start-on-reload |
| 3071 | no option start-on-reload |
| 3072 | Start (or not) a new instance of the program upon a reload of the master. |
| 3073 | The default is to start a new instance. This option may only be used in a |
| 3074 | program section. |
| 3075 | |
| 3076 | |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 3077 | 3.8. HTTP-errors |
| 3078 | ---------------- |
| 3079 | |
| 3080 | It is possible to globally declare several groups of HTTP errors, to be |
| 3081 | imported afterwards in any proxy section. Same group may be referenced at |
| 3082 | several places and can be fully or partially imported. |
| 3083 | |
| 3084 | http-errors <name> |
| 3085 | Create a new http-errors group with the name <name>. It is an independent |
| 3086 | section that may be referenced by one or more proxies using its name. |
| 3087 | |
| 3088 | errorfile <code> <file> |
| 3089 | Associate a file contents to an HTTP error code |
| 3090 | |
| 3091 | Arguments : |
| 3092 | <code> is the HTTP status code. Currently, HAProxy is capable of |
Christopher Faulet | 612f2ea | 2020-05-27 09:57:28 +0200 | [diff] [blame] | 3093 | generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 3094 | 425, 429, 500, 501, 502, 503, and 504. |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 3095 | |
| 3096 | <file> designates a file containing the full HTTP response. It is |
| 3097 | recommended to follow the common practice of appending ".http" to |
| 3098 | the filename so that people do not confuse the response with HTML |
| 3099 | error pages, and to use absolute paths, since files are read |
| 3100 | before any chroot is performed. |
| 3101 | |
| 3102 | Please referrers to "errorfile" keyword in section 4 for details. |
| 3103 | |
| 3104 | Example: |
| 3105 | http-errors website-1 |
| 3106 | errorfile 400 /etc/haproxy/errorfiles/site1/400.http |
| 3107 | errorfile 404 /etc/haproxy/errorfiles/site1/404.http |
| 3108 | errorfile 408 /dev/null # work around Chrome pre-connect bug |
| 3109 | |
| 3110 | http-errors website-2 |
| 3111 | errorfile 400 /etc/haproxy/errorfiles/site2/400.http |
| 3112 | errorfile 404 /etc/haproxy/errorfiles/site2/404.http |
| 3113 | errorfile 408 /dev/null # work around Chrome pre-connect bug |
| 3114 | |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3115 | 3.9. Rings |
| 3116 | ---------- |
| 3117 | |
| 3118 | It is possible to globally declare ring-buffers, to be used as target for log |
| 3119 | servers or traces. |
| 3120 | |
| 3121 | ring <ringname> |
| 3122 | Creates a new ring-buffer with name <ringname>. |
| 3123 | |
| 3124 | description <text> |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 3125 | The description is an optional description string of the ring. It will |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3126 | appear on CLI. By default, <name> is reused to fill this field. |
| 3127 | |
| 3128 | format <format> |
| 3129 | Format used to store events into the ring buffer. |
| 3130 | |
| 3131 | Arguments: |
| 3132 | <format> is the log format used when generating syslog messages. It may be |
| 3133 | one of the following : |
| 3134 | |
| 3135 | iso A message containing only the ISO date, followed by the text. |
| 3136 | The PID, process name and system name are omitted. This is |
| 3137 | designed to be used with a local log server. |
| 3138 | |
Emeric Brun | 0237c4e | 2020-11-27 16:24:34 +0100 | [diff] [blame] | 3139 | local Analog to rfc3164 syslog message format except that hostname |
| 3140 | field is stripped. This is the default. |
| 3141 | Note: option "log-send-hostname" switches the default to |
| 3142 | rfc3164. |
| 3143 | |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3144 | raw A message containing only the text. The level, PID, date, time, |
| 3145 | process name and system name are omitted. This is designed to be |
| 3146 | used in containers or during development, where the severity |
| 3147 | only depends on the file descriptor used (stdout/stderr). This |
| 3148 | is the default. |
| 3149 | |
Emeric Brun | 0237c4e | 2020-11-27 16:24:34 +0100 | [diff] [blame] | 3150 | rfc3164 The RFC3164 syslog message format. |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3151 | (https://tools.ietf.org/html/rfc3164) |
| 3152 | |
| 3153 | rfc5424 The RFC5424 syslog message format. |
| 3154 | (https://tools.ietf.org/html/rfc5424) |
| 3155 | |
| 3156 | short A message containing only a level between angle brackets such as |
| 3157 | '<3>', followed by the text. The PID, date, time, process name |
| 3158 | and system name are omitted. This is designed to be used with a |
| 3159 | local log server. This format is compatible with what the systemd |
| 3160 | logger consumes. |
| 3161 | |
Emeric Brun | 5464885 | 2020-07-06 15:54:06 +0200 | [diff] [blame] | 3162 | priority A message containing only a level plus syslog facility between angle |
| 3163 | brackets such as '<63>', followed by the text. The PID, date, time, |
| 3164 | process name and system name are omitted. This is designed to be used |
| 3165 | with a local log server. |
| 3166 | |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3167 | timed A message containing only a level between angle brackets such as |
| 3168 | '<3>', followed by ISO date and by the text. The PID, process |
| 3169 | name and system name are omitted. This is designed to be |
| 3170 | used with a local log server. |
| 3171 | |
| 3172 | maxlen <length> |
| 3173 | The maximum length of an event message stored into the ring, |
| 3174 | including formatted header. If an event message is longer than |
| 3175 | <length>, it will be truncated to this length. |
| 3176 | |
Emeric Brun | 494c505 | 2020-05-28 11:13:15 +0200 | [diff] [blame] | 3177 | server <name> <address> [param*] |
| 3178 | Used to configure a syslog tcp server to forward messages from ring buffer. |
| 3179 | This supports for all "server" parameters found in 5.2 paragraph. Some of |
| 3180 | these parameters are irrelevant for "ring" sections. Important point: there |
| 3181 | is little reason to add more than one server to a ring, because all servers |
| 3182 | will receive the exact same copy of the ring contents, and as such the ring |
| 3183 | will progress at the speed of the slowest server. If one server does not |
| 3184 | respond, it will prevent old messages from being purged and may block new |
| 3185 | messages from being inserted into the ring. The proper way to send messages |
| 3186 | to multiple servers is to use one distinct ring per log server, not to |
Emeric Brun | 9755647 | 2020-05-30 01:42:45 +0200 | [diff] [blame] | 3187 | attach multiple servers to the same ring. Note that specific server directive |
| 3188 | "log-proto" is used to set the protocol used to send messages. |
Emeric Brun | 494c505 | 2020-05-28 11:13:15 +0200 | [diff] [blame] | 3189 | |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3190 | size <size> |
| 3191 | This is the optional size in bytes for the ring-buffer. Default value is |
| 3192 | set to BUFSIZE. |
| 3193 | |
Emeric Brun | 494c505 | 2020-05-28 11:13:15 +0200 | [diff] [blame] | 3194 | timeout connect <timeout> |
| 3195 | Set the maximum time to wait for a connection attempt to a server to succeed. |
| 3196 | |
| 3197 | Arguments : |
| 3198 | <timeout> is the timeout value specified in milliseconds by default, but |
| 3199 | can be in any other unit if the number is suffixed by the unit, |
| 3200 | as explained at the top of this document. |
| 3201 | |
| 3202 | timeout server <timeout> |
| 3203 | Set the maximum time for pending data staying into output buffer. |
| 3204 | |
| 3205 | Arguments : |
| 3206 | <timeout> is the timeout value specified in milliseconds by default, but |
| 3207 | can be in any other unit if the number is suffixed by the unit, |
| 3208 | as explained at the top of this document. |
| 3209 | |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3210 | Example: |
| 3211 | global |
| 3212 | log ring@myring local7 |
| 3213 | |
| 3214 | ring myring |
| 3215 | description "My local buffer" |
| 3216 | format rfc3164 |
| 3217 | maxlen 1200 |
| 3218 | size 32764 |
Emeric Brun | 494c505 | 2020-05-28 11:13:15 +0200 | [diff] [blame] | 3219 | timeout connect 5s |
| 3220 | timeout server 10s |
Emeric Brun | 9755647 | 2020-05-30 01:42:45 +0200 | [diff] [blame] | 3221 | server mysyslogsrv 127.0.0.1:6514 log-proto octet-count |
Emeric Brun | 99c453d | 2020-05-25 15:01:04 +0200 | [diff] [blame] | 3222 | |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3223 | 3.10. Log forwarding |
| 3224 | ------------------- |
| 3225 | |
| 3226 | It is possible to declare one or multiple log forwarding section, |
| 3227 | haproxy will forward all received log messages to a log servers list. |
| 3228 | |
| 3229 | log-forward <name> |
| 3230 | Creates a new log forwarder proxy identified as <name>. |
| 3231 | |
Emeric Brun | cbb7bf7 | 2020-10-05 14:39:35 +0200 | [diff] [blame] | 3232 | backlog <conns> |
| 3233 | Give hints to the system about the approximate listen backlog desired size |
| 3234 | on connections accept. |
| 3235 | |
| 3236 | bind <addr> [param*] |
| 3237 | Used to configure a stream log listener to receive messages to forward. |
Emeric Brun | da46c1c | 2020-10-08 08:39:02 +0200 | [diff] [blame] | 3238 | This supports the "bind" parameters found in 5.1 paragraph including |
| 3239 | those about ssl but some statements such as "alpn" may be irrelevant for |
| 3240 | syslog protocol over TCP. |
| 3241 | Those listeners support both "Octet Counting" and "Non-Transparent-Framing" |
Emeric Brun | cbb7bf7 | 2020-10-05 14:39:35 +0200 | [diff] [blame] | 3242 | modes as defined in rfc-6587. |
| 3243 | |
Willy Tarreau | 76aaa7f | 2020-09-16 15:07:22 +0200 | [diff] [blame] | 3244 | dgram-bind <addr> [param*] |
Emeric Brun | cbb7bf7 | 2020-10-05 14:39:35 +0200 | [diff] [blame] | 3245 | Used to configure a datagram log listener to receive messages to forward. |
| 3246 | Addresses must be in IPv4 or IPv6 form,followed by a port. This supports |
| 3247 | for some of the "bind" parameters found in 5.1 paragraph among which |
| 3248 | "interface", "namespace" or "transparent", the other ones being |
Willy Tarreau | 26ff5da | 2020-09-16 15:22:19 +0200 | [diff] [blame] | 3249 | silently ignored as irrelevant for UDP/syslog case. |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3250 | |
| 3251 | log global |
Jan Wagner | 3e67860 | 2020-12-17 22:22:32 +0100 | [diff] [blame] | 3252 | log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>] |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3253 | <facility> [<level> [<minlevel>]] |
| 3254 | Used to configure target log servers. See more details on proxies |
| 3255 | documentation. |
| 3256 | If no format specified, haproxy tries to keep the incoming log format. |
| 3257 | Configured facility is ignored, except if incoming message does not |
| 3258 | present a facility but one is mandatory on the outgoing format. |
| 3259 | If there is no timestamp available in the input format, but the field |
| 3260 | exists in output format, haproxy will use the local date. |
| 3261 | |
| 3262 | Example: |
| 3263 | global |
| 3264 | log stderr format iso local7 |
| 3265 | |
| 3266 | ring myring |
| 3267 | description "My local buffer" |
| 3268 | format rfc5424 |
| 3269 | maxlen 1200 |
| 3270 | size 32764 |
| 3271 | timeout connect 5s |
| 3272 | timeout server 10s |
| 3273 | # syslog tcp server |
| 3274 | server mysyslogsrv 127.0.0.1:514 log-proto octet-count |
| 3275 | |
| 3276 | log-forward sylog-loadb |
Emeric Brun | cbb7bf7 | 2020-10-05 14:39:35 +0200 | [diff] [blame] | 3277 | dgram-bind 127.0.0.1:1514 |
| 3278 | bind 127.0.0.1:1514 |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3279 | # all messages on stderr |
| 3280 | log global |
| 3281 | # all messages on local tcp syslog server |
| 3282 | log ring@myring local0 |
| 3283 | # load balance messages on 4 udp syslog servers |
| 3284 | log 127.0.0.1:10001 sample 1:4 local0 |
| 3285 | log 127.0.0.1:10002 sample 2:4 local0 |
| 3286 | log 127.0.0.1:10003 sample 3:4 local0 |
| 3287 | log 127.0.0.1:10004 sample 4:4 local0 |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 3288 | |
Emeric Brun | cbb7bf7 | 2020-10-05 14:39:35 +0200 | [diff] [blame] | 3289 | maxconn <conns> |
| 3290 | Fix the maximum number of concurrent connections on a log forwarder. |
| 3291 | 10 is the default. |
| 3292 | |
| 3293 | timeout client <timeout> |
| 3294 | Set the maximum inactivity time on the client side. |
| 3295 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3296 | 4. Proxies |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3297 | ---------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3298 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3299 | Proxy configuration can be located in a set of sections : |
Willy Tarreau | 7c0b4d8 | 2021-02-12 14:58:08 +0100 | [diff] [blame] | 3300 | - defaults [<name>] [ from <defaults_name> ] |
| 3301 | - frontend <name> [ from <defaults_name> ] |
| 3302 | - backend <name> [ from <defaults_name> ] |
| 3303 | - listen <name> [ from <defaults_name> ] |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3304 | |
| 3305 | A "frontend" section describes a set of listening sockets accepting client |
| 3306 | connections. |
| 3307 | |
| 3308 | A "backend" section describes a set of servers to which the proxy will connect |
| 3309 | to forward incoming connections. |
| 3310 | |
| 3311 | A "listen" section defines a complete proxy with its frontend and backend |
| 3312 | parts combined in one section. It is generally useful for TCP-only traffic. |
| 3313 | |
Willy Tarreau | 7c0b4d8 | 2021-02-12 14:58:08 +0100 | [diff] [blame] | 3314 | A "defaults" section resets all settings to the documented ones and presets new |
| 3315 | ones for use by subsequent sections. All of "frontend", "backend" and "listen" |
| 3316 | sections always take their initial settings from a defaults section, by default |
| 3317 | the latest one that appears before the newly created section. It is possible to |
| 3318 | explicitly designate a specific "defaults" section to load the initial settings |
| 3319 | from by indicating its name on the section line after the optional keyword |
| 3320 | "from". While "defaults" section do not impose a name, this use is encouraged |
| 3321 | for better readability. It is also the only way to designate a specific section |
| 3322 | to use instead of the default previous one. Since "defaults" section names are |
| 3323 | optional, by default a very permissive check is applied on their name and these |
| 3324 | are even permitted to overlap. However if a "defaults" section is referenced by |
| 3325 | any other section, its name must comply with the syntax imposed on all proxy |
| 3326 | names, and this name must be unique among the defaults sections. Please note |
| 3327 | that regardless of what is currently permitted, it is recommended to avoid |
| 3328 | duplicate section names in general and to respect the same syntax as for proxy |
| 3329 | names. This rule might be enforced in a future version. |
| 3330 | |
| 3331 | Note that it is even possible for a defaults section to take its initial |
| 3332 | settings from another one, and as such, inherit settings across multiple levels |
| 3333 | of defaults sections. This can be convenient to establish certain configuration |
| 3334 | profiles to carry groups of default settings (e.g. TCP vs HTTP or short vs long |
| 3335 | timeouts) but can quickly become confusing to follow. |
| 3336 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3337 | All proxy names must be formed from upper and lower case letters, digits, |
| 3338 | '-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are |
| 3339 | case-sensitive, which means that "www" and "WWW" are two different proxies. |
| 3340 | |
| 3341 | Historically, all proxy names could overlap, it just caused troubles in the |
| 3342 | logs. Since the introduction of content switching, it is mandatory that two |
| 3343 | proxies with overlapping capabilities (frontend/backend) have different names. |
| 3344 | However, it is still permitted that a frontend and a backend share the same |
| 3345 | name, as this configuration seems to be commonly encountered. |
| 3346 | |
| 3347 | Right now, two major proxy modes are supported : "tcp", also known as layer 4, |
| 3348 | 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] | 3349 | bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3350 | protocol, and can interact with it by allowing, blocking, switching, adding, |
| 3351 | modifying, or removing arbitrary contents in requests or responses, based on |
| 3352 | arbitrary criteria. |
| 3353 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3354 | In HTTP mode, the processing applied to requests and responses flowing over |
| 3355 | a connection depends in the combination of the frontend's HTTP options and |
Julien Pivotto | 21ad315 | 2019-12-10 13:11:17 +0100 | [diff] [blame] | 3356 | the backend's. HAProxy supports 3 connection modes : |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3357 | |
| 3358 | - KAL : keep alive ("option http-keep-alive") which is the default mode : all |
| 3359 | requests and responses are processed, and connections remain open but idle |
| 3360 | between responses and new requests. |
| 3361 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3362 | - SCL: server close ("option http-server-close") : the server-facing |
| 3363 | connection is closed after the end of the response is received, but the |
| 3364 | client-facing connection remains open. |
| 3365 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 3366 | - CLO: close ("option httpclose"): the connection is closed after the end of |
| 3367 | the response and "Connection: close" appended in both directions. |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3368 | |
| 3369 | The effective mode that will be applied to a connection passing through a |
| 3370 | frontend and a backend can be determined by both proxy modes according to the |
| 3371 | following matrix, but in short, the modes are symmetric, keep-alive is the |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 3372 | weakest option and close is the strongest. |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3373 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 3374 | Backend mode |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3375 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 3376 | | KAL | SCL | CLO |
| 3377 | ----+-----+-----+---- |
| 3378 | KAL | KAL | SCL | CLO |
| 3379 | ----+-----+-----+---- |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 3380 | mode SCL | SCL | SCL | CLO |
| 3381 | ----+-----+-----+---- |
| 3382 | CLO | CLO | CLO | CLO |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3383 | |
Christopher Faulet | 4d37e53 | 2021-03-26 14:44:00 +0100 | [diff] [blame] | 3384 | It is possible to chain a TCP frontend to an HTTP backend. It is pointless if |
| 3385 | only HTTP traffic is handled. But It may be used to handle several protocols |
| 3386 | into the same frontend. It this case, the client's connection is first handled |
| 3387 | as a raw tcp connection before being upgraded to HTTP. Before the upgrade, the |
| 3388 | content processings are performend on raw data. Once upgraded, data are parsed |
| 3389 | and stored using an internal representation called HTX and it is no longer |
| 3390 | possible to rely on raw representation. There is no way to go back. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3391 | |
Christopher Faulet | 4d37e53 | 2021-03-26 14:44:00 +0100 | [diff] [blame] | 3392 | There are two kind of upgrades, in-place upgrades and destructive upgrades. The |
| 3393 | first ones concern the TCP to HTTP/1 upgrades. In HTTP/1, the request |
| 3394 | processings are serialized, thus the applicative stream can be preserved. The |
| 3395 | second ones concern the TCP to HTTP/2 upgrades. Because it is a multiplexed |
| 3396 | protocol, the applicative stream cannot be associated to any HTTP/2 stream and |
| 3397 | is destroyed. New applicative streams are then created when HAProxy receives |
| 3398 | new HTTP/2 streams at the lower level, in the H2 multiplexer. It is important |
| 3399 | to understand this difference because that drastically change the way to |
| 3400 | process data. When an HTTP/1 upgrade is performed, the content processings |
| 3401 | already performed on raw data are neither lost nor reexecuted while for an |
| 3402 | HTTP/2 upgrade, applicative streams are distinct and all frontend rules are |
| 3403 | evaluated systematically on each one. And as said, the first stream, the TCP |
| 3404 | one, is destroyed, but only after the frontend rules were evaluated. |
| 3405 | |
| 3406 | There is another importnat point to understand when HTTP processings are |
| 3407 | performed from a TCP proxy. While HAProxy is able to parse HTTP/1 in-fly from |
| 3408 | tcp-request content rules, it is not possible for HTTP/2. Only the HTTP/2 |
| 3409 | preface can be parsed. This is a huge limitation regarding the HTTP content |
| 3410 | analysis in TCP. Concretely it is only possible to know if received data are |
| 3411 | HTTP. For instance, it is not possible to choose a backend based on the Host |
| 3412 | header value while it is trivial in HTTP/1. Hopefully, there is a solution to |
| 3413 | mitigate this drawback. |
| 3414 | |
| 3415 | It exists two way to perform HTTP upgrades. The first one, the historical |
| 3416 | method, is to select an HTTP backend. The upgrade happens when the backend is |
| 3417 | set. Thus, for in-place upgrades, only the backend configuration is considered |
| 3418 | in the HTTP data processing. For destructive upgrades, the applicative stream |
| 3419 | is destroyed, thus its processing is stopped. With this method, possibilities |
| 3420 | to choose a backend with an HTTP/2 connection are really limited, as mentioned |
| 3421 | above, and a bit useless because the stream is destroyed. The second method is |
| 3422 | to upgrade during the tcp-request content rules evaluation, thanks to the |
| 3423 | "switch-mode http" action. In this case, the upgrade is performed in the |
| 3424 | frontend context and it is possible to define HTTP directives in this |
| 3425 | frontend. For in-place upgrades, it offers all the power of the HTTP analysis |
| 3426 | as soon as possible. It is not that far from an HTTP frontend. For destructive |
| 3427 | upgrades, it does not change anything except it is useless to choose a backend |
| 3428 | on limited information. It is of course the recommended method. Thus, testing |
| 3429 | the request protocol from the tcp-request content rules to perform an HTTP |
| 3430 | upgrade is enough. All the remaining HTTP manipulation may be moved to the |
| 3431 | frontend http-request ruleset. But keep in mind that tcp-request content rules |
| 3432 | remains evaluated on each streams, that can't be changed. |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 3433 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3434 | 4.1. Proxy keywords matrix |
| 3435 | -------------------------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3436 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3437 | The following list of keywords is supported. Most of them may only be used in a |
| 3438 | limited set of section types. Some of them are marked as "deprecated" because |
| 3439 | they are inherited from an old syntax which may be confusing or functionally |
| 3440 | limited, and there are new recommended keywords to replace them. Keywords |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 3441 | marked with "(*)" can be optionally inverted using the "no" prefix, e.g. "no |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3442 | 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] | 3443 | and must be disabled for a specific instance. Such options may also be prefixed |
| 3444 | with "default" in order to restore default settings regardless of what has been |
| 3445 | specified in a previous "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3446 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3447 | |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3448 | keyword defaults frontend listen backend |
| 3449 | ------------------------------------+----------+----------+---------+--------- |
| 3450 | acl - X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3451 | backlog X X X - |
| 3452 | balance X - X X |
| 3453 | bind - X X - |
| 3454 | bind-process X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3455 | capture cookie - X X - |
| 3456 | capture request header - X X - |
| 3457 | capture response header - X X - |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 3458 | clitcpka-cnt X X X - |
| 3459 | clitcpka-idle X X X - |
| 3460 | clitcpka-intvl X X X - |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 3461 | compression X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3462 | cookie X - X X |
Thierry FOURNIER | a0a1b75 | 2015-05-26 17:44:32 +0200 | [diff] [blame] | 3463 | declare capture - X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3464 | default-server X - X X |
| 3465 | default_backend X X X - |
| 3466 | description - X X X |
| 3467 | disabled X X X X |
| 3468 | dispatch - - X X |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 3469 | email-alert from X X X X |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 3470 | email-alert level X X X X |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 3471 | email-alert mailers X X X X |
| 3472 | email-alert myhostname X X X X |
| 3473 | email-alert to X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3474 | enabled X X X X |
| 3475 | errorfile X X X X |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 3476 | errorfiles X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3477 | errorloc X X X X |
| 3478 | errorloc302 X X X X |
| 3479 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 3480 | errorloc303 X X X X |
Cyril Bonté | 4288c5a | 2018-03-12 22:02:59 +0100 | [diff] [blame] | 3481 | force-persist - - X X |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 3482 | filter - X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3483 | fullconn X - X X |
| 3484 | grace X X X X |
| 3485 | hash-type X - X X |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 3486 | http-after-response - X X X |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 3487 | http-check comment X - X X |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 3488 | http-check connect X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3489 | http-check disable-on-404 X - X X |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 3490 | http-check expect X - X X |
Peter Gervai | 8912ae6 | 2020-06-11 18:26:36 +0200 | [diff] [blame] | 3491 | http-check send X - X X |
Willy Tarreau | 7ab6aff | 2010-10-12 06:30:16 +0200 | [diff] [blame] | 3492 | http-check send-state X - X X |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 3493 | http-check set-var X - X X |
| 3494 | http-check unset-var X - X X |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 3495 | http-error X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3496 | http-request - X X X |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 3497 | http-response - X X X |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 3498 | http-reuse X - X X |
Baptiste Assmann | 2c42ef5 | 2013-10-09 21:57:02 +0200 | [diff] [blame] | 3499 | http-send-name-header - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3500 | id - X X X |
Cyril Bonté | 4288c5a | 2018-03-12 22:02:59 +0100 | [diff] [blame] | 3501 | ignore-persist - - X X |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 3502 | load-server-state-from-file X - X X |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 3503 | log (*) X X X X |
Willy Tarreau | fb4e7ea | 2015-01-07 14:55:17 +0100 | [diff] [blame] | 3504 | log-format X X X - |
Dragan Dosen | 7ad3154 | 2015-09-28 17:16:47 +0200 | [diff] [blame] | 3505 | log-format-sd X X X - |
Willy Tarreau | 094af4e | 2015-01-07 15:03:42 +0100 | [diff] [blame] | 3506 | log-tag X X X X |
Willy Tarreau | c35362a | 2014-04-25 13:58:37 +0200 | [diff] [blame] | 3507 | max-keep-alive-queue X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3508 | maxconn X X X - |
| 3509 | mode X X X X |
| 3510 | monitor fail - X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3511 | monitor-uri X X X - |
| 3512 | option abortonclose (*) X - X X |
| 3513 | option accept-invalid-http-request (*) X X X - |
| 3514 | option accept-invalid-http-response (*) X - X X |
| 3515 | option allbackups (*) X - X X |
| 3516 | option checkcache (*) X - X X |
| 3517 | option clitcpka (*) X X X - |
| 3518 | option contstats (*) X X X - |
Christopher Faulet | 89aed32 | 2020-06-02 17:33:56 +0200 | [diff] [blame] | 3519 | option disable-h2-upgrade (*) X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3520 | option dontlog-normal (*) X X X - |
| 3521 | option dontlognull (*) X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3522 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 3523 | option forwardfor X X X X |
Christopher Faulet | 98fbe95 | 2019-07-22 16:18:24 +0200 | [diff] [blame] | 3524 | option h1-case-adjust-bogus-client (*) X X X - |
| 3525 | option h1-case-adjust-bogus-server (*) X - X X |
Willy Tarreau | 9fbe18e | 2015-05-01 22:42:08 +0200 | [diff] [blame] | 3526 | option http-buffer-request (*) X X X X |
Willy Tarreau | 82649f9 | 2015-05-01 22:40:51 +0200 | [diff] [blame] | 3527 | option http-ignore-probes (*) X X X - |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 3528 | option http-keep-alive (*) X X X X |
Willy Tarreau | 96e3121 | 2011-05-30 18:10:30 +0200 | [diff] [blame] | 3529 | option http-no-delay (*) X X X X |
Christopher Faulet | 98db976 | 2018-09-21 10:25:19 +0200 | [diff] [blame] | 3530 | option http-pretend-keepalive (*) X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3531 | option http-server-close (*) X X X X |
| 3532 | option http-use-proxy-header (*) X X X - |
| 3533 | option httpchk X - X X |
| 3534 | option httpclose (*) X X X X |
Freddy Spierenburg | e88b773 | 2019-03-25 14:35:17 +0100 | [diff] [blame] | 3535 | option httplog X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3536 | option http_proxy (*) X X X X |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 3537 | option independent-streams (*) X X X X |
Gabor Lekeny | b4c81e4 | 2010-09-29 18:17:05 +0200 | [diff] [blame] | 3538 | option ldap-check X - X X |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 3539 | option external-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3540 | option log-health-checks (*) X - X X |
| 3541 | option log-separate-errors (*) X X X - |
| 3542 | option logasap (*) X X X - |
| 3543 | option mysql-check X - X X |
| 3544 | option nolinger (*) X X X X |
| 3545 | option originalto X X X X |
| 3546 | option persist (*) X - X X |
Baptiste Assmann | 809e22a | 2015-10-12 20:22:55 +0200 | [diff] [blame] | 3547 | option pgsql-check X - X X |
| 3548 | option prefer-last-server (*) X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3549 | option redispatch (*) X - X X |
Hervé COMMOWICK | ec032d6 | 2011-08-05 16:23:48 +0200 | [diff] [blame] | 3550 | option redis-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3551 | option smtpchk X - X X |
| 3552 | option socket-stats (*) X X X - |
| 3553 | option splice-auto (*) X X X X |
| 3554 | option splice-request (*) X X X X |
| 3555 | option splice-response (*) X X X X |
Christopher Faulet | ba7bc16 | 2016-11-07 21:07:38 +0100 | [diff] [blame] | 3556 | option spop-check - - - X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3557 | option srvtcpka (*) X - X X |
| 3558 | option ssl-hello-chk X - X X |
| 3559 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 3560 | option tcp-check X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3561 | option tcp-smart-accept (*) X X X - |
| 3562 | option tcp-smart-connect (*) X - X X |
| 3563 | option tcpka X X X X |
| 3564 | option tcplog X X X X |
| 3565 | option transparent (*) X - X X |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 3566 | external-check command X - X X |
| 3567 | external-check path X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3568 | persist rdp-cookie X - X X |
| 3569 | rate-limit sessions X X X - |
| 3570 | redirect - X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3571 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3572 | retries X - X X |
Olivier Houchard | a254a37 | 2019-04-05 15:30:12 +0200 | [diff] [blame] | 3573 | retry-on X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3574 | server - - X X |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 3575 | server-state-file-name X - X X |
Frédéric Lécaille | cb4502e | 2017-04-20 13:36:25 +0200 | [diff] [blame] | 3576 | server-template - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3577 | source X - X X |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 3578 | srvtcpka-cnt X - X X |
| 3579 | srvtcpka-idle X - X X |
| 3580 | srvtcpka-intvl X - X X |
Baptiste Assmann | 5a54921 | 2015-10-12 20:30:24 +0200 | [diff] [blame] | 3581 | stats admin - X X X |
| 3582 | stats auth X X X X |
| 3583 | stats enable X X X X |
| 3584 | stats hide-version X X X X |
| 3585 | stats http-request - X X X |
| 3586 | stats realm X X X X |
| 3587 | stats refresh X X X X |
| 3588 | stats scope X X X X |
| 3589 | stats show-desc X X X X |
| 3590 | stats show-legends X X X X |
| 3591 | stats show-node X X X X |
| 3592 | stats uri X X X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3593 | -- keyword -------------------------- defaults - frontend - listen -- backend - |
| 3594 | stick match - - X X |
| 3595 | stick on - - X X |
| 3596 | stick store-request - - X X |
Willy Tarreau | d8dc99f | 2011-07-01 11:33:25 +0200 | [diff] [blame] | 3597 | stick store-response - - X X |
Adam Spiers | 68af3c1 | 2017-04-06 16:31:39 +0100 | [diff] [blame] | 3598 | stick-table - X X X |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 3599 | tcp-check comment X - X X |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 3600 | tcp-check connect X - X X |
| 3601 | tcp-check expect X - X X |
| 3602 | tcp-check send X - X X |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 3603 | tcp-check send-lf X - X X |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 3604 | tcp-check send-binary X - X X |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 3605 | tcp-check send-binary-lf X - X X |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 3606 | tcp-check set-var X - X X |
| 3607 | tcp-check unset-var X - X X |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 3608 | tcp-request connection - X X - |
| 3609 | tcp-request content - X X X |
Willy Tarreau | a56235c | 2010-09-14 11:31:36 +0200 | [diff] [blame] | 3610 | tcp-request inspect-delay - X X X |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 3611 | tcp-request session - X X - |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 3612 | tcp-response content - - X X |
| 3613 | tcp-response inspect-delay - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3614 | timeout check X - X X |
| 3615 | timeout client X X X - |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 3616 | timeout client-fin X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3617 | timeout connect X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3618 | timeout http-keep-alive X X X X |
| 3619 | timeout http-request X X X X |
| 3620 | timeout queue X - X X |
| 3621 | timeout server X - X X |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 3622 | timeout server-fin X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3623 | timeout tarpit X X X X |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 3624 | timeout tunnel X - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3625 | transparent (deprecated) X - X X |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 3626 | unique-id-format X X X - |
| 3627 | unique-id-header X X X - |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3628 | use_backend - X X - |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 3629 | use-fcgi-app - - X X |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 3630 | use-server - - X X |
Willy Tarreau | 5c6f7b3 | 2010-02-26 13:34:29 +0100 | [diff] [blame] | 3631 | ------------------------------------+----------+----------+---------+--------- |
| 3632 | keyword defaults frontend listen backend |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3633 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3634 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3635 | 4.2. Alphabetically sorted keywords reference |
| 3636 | --------------------------------------------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3637 | |
| 3638 | This section provides a description of each keyword and its usage. |
| 3639 | |
| 3640 | |
| 3641 | acl <aclname> <criterion> [flags] [operator] <value> ... |
| 3642 | Declare or complete an access list. |
| 3643 | May be used in sections : defaults | frontend | listen | backend |
| 3644 | no | yes | yes | yes |
| 3645 | Example: |
| 3646 | acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| 3647 | acl invalid_src src_port 0:1023 |
| 3648 | acl local_dst hdr(host) -i localhost |
| 3649 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 3650 | See section 7 about ACL usage. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3651 | |
| 3652 | |
Willy Tarreau | c73ce2b | 2008-01-06 10:55:10 +0100 | [diff] [blame] | 3653 | backlog <conns> |
| 3654 | Give hints to the system about the approximate listen backlog desired size |
| 3655 | May be used in sections : defaults | frontend | listen | backend |
| 3656 | yes | yes | yes | no |
| 3657 | Arguments : |
| 3658 | <conns> is the number of pending connections. Depending on the operating |
| 3659 | system, it may represent the number of already acknowledged |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 3660 | connections, of non-acknowledged ones, or both. |
Willy Tarreau | c73ce2b | 2008-01-06 10:55:10 +0100 | [diff] [blame] | 3661 | |
| 3662 | In order to protect against SYN flood attacks, one solution is to increase |
| 3663 | the system's SYN backlog size. Depending on the system, sometimes it is just |
| 3664 | tunable via a system parameter, sometimes it is not adjustable at all, and |
| 3665 | sometimes the system relies on hints given by the application at the time of |
| 3666 | the listen() syscall. By default, HAProxy passes the frontend's maxconn value |
| 3667 | to the listen() syscall. On systems which can make use of this value, it can |
| 3668 | sometimes be useful to be able to specify a different value, hence this |
| 3669 | backlog parameter. |
| 3670 | |
| 3671 | On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is |
| 3672 | used as a hint and the system accepts up to the smallest greater power of |
| 3673 | two, and never more than some limits (usually 32768). |
| 3674 | |
| 3675 | See also : "maxconn" and the target operating system's tuning guide. |
| 3676 | |
| 3677 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3678 | balance <algorithm> [ <arguments> ] |
Willy Tarreau | 226071e | 2014-04-10 11:55:45 +0200 | [diff] [blame] | 3679 | balance url_param <param> [check_post] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3680 | Define the load balancing algorithm to be used in a backend. |
| 3681 | May be used in sections : defaults | frontend | listen | backend |
| 3682 | yes | no | yes | yes |
| 3683 | Arguments : |
| 3684 | <algorithm> is the algorithm used to select a server when doing load |
| 3685 | balancing. This only applies when no persistence information |
| 3686 | is available, or when a connection is redispatched to another |
| 3687 | server. <algorithm> may be one of the following : |
| 3688 | |
| 3689 | roundrobin Each server is used in turns, according to their weights. |
| 3690 | This is the smoothest and fairest algorithm when the server's |
| 3691 | processing time remains equally distributed. This algorithm |
| 3692 | is dynamic, which means that server weights may be adjusted |
Willy Tarreau | 9757a38 | 2009-10-03 12:56:50 +0200 | [diff] [blame] | 3693 | on the fly for slow starts for instance. It is limited by |
Godbach | a34bdc0 | 2013-07-22 07:44:53 +0800 | [diff] [blame] | 3694 | design to 4095 active servers per backend. Note that in some |
Willy Tarreau | 9757a38 | 2009-10-03 12:56:50 +0200 | [diff] [blame] | 3695 | large farms, when a server becomes up after having been down |
| 3696 | for a very short time, it may sometimes take a few hundreds |
| 3697 | requests for it to be re-integrated into the farm and start |
| 3698 | receiving traffic. This is normal, though very rare. It is |
| 3699 | indicated here in case you would have the chance to observe |
| 3700 | it, so that you don't worry. |
| 3701 | |
| 3702 | static-rr Each server is used in turns, according to their weights. |
| 3703 | This algorithm is as similar to roundrobin except that it is |
| 3704 | static, which means that changing a server's weight on the |
| 3705 | fly will have no effect. On the other hand, it has no design |
| 3706 | limitation on the number of servers, and when a server goes |
| 3707 | up, it is always immediately reintroduced into the farm, once |
| 3708 | the full map is recomputed. It also uses slightly less CPU to |
| 3709 | run (around -1%). |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3710 | |
Willy Tarreau | 2d2a7f8 | 2008-03-17 12:07:56 +0100 | [diff] [blame] | 3711 | leastconn The server with the lowest number of connections receives the |
| 3712 | connection. Round-robin is performed within groups of servers |
| 3713 | of the same load to ensure that all servers will be used. Use |
| 3714 | of this algorithm is recommended where very long sessions are |
| 3715 | expected, such as LDAP, SQL, TSE, etc... but is not very well |
| 3716 | suited for protocols using short sessions such as HTTP. This |
| 3717 | algorithm is dynamic, which means that server weights may be |
Willy Tarreau | 8c855f6 | 2020-10-22 17:41:45 +0200 | [diff] [blame] | 3718 | adjusted on the fly for slow starts for instance. It will |
| 3719 | also consider the number of queued connections in addition to |
| 3720 | the established ones in order to minimize queuing. |
Willy Tarreau | 2d2a7f8 | 2008-03-17 12:07:56 +0100 | [diff] [blame] | 3721 | |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 3722 | first The first server with available connection slots receives the |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 3723 | connection. The servers are chosen from the lowest numeric |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 3724 | identifier to the highest (see server parameter "id"), which |
| 3725 | defaults to the server's position in the farm. Once a server |
Willy Tarreau | 64559c5 | 2012-04-07 09:08:45 +0200 | [diff] [blame] | 3726 | reaches its maxconn value, the next server is used. It does |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 3727 | not make sense to use this algorithm without setting maxconn. |
| 3728 | The purpose of this algorithm is to always use the smallest |
| 3729 | number of servers so that extra servers can be powered off |
| 3730 | during non-intensive hours. This algorithm ignores the server |
| 3731 | weight, and brings more benefit to long session such as RDP |
Willy Tarreau | 64559c5 | 2012-04-07 09:08:45 +0200 | [diff] [blame] | 3732 | or IMAP than HTTP, though it can be useful there too. In |
| 3733 | order to use this algorithm efficiently, it is recommended |
| 3734 | that a cloud controller regularly checks server usage to turn |
| 3735 | them off when unused, and regularly checks backend queue to |
| 3736 | turn new servers on when the queue inflates. Alternatively, |
| 3737 | using "http-check send-state" may inform servers on the load. |
Willy Tarreau | f09c660 | 2012-02-13 17:12:08 +0100 | [diff] [blame] | 3738 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3739 | source The source IP address is hashed and divided by the total |
| 3740 | weight of the running servers to designate which server will |
| 3741 | receive the request. This ensures that the same client IP |
| 3742 | address will always reach the same server as long as no |
| 3743 | server goes down or up. If the hash result changes due to the |
| 3744 | number of running servers changing, many clients will be |
| 3745 | directed to a different server. This algorithm is generally |
| 3746 | 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] | 3747 | be used on the Internet to provide a best-effort stickiness |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3748 | to clients which refuse session cookies. This algorithm is |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 3749 | static by default, which means that changing a server's |
| 3750 | weight on the fly will have no effect, but this can be |
| 3751 | changed using "hash-type". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3752 | |
Oskar Stolc | 8dc4184 | 2012-05-19 10:19:54 +0100 | [diff] [blame] | 3753 | uri This algorithm hashes either the left part of the URI (before |
| 3754 | the question mark) or the whole URI (if the "whole" parameter |
| 3755 | is present) and divides the hash value by the total weight of |
| 3756 | the running servers. The result designates which server will |
| 3757 | receive the request. This ensures that the same URI will |
| 3758 | always be directed to the same server as long as no server |
| 3759 | goes up or down. This is used with proxy caches and |
| 3760 | anti-virus proxies in order to maximize the cache hit rate. |
| 3761 | Note that this algorithm may only be used in an HTTP backend. |
| 3762 | This algorithm is static by default, which means that |
| 3763 | changing a server's weight on the fly will have no effect, |
| 3764 | but this can be changed using "hash-type". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3765 | |
Oskar Stolc | 8dc4184 | 2012-05-19 10:19:54 +0100 | [diff] [blame] | 3766 | This algorithm supports two optional parameters "len" and |
Marek Majkowski | 9c30fc1 | 2008-04-27 23:25:55 +0200 | [diff] [blame] | 3767 | "depth", both followed by a positive integer number. These |
| 3768 | options may be helpful when it is needed to balance servers |
| 3769 | based on the beginning of the URI only. The "len" parameter |
| 3770 | indicates that the algorithm should only consider that many |
| 3771 | characters at the beginning of the URI to compute the hash. |
| 3772 | Note that having "len" set to 1 rarely makes sense since most |
| 3773 | URIs start with a leading "/". |
| 3774 | |
| 3775 | The "depth" parameter indicates the maximum directory depth |
| 3776 | to be used to compute the hash. One level is counted for each |
| 3777 | slash in the request. If both parameters are specified, the |
| 3778 | evaluation stops when either is reached. |
| 3779 | |
Willy Tarreau | 57a3741 | 2020-09-23 08:56:29 +0200 | [diff] [blame] | 3780 | A "path-only" parameter indicates that the hashing key starts |
| 3781 | at the first '/' of the path. This can be used to ignore the |
| 3782 | authority part of absolute URIs, and to make sure that HTTP/1 |
| 3783 | and HTTP/2 URIs will provide the same hash. |
| 3784 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3785 | 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] | 3786 | the query string of each HTTP GET request. |
| 3787 | |
| 3788 | If the modifier "check_post" is used, then an HTTP POST |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 3789 | request entity will be searched for the parameter argument, |
| 3790 | 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] | 3791 | ('?') in the URL. The message body will only start to be |
| 3792 | analyzed once either the advertised amount of data has been |
| 3793 | received or the request buffer is full. In the unlikely event |
| 3794 | that chunked encoding is used, only the first chunk is |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 3795 | scanned. Parameter values separated by a chunk boundary, may |
Willy Tarreau | 226071e | 2014-04-10 11:55:45 +0200 | [diff] [blame] | 3796 | be randomly balanced if at all. This keyword used to support |
| 3797 | an optional <max_wait> parameter which is now ignored. |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3798 | |
| 3799 | If the parameter is found followed by an equal sign ('=') and |
| 3800 | a value, then the value is hashed and divided by the total |
| 3801 | weight of the running servers. The result designates which |
| 3802 | server will receive the request. |
| 3803 | |
| 3804 | This is used to track user identifiers in requests and ensure |
| 3805 | that a same user ID will always be sent to the same server as |
| 3806 | long as no server goes up or down. If no value is found or if |
| 3807 | the parameter is not found, then a round robin algorithm is |
| 3808 | applied. Note that this algorithm may only be used in an HTTP |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 3809 | backend. This algorithm is static by default, which means |
| 3810 | that changing a server's weight on the fly will have no |
| 3811 | effect, but this can be changed using "hash-type". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3812 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 3813 | hdr(<name>) The HTTP header <name> will be looked up in each HTTP |
| 3814 | request. Just as with the equivalent ACL 'hdr()' function, |
| 3815 | the header name in parenthesis is not case sensitive. If the |
| 3816 | header is absent or if it does not contain any value, the |
| 3817 | roundrobin algorithm is applied instead. |
Benoit | affb481 | 2009-03-25 13:02:10 +0100 | [diff] [blame] | 3818 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3819 | An optional 'use_domain_only' parameter is available, for |
Benoit | affb481 | 2009-03-25 13:02:10 +0100 | [diff] [blame] | 3820 | reducing the hash algorithm to the main domain part with some |
| 3821 | specific headers such as 'Host'. For instance, in the Host |
| 3822 | value "haproxy.1wt.eu", only "1wt" will be considered. |
| 3823 | |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 3824 | This algorithm is static by default, which means that |
| 3825 | changing a server's weight on the fly will have no effect, |
| 3826 | but this can be changed using "hash-type". |
| 3827 | |
Willy Tarreau | 21c741a | 2019-01-14 18:14:27 +0100 | [diff] [blame] | 3828 | random |
| 3829 | random(<draws>) |
| 3830 | A random number will be used as the key for the consistent |
Willy Tarreau | 760e81d | 2018-05-03 07:20:40 +0200 | [diff] [blame] | 3831 | hashing function. This means that the servers' weights are |
| 3832 | respected, dynamic weight changes immediately take effect, as |
| 3833 | well as new server additions. Random load balancing can be |
| 3834 | useful with large farms or when servers are frequently added |
Willy Tarreau | 21c741a | 2019-01-14 18:14:27 +0100 | [diff] [blame] | 3835 | or removed as it may avoid the hammering effect that could |
| 3836 | result from roundrobin or leastconn in this situation. The |
| 3837 | hash-balance-factor directive can be used to further improve |
| 3838 | fairness of the load balancing, especially in situations |
| 3839 | where servers show highly variable response times. When an |
| 3840 | argument <draws> is present, it must be an integer value one |
| 3841 | or greater, indicating the number of draws before selecting |
| 3842 | the least loaded of these servers. It was indeed demonstrated |
| 3843 | that picking the least loaded of two servers is enough to |
| 3844 | significantly improve the fairness of the algorithm, by |
| 3845 | always avoiding to pick the most loaded server within a farm |
| 3846 | and getting rid of any bias that could be induced by the |
| 3847 | unfair distribution of the consistent list. Higher values N |
| 3848 | will take away N-1 of the highest loaded servers at the |
| 3849 | expense of performance. With very high values, the algorithm |
| 3850 | will converge towards the leastconn's result but much slower. |
| 3851 | The default value is 2, which generally shows very good |
| 3852 | distribution and performance. This algorithm is also known as |
| 3853 | the Power of Two Random Choices and is described here : |
| 3854 | http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf |
Willy Tarreau | 760e81d | 2018-05-03 07:20:40 +0200 | [diff] [blame] | 3855 | |
Emeric Brun | 736aa23 | 2009-06-30 17:56:00 +0200 | [diff] [blame] | 3856 | rdp-cookie |
Hervé COMMOWICK | a3eb39c | 2011-08-05 18:48:51 +0200 | [diff] [blame] | 3857 | rdp-cookie(<name>) |
Emeric Brun | 736aa23 | 2009-06-30 17:56:00 +0200 | [diff] [blame] | 3858 | The RDP cookie <name> (or "mstshash" if omitted) will be |
| 3859 | looked up and hashed for each incoming TCP request. Just as |
| 3860 | with the equivalent ACL 'req_rdp_cookie()' function, the name |
| 3861 | is not case-sensitive. This mechanism is useful as a degraded |
| 3862 | persistence mode, as it makes it possible to always send the |
| 3863 | 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] | 3864 | cookie is not found, the normal roundrobin algorithm is |
Emeric Brun | 736aa23 | 2009-06-30 17:56:00 +0200 | [diff] [blame] | 3865 | used instead. |
| 3866 | |
| 3867 | Note that for this to work, the frontend must ensure that an |
| 3868 | RDP cookie is already present in the request buffer. For this |
| 3869 | you must use 'tcp-request content accept' rule combined with |
| 3870 | a 'req_rdp_cookie_cnt' ACL. |
| 3871 | |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 3872 | This algorithm is static by default, which means that |
| 3873 | changing a server's weight on the fly will have no effect, |
| 3874 | but this can be changed using "hash-type". |
| 3875 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 3876 | See also the rdp_cookie pattern fetch function. |
Simon Horman | ab814e0 | 2011-06-24 14:50:20 +0900 | [diff] [blame] | 3877 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3878 | <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] | 3879 | algorithms. Right now, only "url_param" and "uri" support an |
| 3880 | optional argument. |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3881 | |
Willy Tarreau | 3cd9af2 | 2009-03-15 14:06:41 +0100 | [diff] [blame] | 3882 | The load balancing algorithm of a backend is set to roundrobin when no other |
| 3883 | algorithm, mode nor option have been set. The algorithm may only be set once |
| 3884 | for each backend. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3885 | |
Lukas Tribus | 80512b1 | 2018-10-27 20:07:40 +0200 | [diff] [blame] | 3886 | With authentication schemes that require the same connection like NTLM, URI |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 3887 | based algorithms must not be used, as they would cause subsequent requests |
Lukas Tribus | 80512b1 | 2018-10-27 20:07:40 +0200 | [diff] [blame] | 3888 | to be routed to different backend servers, breaking the invalid assumptions |
| 3889 | NTLM relies on. |
| 3890 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3891 | Examples : |
| 3892 | balance roundrobin |
| 3893 | balance url_param userid |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3894 | balance url_param session_id check_post 64 |
Benoit | affb481 | 2009-03-25 13:02:10 +0100 | [diff] [blame] | 3895 | balance hdr(User-Agent) |
| 3896 | balance hdr(host) |
| 3897 | balance hdr(Host) use_domain_only |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3898 | |
| 3899 | Note: the following caveats and limitations on using the "check_post" |
| 3900 | extension with "url_param" must be considered : |
| 3901 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 3902 | - 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] | 3903 | to determine if the parameters will be found in the body or entity which |
| 3904 | may contain binary data. Therefore another method may be required to |
| 3905 | restrict consideration of POST requests that have no URL parameters in |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 3906 | the body. (see acl http_end) |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3907 | |
| 3908 | - using a <max_wait> value larger than the request buffer size does not |
| 3909 | make sense and is useless. The buffer size is set at build time, and |
| 3910 | defaults to 16 kB. |
| 3911 | |
| 3912 | - Content-Encoding is not supported, the parameter search will probably |
| 3913 | fail; and load balancing will fall back to Round Robin. |
| 3914 | |
| 3915 | - Expect: 100-continue is not supported, load balancing will fall back to |
| 3916 | Round Robin. |
| 3917 | |
Lukas Tribus | 2395368 | 2017-04-28 13:24:30 +0000 | [diff] [blame] | 3918 | - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk. |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3919 | If the entire parameter value is not present in the first chunk, the |
| 3920 | selection of server is undefined (actually, defined by how little |
| 3921 | actually appeared in the first chunk). |
| 3922 | |
| 3923 | - This feature does not support generation of a 100, 411 or 501 response. |
| 3924 | |
| 3925 | - 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] | 3926 | contents of a message body. Scanning normally terminates when linear |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 3927 | white space or control characters are found, indicating the end of what |
| 3928 | might be a URL parameter list. This is probably not a concern with SGML |
| 3929 | type message bodies. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3930 | |
Willy Tarreau | 294d0f0 | 2015-08-10 19:40:12 +0200 | [diff] [blame] | 3931 | See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3932 | |
| 3933 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 3934 | bind [<address>]:<port_range> [, ...] [param*] |
| 3935 | bind /<path> [, ...] [param*] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3936 | Define one or several listening addresses and/or ports in a frontend. |
| 3937 | May be used in sections : defaults | frontend | listen | backend |
| 3938 | no | yes | yes | no |
| 3939 | Arguments : |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 3940 | <address> is optional and can be a host name, an IPv4 address, an IPv6 |
| 3941 | address, or '*'. It designates the address the frontend will |
| 3942 | listen on. If unset, all IPv4 addresses of the system will be |
| 3943 | listened on. The same will apply for '*' or the system's |
David du Colombier | 9c938da | 2011-03-17 10:40:27 +0100 | [diff] [blame] | 3944 | special address "0.0.0.0". The IPv6 equivalent is '::'. |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 3945 | Optionally, an address family prefix may be used before the |
| 3946 | address to force the family regardless of the address format, |
| 3947 | which can be useful to specify a path to a unix socket with |
| 3948 | no slash ('/'). Currently supported prefixes are : |
| 3949 | - 'ipv4@' -> address is always IPv4 |
| 3950 | - 'ipv6@' -> address is always IPv6 |
Emeric Brun | 3835c0d | 2020-07-07 09:46:09 +0200 | [diff] [blame] | 3951 | - 'udp@' -> address is resolved as IPv4 or IPv6 and |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3952 | protocol UDP is used. Currently those listeners are |
| 3953 | supported only in log-forward sections. |
Emeric Brun | 3835c0d | 2020-07-07 09:46:09 +0200 | [diff] [blame] | 3954 | - 'udp4@' -> address is always IPv4 and protocol UDP |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3955 | is used. Currently those listeners are supported |
| 3956 | only in log-forward sections. |
Emeric Brun | 3835c0d | 2020-07-07 09:46:09 +0200 | [diff] [blame] | 3957 | - 'udp6@' -> address is always IPv6 and protocol UDP |
Emeric Brun | 12941c8 | 2020-07-07 14:19:42 +0200 | [diff] [blame] | 3958 | is used. Currently those listeners are supported |
| 3959 | only in log-forward sections. |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 3960 | - 'unix@' -> address is a path to a local unix socket |
Willy Tarreau | 70f72e0 | 2014-07-08 00:37:50 +0200 | [diff] [blame] | 3961 | - 'abns@' -> address is in abstract namespace (Linux only). |
| 3962 | Note: since abstract sockets are not "rebindable", they |
| 3963 | do not cope well with multi-process mode during |
| 3964 | soft-restart, so it is better to avoid them if |
| 3965 | nbproc is greater than 1. The effect is that if the |
| 3966 | new process fails to start, only one of the old ones |
| 3967 | will be able to rebind to the socket. |
Willy Tarreau | 40aa070 | 2013-03-10 23:51:38 +0100 | [diff] [blame] | 3968 | - 'fd@<n>' -> use file descriptor <n> inherited from the |
| 3969 | parent. The fd must be bound and may or may not already |
| 3970 | be listening. |
William Lallemand | 2fe7dd0 | 2018-09-11 16:51:29 +0200 | [diff] [blame] | 3971 | - 'sockpair@<n>'-> like fd@ but you must use the fd of a |
| 3972 | connected unix socket or of a socketpair. The bind waits |
| 3973 | to receive a FD over the unix socket and uses it as if it |
| 3974 | was the FD of an accept(). Should be used carefully. |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 3975 | You may want to reference some environment variables in the |
| 3976 | address parameter, see section 2.3 about environment |
| 3977 | variables. |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 3978 | |
Willy Tarreau | c5011ca | 2010-03-22 11:53:56 +0100 | [diff] [blame] | 3979 | <port_range> is either a unique TCP port, or a port range for which the |
| 3980 | proxy will accept connections for the IP address specified |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 3981 | above. The port is mandatory for TCP listeners. Note that in |
| 3982 | the case of an IPv6 address, the port is always the number |
| 3983 | after the last colon (':'). A range can either be : |
Willy Tarreau | c5011ca | 2010-03-22 11:53:56 +0100 | [diff] [blame] | 3984 | - a numerical port (ex: '80') |
| 3985 | - a dash-delimited ports range explicitly stating the lower |
| 3986 | and upper bounds (ex: '2000-2100') which are included in |
| 3987 | the range. |
| 3988 | |
| 3989 | Particular care must be taken against port ranges, because |
| 3990 | every <address:port> couple consumes one socket (= a file |
| 3991 | descriptor), so it's easy to consume lots of descriptors |
| 3992 | with a simple range, and to run out of sockets. Also, each |
| 3993 | <address:port> couple must be used only once among all |
| 3994 | instances running on a same system. Please note that binding |
| 3995 | to ports lower than 1024 generally require particular |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 3996 | privileges to start the program, which are independent of |
Willy Tarreau | c5011ca | 2010-03-22 11:53:56 +0100 | [diff] [blame] | 3997 | the 'uid' parameter. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3998 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 3999 | <path> is a UNIX socket path beginning with a slash ('/'). This is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4000 | alternative to the TCP listening port. HAProxy will then |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 4001 | receive UNIX connections on the socket located at this place. |
| 4002 | The path must begin with a slash and by default is absolute. |
| 4003 | It can be relative to the prefix defined by "unix-bind" in |
| 4004 | the global section. Note that the total length of the prefix |
| 4005 | followed by the socket path cannot exceed some system limits |
| 4006 | for UNIX sockets, which commonly are set to 107 characters. |
| 4007 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 4008 | <param*> is a list of parameters common to all sockets declared on the |
| 4009 | same line. These numerous parameters depend on OS and build |
| 4010 | options and have a complete section dedicated to them. Please |
| 4011 | refer to section 5 to for more details. |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 4012 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4013 | It is possible to specify a list of address:port combinations delimited by |
| 4014 | commas. The frontend will then listen on all of these addresses. There is no |
| 4015 | fixed limit to the number of addresses and ports which can be listened on in |
| 4016 | a frontend, as well as there is no limit to the number of "bind" statements |
| 4017 | in a frontend. |
| 4018 | |
| 4019 | Example : |
| 4020 | listen http_proxy |
| 4021 | bind :80,:443 |
| 4022 | bind 10.0.0.1:10080,10.0.0.1:10443 |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 4023 | bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4024 | |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 4025 | listen http_https_proxy |
| 4026 | bind :80 |
Cyril Bonté | 0d44fc6 | 2012-10-09 22:45:33 +0200 | [diff] [blame] | 4027 | bind :443 ssl crt /etc/haproxy/site.pem |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 4028 | |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 4029 | listen http_https_proxy_explicit |
| 4030 | bind ipv6@:80 |
| 4031 | bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem |
| 4032 | bind unix@ssl-frontend.sock user root mode 600 accept-proxy |
| 4033 | |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 4034 | listen external_bind_app1 |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 4035 | bind "fd@${FD_APP1}" |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 4036 | |
Willy Tarreau | 55dcaf6 | 2015-09-27 15:03:15 +0200 | [diff] [blame] | 4037 | Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole |
| 4038 | sun_path length is used for the address length. Some other programs |
| 4039 | such as socat use the string length only by default. Pass the option |
| 4040 | ",unix-tightsocklen=0" to any abstract socket definition in socat to |
| 4041 | make it compatible with HAProxy's. |
| 4042 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 4043 | See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 4044 | documentation, and section 5 about bind options. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4045 | |
| 4046 | |
Christopher Faulet | ff4121f | 2017-11-22 16:38:49 +0100 | [diff] [blame] | 4047 | bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ... |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4048 | Limit visibility of an instance to a certain set of processes numbers. |
| 4049 | May be used in sections : defaults | frontend | listen | backend |
| 4050 | yes | yes | yes | yes |
| 4051 | Arguments : |
| 4052 | all All process will see this instance. This is the default. It |
| 4053 | may be used to override a default value. |
| 4054 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 4055 | 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] | 4056 | option may be combined with other numbers. |
| 4057 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 4058 | 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] | 4059 | option may be combined with other numbers. Do not use it |
| 4060 | with less than 2 processes otherwise some instances might be |
| 4061 | missing from all processes. |
| 4062 | |
Christopher Faulet | ff4121f | 2017-11-22 16:38:49 +0100 | [diff] [blame] | 4063 | process_num The instance will be enabled on this process number or range, |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 4064 | whose values must all be between 1 and 32 or 64 depending on |
Christopher Faulet | ff4121f | 2017-11-22 16:38:49 +0100 | [diff] [blame] | 4065 | the machine's word size. Ranges can be partially defined. The |
| 4066 | higher bound can be omitted. In such case, it is replaced by |
| 4067 | the corresponding maximum value. If a proxy is bound to |
| 4068 | process numbers greater than the configured global.nbproc, it |
| 4069 | will either be forced to process #1 if a single process was |
Willy Tarreau | 102df61 | 2014-05-07 23:56:38 +0200 | [diff] [blame] | 4070 | specified, or to all processes otherwise. |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4071 | |
| 4072 | This keyword limits binding of certain instances to certain processes. This |
| 4073 | is useful in order not to have too many processes listening to the same |
| 4074 | ports. For instance, on a dual-core machine, it might make sense to set |
| 4075 | 'nbproc 2' in the global section, then distributes the listeners among 'odd' |
| 4076 | and 'even' instances. |
| 4077 | |
Willy Tarreau | a9db57e | 2013-01-18 11:29:29 +0100 | [diff] [blame] | 4078 | At the moment, it is not possible to reference more than 32 or 64 processes |
| 4079 | using this keyword, but this should be more than enough for most setups. |
| 4080 | Please note that 'all' really means all processes regardless of the machine's |
| 4081 | word size, and is not limited to the first 32 or 64. |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4082 | |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 4083 | Each "bind" line may further be limited to a subset of the proxy's processes, |
| 4084 | please consult the "process" bind keyword in section 5.1. |
| 4085 | |
Willy Tarreau | b369a04 | 2014-09-16 13:21:03 +0200 | [diff] [blame] | 4086 | When a frontend has no explicit "bind-process" line, it tries to bind to all |
| 4087 | the processes referenced by its "bind" lines. That means that frontends can |
| 4088 | easily adapt to their listeners' processes. |
| 4089 | |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4090 | If some backends are referenced by frontends bound to other processes, the |
| 4091 | backend automatically inherits the frontend's processes. |
| 4092 | |
| 4093 | Example : |
| 4094 | listen app_ip1 |
| 4095 | bind 10.0.0.1:80 |
Willy Tarreau | bfcd311 | 2010-10-23 11:22:08 +0200 | [diff] [blame] | 4096 | bind-process odd |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4097 | |
| 4098 | listen app_ip2 |
| 4099 | bind 10.0.0.2:80 |
Willy Tarreau | bfcd311 | 2010-10-23 11:22:08 +0200 | [diff] [blame] | 4100 | bind-process even |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4101 | |
| 4102 | listen management |
| 4103 | bind 10.0.0.3:80 |
Willy Tarreau | bfcd311 | 2010-10-23 11:22:08 +0200 | [diff] [blame] | 4104 | bind-process 1 2 3 4 |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4105 | |
Willy Tarreau | 110ecc1 | 2012-11-15 17:50:01 +0100 | [diff] [blame] | 4106 | listen management |
| 4107 | bind 10.0.0.4:80 |
| 4108 | bind-process 1-4 |
| 4109 | |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 4110 | See also : "nbproc" in global section, and "process" in section 5.1. |
Willy Tarreau | 0b9c02c | 2009-02-04 22:05:05 +0100 | [diff] [blame] | 4111 | |
| 4112 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4113 | capture cookie <name> len <length> |
| 4114 | Capture and log a cookie in the request and in the response. |
| 4115 | May be used in sections : defaults | frontend | listen | backend |
| 4116 | no | yes | yes | no |
| 4117 | Arguments : |
| 4118 | <name> is the beginning of the name of the cookie to capture. In order |
| 4119 | to match the exact name, simply suffix the name with an equal |
| 4120 | sign ('='). The full name will appear in the logs, which is |
| 4121 | useful with application servers which adjust both the cookie name |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4122 | and value (e.g. ASPSESSIONXXX). |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4123 | |
| 4124 | <length> is the maximum number of characters to report in the logs, which |
| 4125 | include the cookie name, the equal sign and the value, all in the |
| 4126 | standard "name=value" form. The string will be truncated on the |
| 4127 | right if it exceeds <length>. |
| 4128 | |
| 4129 | Only the first cookie is captured. Both the "cookie" request headers and the |
| 4130 | "set-cookie" response headers are monitored. This is particularly useful to |
| 4131 | check for application bugs causing session crossing or stealing between |
| 4132 | users, because generally the user's cookies can only change on a login page. |
| 4133 | |
| 4134 | When the cookie was not presented by the client, the associated log column |
| 4135 | will report "-". When a request does not cause a cookie to be assigned by the |
| 4136 | server, a "-" is reported in the response column. |
| 4137 | |
| 4138 | The capture is performed in the frontend only because it is necessary that |
| 4139 | the log format does not change for a given frontend depending on the |
| 4140 | 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] | 4141 | "capture cookie" statement in a frontend. The maximum capture length is set |
| 4142 | by the global "tune.http.cookielen" setting and defaults to 63 characters. It |
| 4143 | is not possible to specify a capture in a "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4144 | |
| 4145 | Example: |
| 4146 | capture cookie ASPSESSION len 32 |
| 4147 | |
| 4148 | See also : "capture request header", "capture response header" as well as |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 4149 | section 8 about logging. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4150 | |
| 4151 | |
| 4152 | capture request header <name> len <length> |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 4153 | Capture and log the last occurrence of the specified request header. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4154 | May be used in sections : defaults | frontend | listen | backend |
| 4155 | no | yes | yes | no |
| 4156 | Arguments : |
| 4157 | <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] | 4158 | 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] | 4159 | appear in the requests, with the first letter of each word in |
| 4160 | upper case. The header name will not appear in the logs, only the |
| 4161 | value is reported, but the position in the logs is respected. |
| 4162 | |
| 4163 | <length> is the maximum number of characters to extract from the value and |
| 4164 | report in the logs. The string will be truncated on the right if |
| 4165 | it exceeds <length>. |
| 4166 | |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 4167 | 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] | 4168 | value will be added to the logs between braces ('{}'). If multiple headers |
| 4169 | 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] | 4170 | in the same order they were declared in the configuration. Non-existent |
| 4171 | headers will be logged just as an empty string. Common uses for request |
| 4172 | header captures include the "Host" field in virtual hosting environments, the |
| 4173 | "Content-length" when uploads are supported, "User-agent" to quickly |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 4174 | differentiate between real users and robots, and "X-Forwarded-For" in proxied |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 4175 | environments to find where the request came from. |
| 4176 | |
| 4177 | Note that when capturing headers such as "User-agent", some spaces may be |
| 4178 | logged, making the log analysis more difficult. Thus be careful about what |
| 4179 | you log if you know your log parser is not smart enough to rely on the |
| 4180 | braces. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4181 | |
Willy Tarreau | 0900abb | 2012-11-22 00:21:46 +0100 | [diff] [blame] | 4182 | There is no limit to the number of captured request headers nor to their |
| 4183 | length, though it is wise to keep them low to limit memory usage per session. |
| 4184 | In order to keep log format consistent for a same frontend, header captures |
| 4185 | can only be declared in a frontend. It is not possible to specify a capture |
| 4186 | in a "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4187 | |
| 4188 | Example: |
| 4189 | capture request header Host len 15 |
| 4190 | capture request header X-Forwarded-For len 15 |
Cyril Bonté | d1b0f7c | 2015-10-26 22:37:39 +0100 | [diff] [blame] | 4191 | capture request header Referer len 15 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4192 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 4193 | See also : "capture cookie", "capture response header" as well as section 8 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4194 | about logging. |
| 4195 | |
| 4196 | |
| 4197 | capture response header <name> len <length> |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 4198 | Capture and log the last occurrence of the specified response header. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4199 | May be used in sections : defaults | frontend | listen | backend |
| 4200 | no | yes | yes | no |
| 4201 | Arguments : |
| 4202 | <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] | 4203 | 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] | 4204 | appear in the response, with the first letter of each word in |
| 4205 | upper case. The header name will not appear in the logs, only the |
| 4206 | value is reported, but the position in the logs is respected. |
| 4207 | |
| 4208 | <length> is the maximum number of characters to extract from the value and |
| 4209 | report in the logs. The string will be truncated on the right if |
| 4210 | it exceeds <length>. |
| 4211 | |
Willy Tarreau | 4460d03 | 2012-11-21 23:37:37 +0100 | [diff] [blame] | 4212 | 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] | 4213 | result will be added to the logs between braces ('{}') after the captured |
| 4214 | request headers. If multiple headers are captured, they will be delimited by |
| 4215 | 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] | 4216 | the configuration. Non-existent headers will be logged just as an empty |
| 4217 | string. Common uses for response header captures include the "Content-length" |
| 4218 | header which indicates how many bytes are expected to be returned, the |
| 4219 | "Location" header to track redirections. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4220 | |
Willy Tarreau | 0900abb | 2012-11-22 00:21:46 +0100 | [diff] [blame] | 4221 | There is no limit to the number of captured response headers nor to their |
| 4222 | length, though it is wise to keep them low to limit memory usage per session. |
| 4223 | In order to keep log format consistent for a same frontend, header captures |
| 4224 | can only be declared in a frontend. It is not possible to specify a capture |
| 4225 | in a "defaults" section. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4226 | |
| 4227 | Example: |
| 4228 | capture response header Content-length len 9 |
| 4229 | capture response header Location len 15 |
| 4230 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 4231 | See also : "capture cookie", "capture request header" as well as section 8 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4232 | about logging. |
| 4233 | |
| 4234 | |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 4235 | clitcpka-cnt <count> |
| 4236 | Sets the maximum number of keepalive probes TCP should send before dropping |
| 4237 | the connection on the client side. |
| 4238 | May be used in sections : defaults | frontend | listen | backend |
| 4239 | yes | yes | yes | no |
| 4240 | Arguments : |
| 4241 | <count> is the maximum number of keepalive probes. |
| 4242 | |
| 4243 | This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword |
| 4244 | is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used. |
Willy Tarreau | 5254321 | 2020-07-09 05:58:51 +0200 | [diff] [blame] | 4245 | The availability of this setting depends on the operating system. It is |
| 4246 | known to work on Linux. |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 4247 | |
| 4248 | See also : "option clitcpka", "clitcpka-idle", "clitcpka-intvl". |
| 4249 | |
| 4250 | |
| 4251 | clitcpka-idle <timeout> |
| 4252 | Sets the time the connection needs to remain idle before TCP starts sending |
| 4253 | keepalive probes, if enabled the sending of TCP keepalive packets on the |
| 4254 | client side. |
| 4255 | May be used in sections : defaults | frontend | listen | backend |
| 4256 | yes | yes | yes | no |
| 4257 | Arguments : |
| 4258 | <timeout> is the time the connection needs to remain idle before TCP starts |
| 4259 | sending keepalive probes. It is specified in seconds by default, |
| 4260 | but can be in any other unit if the number is suffixed by the |
| 4261 | unit, as explained at the top of this document. |
| 4262 | |
| 4263 | This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword |
| 4264 | is not specified, system-wide TCP parameter (tcp_keepalive_time) is used. |
Willy Tarreau | 5254321 | 2020-07-09 05:58:51 +0200 | [diff] [blame] | 4265 | The availability of this setting depends on the operating system. It is |
| 4266 | known to work on Linux. |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 4267 | |
| 4268 | See also : "option clitcpka", "clitcpka-cnt", "clitcpka-intvl". |
| 4269 | |
| 4270 | |
| 4271 | clitcpka-intvl <timeout> |
| 4272 | Sets the time between individual keepalive probes on the client side. |
| 4273 | May be used in sections : defaults | frontend | listen | backend |
| 4274 | yes | yes | yes | no |
| 4275 | Arguments : |
| 4276 | <timeout> is the time between individual keepalive probes. It is specified |
| 4277 | in seconds by default, but can be in any other unit if the number |
| 4278 | is suffixed by the unit, as explained at the top of this |
| 4279 | document. |
| 4280 | |
| 4281 | This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword |
| 4282 | is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used. |
Willy Tarreau | 5254321 | 2020-07-09 05:58:51 +0200 | [diff] [blame] | 4283 | The availability of this setting depends on the operating system. It is |
| 4284 | known to work on Linux. |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 4285 | |
| 4286 | See also : "option clitcpka", "clitcpka-cnt", "clitcpka-idle". |
| 4287 | |
| 4288 | |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 4289 | compression algo <algorithm> ... |
| 4290 | compression type <mime type> ... |
Willy Tarreau | 70737d1 | 2012-10-27 00:34:28 +0200 | [diff] [blame] | 4291 | compression offload |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 4292 | Enable HTTP compression. |
| 4293 | May be used in sections : defaults | frontend | listen | backend |
| 4294 | yes | yes | yes | yes |
| 4295 | Arguments : |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 4296 | algo is followed by the list of supported compression algorithms. |
| 4297 | type is followed by the list of MIME types that will be compressed. |
| 4298 | offload makes haproxy work as a compression offloader only (see notes). |
| 4299 | |
| 4300 | The currently supported algorithms are : |
Willy Tarreau | c91840a | 2015-03-28 17:00:39 +0100 | [diff] [blame] | 4301 | identity this is mostly for debugging, and it was useful for developing |
| 4302 | the compression feature. Identity does not apply any change on |
| 4303 | data. |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 4304 | |
Willy Tarreau | c91840a | 2015-03-28 17:00:39 +0100 | [diff] [blame] | 4305 | gzip applies gzip compression. This setting is only available when |
Baptiste Assmann | f085d63 | 2015-12-21 17:57:32 +0100 | [diff] [blame] | 4306 | support for zlib or libslz was built in. |
Willy Tarreau | c91840a | 2015-03-28 17:00:39 +0100 | [diff] [blame] | 4307 | |
| 4308 | deflate same as "gzip", but with deflate algorithm and zlib format. |
| 4309 | Note that this algorithm has ambiguous support on many |
| 4310 | browsers and no support at all from recent ones. It is |
| 4311 | strongly recommended not to use it for anything else than |
| 4312 | experimentation. This setting is only available when support |
Baptiste Assmann | f085d63 | 2015-12-21 17:57:32 +0100 | [diff] [blame] | 4313 | for zlib or libslz was built in. |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 4314 | |
Willy Tarreau | c91840a | 2015-03-28 17:00:39 +0100 | [diff] [blame] | 4315 | raw-deflate same as "deflate" without the zlib wrapper, and used as an |
| 4316 | alternative when the browser wants "deflate". All major |
| 4317 | browsers understand it and despite violating the standards, |
| 4318 | it is known to work better than "deflate", at least on MSIE |
| 4319 | and some versions of Safari. Do not use it in conjunction |
| 4320 | with "deflate", use either one or the other since both react |
| 4321 | to the same Accept-Encoding token. This setting is only |
Baptiste Assmann | f085d63 | 2015-12-21 17:57:32 +0100 | [diff] [blame] | 4322 | available when support for zlib or libslz was built in. |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 4323 | |
Dmitry Sivachenko | 87c208b | 2012-11-22 20:03:26 +0400 | [diff] [blame] | 4324 | Compression will be activated depending on the Accept-Encoding request |
Cyril Bonté | 316a8cf | 2012-11-11 13:38:27 +0100 | [diff] [blame] | 4325 | header. With identity, it does not take care of that header. |
Dmitry Sivachenko | c9f3b45 | 2012-11-28 17:47:11 +0400 | [diff] [blame] | 4326 | If backend servers support HTTP compression, these directives |
| 4327 | will be no-op: haproxy will see the compressed response and will not |
| 4328 | compress again. If backend servers do not support HTTP compression and |
| 4329 | there is Accept-Encoding header in request, haproxy will compress the |
| 4330 | matching response. |
Willy Tarreau | 70737d1 | 2012-10-27 00:34:28 +0200 | [diff] [blame] | 4331 | |
| 4332 | The "offload" setting makes haproxy remove the Accept-Encoding header to |
| 4333 | prevent backend servers from compressing responses. It is strongly |
| 4334 | recommended not to do this because this means that all the compression work |
| 4335 | will be done on the single point where haproxy is located. However in some |
| 4336 | deployment scenarios, haproxy may be installed in front of a buggy gateway |
Dmitry Sivachenko | c9f3b45 | 2012-11-28 17:47:11 +0400 | [diff] [blame] | 4337 | with broken HTTP compression implementation which can't be turned off. |
| 4338 | In that case haproxy can be used to prevent that gateway from emitting |
| 4339 | invalid payloads. In this case, simply removing the header in the |
| 4340 | configuration does not work because it applies before the header is parsed, |
| 4341 | so that prevents haproxy from compressing. The "offload" setting should |
Willy Tarreau | ffea9fd | 2014-07-12 16:37:02 +0200 | [diff] [blame] | 4342 | then be used for such scenarios. Note: for now, the "offload" setting is |
| 4343 | ignored when set in a defaults section. |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 4344 | |
William Lallemand | 0509744 | 2012-11-20 12:14:28 +0100 | [diff] [blame] | 4345 | Compression is disabled when: |
Baptiste Assmann | 650d53d | 2013-01-05 15:44:44 +0100 | [diff] [blame] | 4346 | * the request does not advertise a supported compression algorithm in the |
| 4347 | "Accept-Encoding" header |
Julien Pivotto | ff80c82 | 2021-03-29 12:41:40 +0200 | [diff] [blame] | 4348 | * the response message is not HTTP/1.1 or above |
Tim Duesterhus | bb48c9a | 2019-01-30 23:46:04 +0100 | [diff] [blame] | 4349 | * HTTP status code is not one of 200, 201, 202, or 203 |
Baptiste Assmann | 650d53d | 2013-01-05 15:44:44 +0100 | [diff] [blame] | 4350 | * response contain neither a "Content-Length" header nor a |
| 4351 | "Transfer-Encoding" whose last value is "chunked" |
| 4352 | * response contains a "Content-Type" header whose first value starts with |
| 4353 | "multipart" |
| 4354 | * the response contains the "no-transform" value in the "Cache-control" |
| 4355 | header |
| 4356 | * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7 |
| 4357 | and later |
| 4358 | * The response contains a "Content-Encoding" header, indicating that the |
| 4359 | response is already compressed (see compression offload) |
Tim Duesterhus | bb48c9a | 2019-01-30 23:46:04 +0100 | [diff] [blame] | 4360 | * The response contains an invalid "ETag" header or multiple ETag headers |
William Lallemand | 0509744 | 2012-11-20 12:14:28 +0100 | [diff] [blame] | 4361 | |
Tim Duesterhus | b229f01 | 2019-01-29 16:38:56 +0100 | [diff] [blame] | 4362 | Note: The compression does not emit the Warning header. |
William Lallemand | 0509744 | 2012-11-20 12:14:28 +0100 | [diff] [blame] | 4363 | |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 4364 | Examples : |
| 4365 | compression algo gzip |
| 4366 | compression type text/html text/plain |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4367 | |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 4368 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 4369 | cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ] |
Willy Tarreau | 4992dd2 | 2012-05-31 21:02:17 +0200 | [diff] [blame] | 4370 | [ postonly ] [ preserve ] [ httponly ] [ secure ] |
| 4371 | [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ] |
Christopher Faulet | 2f53390 | 2020-01-21 11:06:48 +0100 | [diff] [blame] | 4372 | [ dynamic ] [ attr <value> ]* |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4373 | Enable cookie-based persistence in a backend. |
| 4374 | May be used in sections : defaults | frontend | listen | backend |
| 4375 | yes | no | yes | yes |
| 4376 | Arguments : |
| 4377 | <name> is the name of the cookie which will be monitored, modified or |
| 4378 | inserted in order to bring persistence. This cookie is sent to |
| 4379 | the client via a "Set-Cookie" header in the response, and is |
| 4380 | brought back by the client in a "Cookie" header in all requests. |
| 4381 | Special care should be taken to choose a name which does not |
| 4382 | conflict with any likely application cookie. Also, if the same |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4383 | backends are subject to be used by the same clients (e.g. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4384 | HTTP/HTTPS), care should be taken to use different cookie names |
| 4385 | between all backends if persistence between them is not desired. |
| 4386 | |
| 4387 | rewrite This keyword indicates that the cookie will be provided by the |
| 4388 | server and that haproxy will have to modify its value to set the |
| 4389 | server's identifier in it. This mode is handy when the management |
| 4390 | of complex combinations of "Set-cookie" and "Cache-control" |
| 4391 | headers is left to the application. The application can then |
| 4392 | decide whether or not it is appropriate to emit a persistence |
Lukas Tribus | f01a9cd | 2016-02-03 18:09:37 +0100 | [diff] [blame] | 4393 | cookie. Since all responses should be monitored, this mode |
| 4394 | doesn't work in HTTP tunnel mode. Unless the application |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4395 | behavior is very complex and/or broken, it is advised not to |
Lukas Tribus | f01a9cd | 2016-02-03 18:09:37 +0100 | [diff] [blame] | 4396 | start with this mode for new deployments. This keyword is |
| 4397 | incompatible with "insert" and "prefix". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4398 | |
| 4399 | insert This keyword indicates that the persistence cookie will have to |
Willy Tarreau | a79094d | 2010-08-31 22:54:15 +0200 | [diff] [blame] | 4400 | be inserted by haproxy in server responses if the client did not |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 4401 | |
Willy Tarreau | a79094d | 2010-08-31 22:54:15 +0200 | [diff] [blame] | 4402 | already have a cookie that would have permitted it to access this |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 4403 | server. When used without the "preserve" option, if the server |
Michael Prokop | 4438c60 | 2019-05-24 10:25:45 +0200 | [diff] [blame] | 4404 | emits a cookie with the same name, it will be removed before |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4405 | processing. For this reason, this mode can be used to upgrade |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 4406 | existing configurations running in the "rewrite" mode. The cookie |
| 4407 | will only be a session cookie and will not be stored on the |
| 4408 | client's disk. By default, unless the "indirect" option is added, |
| 4409 | the server will see the cookies emitted by the client. Due to |
| 4410 | caching effects, it is generally wise to add the "nocache" or |
| 4411 | "postonly" keywords (see below). The "insert" keyword is not |
| 4412 | compatible with "rewrite" and "prefix". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4413 | |
| 4414 | prefix This keyword indicates that instead of relying on a dedicated |
| 4415 | cookie for the persistence, an existing one will be completed. |
| 4416 | This may be needed in some specific environments where the client |
| 4417 | does not support more than one single cookie and the application |
| 4418 | already needs it. In this case, whenever the server sets a cookie |
| 4419 | named <name>, it will be prefixed with the server's identifier |
| 4420 | and a delimiter. The prefix will be removed from all client |
| 4421 | requests so that the server still finds the cookie it emitted. |
| 4422 | Since all requests and responses are subject to being modified, |
Lukas Tribus | f01a9cd | 2016-02-03 18:09:37 +0100 | [diff] [blame] | 4423 | this mode doesn't work with tunnel mode. The "prefix" keyword is |
Willy Tarreau | 37229df | 2011-10-17 12:24:55 +0200 | [diff] [blame] | 4424 | not compatible with "rewrite" and "insert". Note: it is highly |
| 4425 | recommended not to use "indirect" with "prefix", otherwise server |
| 4426 | cookie updates would not be sent to clients. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4427 | |
Willy Tarreau | a79094d | 2010-08-31 22:54:15 +0200 | [diff] [blame] | 4428 | indirect When this option is specified, no cookie will be emitted to a |
| 4429 | client which already has a valid one for the server which has |
| 4430 | processed the request. If the server sets such a cookie itself, |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 4431 | it will be removed, unless the "preserve" option is also set. In |
| 4432 | "insert" mode, this will additionally remove cookies from the |
| 4433 | requests transmitted to the server, making the persistence |
| 4434 | mechanism totally transparent from an application point of view. |
Willy Tarreau | 37229df | 2011-10-17 12:24:55 +0200 | [diff] [blame] | 4435 | Note: it is highly recommended not to use "indirect" with |
| 4436 | "prefix", otherwise server cookie updates would not be sent to |
| 4437 | clients. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4438 | |
| 4439 | nocache This option is recommended in conjunction with the insert mode |
| 4440 | when there is a cache between the client and HAProxy, as it |
| 4441 | ensures that a cacheable response will be tagged non-cacheable if |
| 4442 | a cookie needs to be inserted. This is important because if all |
| 4443 | persistence cookies are added on a cacheable home page for |
| 4444 | instance, then all customers will then fetch the page from an |
| 4445 | outer cache and will all share the same persistence cookie, |
| 4446 | leading to one server receiving much more traffic than others. |
| 4447 | See also the "insert" and "postonly" options. |
| 4448 | |
| 4449 | postonly This option ensures that cookie insertion will only be performed |
| 4450 | on responses to POST requests. It is an alternative to the |
| 4451 | "nocache" option, because POST responses are not cacheable, so |
| 4452 | this ensures that the persistence cookie will never get cached. |
| 4453 | Since most sites do not need any sort of persistence before the |
| 4454 | first POST which generally is a login request, this is a very |
| 4455 | efficient method to optimize caching without risking to find a |
| 4456 | persistence cookie in the cache. |
| 4457 | See also the "insert" and "nocache" options. |
| 4458 | |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 4459 | preserve This option may only be used with "insert" and/or "indirect". It |
| 4460 | allows the server to emit the persistence cookie itself. In this |
| 4461 | case, if a cookie is found in the response, haproxy will leave it |
| 4462 | untouched. This is useful in order to end persistence after a |
| 4463 | logout request for instance. For this, the server just has to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4464 | emit a cookie with an invalid value (e.g. empty) or with a date in |
Willy Tarreau | ba4c5be | 2010-10-23 12:46:42 +0200 | [diff] [blame] | 4465 | the past. By combining this mechanism with the "disable-on-404" |
| 4466 | check option, it is possible to perform a completely graceful |
| 4467 | shutdown because users will definitely leave the server after |
| 4468 | they logout. |
| 4469 | |
Willy Tarreau | 4992dd2 | 2012-05-31 21:02:17 +0200 | [diff] [blame] | 4470 | httponly This option tells haproxy to add an "HttpOnly" cookie attribute |
| 4471 | when a cookie is inserted. This attribute is used so that a |
| 4472 | user agent doesn't share the cookie with non-HTTP components. |
| 4473 | Please check RFC6265 for more information on this attribute. |
| 4474 | |
| 4475 | secure This option tells haproxy to add a "Secure" cookie attribute when |
| 4476 | a cookie is inserted. This attribute is used so that a user agent |
| 4477 | never emits this cookie over non-secure channels, which means |
| 4478 | that a cookie learned with this flag will be presented only over |
| 4479 | SSL/TLS connections. Please check RFC6265 for more information on |
| 4480 | this attribute. |
| 4481 | |
Krzysztof Piotr Oledzki | efe3b6f | 2008-05-23 23:49:32 +0200 | [diff] [blame] | 4482 | 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] | 4483 | inserted. It requires exactly one parameter: a valid domain |
Willy Tarreau | 68a897b | 2009-12-03 23:28:34 +0100 | [diff] [blame] | 4484 | name. If the domain begins with a dot, the browser is allowed to |
| 4485 | use it for any host ending with that name. It is also possible to |
| 4486 | specify several domain names by invoking this option multiple |
| 4487 | times. Some browsers might have small limits on the number of |
| 4488 | domains, so be careful when doing that. For the record, sending |
| 4489 | 10 domains to MSIE 6 or Firefox 2 works as expected. |
Krzysztof Piotr Oledzki | efe3b6f | 2008-05-23 23:49:32 +0200 | [diff] [blame] | 4490 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 4491 | maxidle This option allows inserted cookies to be ignored after some idle |
| 4492 | time. It only works with insert-mode cookies. When a cookie is |
| 4493 | sent to the client, the date this cookie was emitted is sent too. |
| 4494 | Upon further presentations of this cookie, if the date is older |
| 4495 | than the delay indicated by the parameter (in seconds), it will |
| 4496 | be ignored. Otherwise, it will be refreshed if needed when the |
| 4497 | response is sent to the client. This is particularly useful to |
| 4498 | prevent users who never close their browsers from remaining for |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4499 | too long on the same server (e.g. after a farm size change). When |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 4500 | this option is set and a cookie has no date, it is always |
| 4501 | accepted, but gets refreshed in the response. This maintains the |
| 4502 | ability for admins to access their sites. Cookies that have a |
| 4503 | date in the future further than 24 hours are ignored. Doing so |
| 4504 | lets admins fix timezone issues without risking kicking users off |
| 4505 | the site. |
| 4506 | |
| 4507 | maxlife This option allows inserted cookies to be ignored after some life |
| 4508 | time, whether they're in use or not. It only works with insert |
| 4509 | mode cookies. When a cookie is first sent to the client, the date |
| 4510 | this cookie was emitted is sent too. Upon further presentations |
| 4511 | of this cookie, if the date is older than the delay indicated by |
| 4512 | the parameter (in seconds), it will be ignored. If the cookie in |
| 4513 | the request has no date, it is accepted and a date will be set. |
| 4514 | Cookies that have a date in the future further than 24 hours are |
| 4515 | ignored. Doing so lets admins fix timezone issues without risking |
| 4516 | kicking users off the site. Contrary to maxidle, this value is |
| 4517 | not refreshed, only the first visit date counts. Both maxidle and |
| 4518 | maxlife may be used at the time. This is particularly useful to |
| 4519 | prevent users who never close their browsers from remaining for |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4520 | too long on the same server (e.g. after a farm size change). This |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 4521 | is stronger than the maxidle method in that it forces a |
| 4522 | redispatch after some absolute delay. |
| 4523 | |
Olivier Houchard | 4e69404 | 2017-03-14 20:01:29 +0100 | [diff] [blame] | 4524 | dynamic Activate dynamic cookies. When used, a session cookie is |
| 4525 | dynamically created for each server, based on the IP and port |
| 4526 | of the server, and a secret key, specified in the |
| 4527 | "dynamic-cookie-key" backend directive. |
| 4528 | The cookie will be regenerated each time the IP address change, |
| 4529 | and is only generated for IPv4/IPv6. |
| 4530 | |
Christopher Faulet | 2f53390 | 2020-01-21 11:06:48 +0100 | [diff] [blame] | 4531 | attr This option tells haproxy to add an extra attribute when a |
| 4532 | cookie is inserted. The attribute value can contain any |
| 4533 | characters except control ones or ";". This option may be |
| 4534 | repeated. |
| 4535 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4536 | There can be only one persistence cookie per HTTP backend, and it can be |
| 4537 | declared in a defaults section. The value of the cookie will be the value |
| 4538 | indicated after the "cookie" keyword in a "server" statement. If no cookie |
| 4539 | is declared for a given server, the cookie is not set. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 4540 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4541 | Examples : |
| 4542 | cookie JSESSIONID prefix |
| 4543 | cookie SRV insert indirect nocache |
| 4544 | cookie SRV insert postonly indirect |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 4545 | cookie SRV insert indirect nocache maxidle 30m maxlife 8h |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4546 | |
Willy Tarreau | 294d0f0 | 2015-08-10 19:40:12 +0200 | [diff] [blame] | 4547 | See also : "balance source", "capture cookie", "server" and "ignore-persist". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4548 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 4549 | |
Thierry FOURNIER | a0a1b75 | 2015-05-26 17:44:32 +0200 | [diff] [blame] | 4550 | declare capture [ request | response ] len <length> |
| 4551 | Declares a capture slot. |
| 4552 | May be used in sections : defaults | frontend | listen | backend |
| 4553 | no | yes | yes | no |
| 4554 | Arguments: |
| 4555 | <length> is the length allowed for the capture. |
| 4556 | |
| 4557 | This declaration is only available in the frontend or listen section, but the |
| 4558 | reserved slot can be used in the backends. The "request" keyword allocates a |
| 4559 | capture slot for use in the request, and "response" allocates a capture slot |
| 4560 | for use in the response. |
| 4561 | |
| 4562 | See also: "capture-req", "capture-res" (sample converters), |
Baptiste Assmann | 5ac425c | 2015-10-21 23:13:46 +0200 | [diff] [blame] | 4563 | "capture.req.hdr", "capture.res.hdr" (sample fetches), |
Thierry FOURNIER | a0a1b75 | 2015-05-26 17:44:32 +0200 | [diff] [blame] | 4564 | "http-request capture" and "http-response capture". |
| 4565 | |
| 4566 | |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 4567 | default-server [param*] |
| 4568 | Change default options for a server in a backend |
| 4569 | May be used in sections : defaults | frontend | listen | backend |
| 4570 | yes | no | yes | yes |
| 4571 | Arguments: |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 4572 | <param*> is a list of parameters for this server. The "default-server" |
| 4573 | keyword accepts an important number of options and has a complete |
| 4574 | section dedicated to it. Please refer to section 5 for more |
| 4575 | details. |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 4576 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 4577 | Example : |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 4578 | default-server inter 1000 weight 13 |
| 4579 | |
| 4580 | See also: "server" and section 5 about server options |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4581 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 4582 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4583 | default_backend <backend> |
| 4584 | Specify the backend to use when no "use_backend" rule has been matched. |
| 4585 | May be used in sections : defaults | frontend | listen | backend |
| 4586 | yes | yes | yes | no |
| 4587 | Arguments : |
| 4588 | <backend> is the name of the backend to use. |
| 4589 | |
| 4590 | When doing content-switching between frontend and backends using the |
| 4591 | "use_backend" keyword, it is often useful to indicate which backend will be |
| 4592 | used when no rule has matched. It generally is the dynamic backend which |
| 4593 | will catch all undetermined requests. |
| 4594 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4595 | Example : |
| 4596 | |
| 4597 | use_backend dynamic if url_dyn |
| 4598 | use_backend static if url_css url_img extension_img |
| 4599 | default_backend dynamic |
| 4600 | |
Willy Tarreau | 98d0485 | 2015-05-26 12:18:29 +0200 | [diff] [blame] | 4601 | See also : "use_backend" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4602 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4603 | |
Baptiste Assmann | 27f5134 | 2013-10-09 06:51:49 +0200 | [diff] [blame] | 4604 | description <string> |
| 4605 | Describe a listen, frontend or backend. |
| 4606 | May be used in sections : defaults | frontend | listen | backend |
| 4607 | no | yes | yes | yes |
| 4608 | Arguments : string |
| 4609 | |
| 4610 | Allows to add a sentence to describe the related object in the HAProxy HTML |
| 4611 | stats page. The description will be printed on the right of the object name |
| 4612 | it describes. |
| 4613 | No need to backslash spaces in the <string> arguments. |
| 4614 | |
| 4615 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4616 | disabled |
| 4617 | Disable a proxy, frontend or backend. |
| 4618 | May be used in sections : defaults | frontend | listen | backend |
| 4619 | yes | yes | yes | yes |
| 4620 | Arguments : none |
| 4621 | |
| 4622 | The "disabled" keyword is used to disable an instance, mainly in order to |
| 4623 | liberate a listening port or to temporarily disable a service. The instance |
| 4624 | will still be created and its configuration will be checked, but it will be |
| 4625 | created in the "stopped" state and will appear as such in the statistics. It |
| 4626 | will not receive any traffic nor will it send any health-checks or logs. It |
| 4627 | is possible to disable many instances at once by adding the "disabled" |
| 4628 | keyword in a "defaults" section. |
| 4629 | |
| 4630 | See also : "enabled" |
| 4631 | |
| 4632 | |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 4633 | dispatch <address>:<port> |
| 4634 | Set a default server address |
| 4635 | May be used in sections : defaults | frontend | listen | backend |
| 4636 | no | no | yes | yes |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 4637 | Arguments : |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 4638 | |
| 4639 | <address> is the IPv4 address of the default server. Alternatively, a |
| 4640 | resolvable hostname is supported, but this name will be resolved |
| 4641 | during start-up. |
| 4642 | |
| 4643 | <ports> is a mandatory port specification. All connections will be sent |
| 4644 | to this port, and it is not permitted to use port offsets as is |
| 4645 | possible with normal servers. |
| 4646 | |
Willy Tarreau | 787aed5 | 2011-04-15 06:45:37 +0200 | [diff] [blame] | 4647 | The "dispatch" keyword designates a default server for use when no other |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 4648 | server can take the connection. In the past it was used to forward non |
| 4649 | persistent connections to an auxiliary load balancer. Due to its simple |
| 4650 | syntax, it has also been used for simple TCP relays. It is recommended not to |
| 4651 | use it for more clarity, and to use the "server" directive instead. |
| 4652 | |
| 4653 | See also : "server" |
| 4654 | |
Olivier Houchard | 4e69404 | 2017-03-14 20:01:29 +0100 | [diff] [blame] | 4655 | |
| 4656 | dynamic-cookie-key <string> |
| 4657 | Set the dynamic cookie secret key for a backend. |
| 4658 | May be used in sections : defaults | frontend | listen | backend |
| 4659 | yes | no | yes | yes |
| 4660 | Arguments : The secret key to be used. |
| 4661 | |
| 4662 | When dynamic cookies are enabled (see the "dynamic" directive for cookie), |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4663 | a dynamic cookie is created for each server (unless one is explicitly |
Olivier Houchard | 4e69404 | 2017-03-14 20:01:29 +0100 | [diff] [blame] | 4664 | specified on the "server" line), using a hash of the IP address of the |
| 4665 | server, the TCP port, and the secret key. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4666 | That way, we can ensure session persistence across multiple load-balancers, |
Olivier Houchard | 4e69404 | 2017-03-14 20:01:29 +0100 | [diff] [blame] | 4667 | even if servers are dynamically added or removed. |
Willy Tarreau | 5ce9457 | 2010-06-07 14:35:41 +0200 | [diff] [blame] | 4668 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4669 | enabled |
| 4670 | Enable a proxy, frontend or backend. |
| 4671 | May be used in sections : defaults | frontend | listen | backend |
| 4672 | yes | yes | yes | yes |
| 4673 | Arguments : none |
| 4674 | |
| 4675 | The "enabled" keyword is used to explicitly enable an instance, when the |
| 4676 | defaults has been set to "disabled". This is very rarely used. |
| 4677 | |
| 4678 | See also : "disabled" |
| 4679 | |
| 4680 | |
| 4681 | errorfile <code> <file> |
| 4682 | Return a file contents instead of errors generated by HAProxy |
| 4683 | May be used in sections : defaults | frontend | listen | backend |
| 4684 | yes | yes | yes | yes |
| 4685 | Arguments : |
| 4686 | <code> is the HTTP status code. Currently, HAProxy is capable of |
Christopher Faulet | 612f2ea | 2020-05-27 09:57:28 +0200 | [diff] [blame] | 4687 | generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 4688 | 413, 425, 429, 500, 501, 502, 503, and 504. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4689 | |
| 4690 | <file> designates a file containing the full HTTP response. It is |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 4691 | recommended to follow the common practice of appending ".http" to |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4692 | the filename so that people do not confuse the response with HTML |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 4693 | error pages, and to use absolute paths, since files are read |
| 4694 | before any chroot is performed. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4695 | |
| 4696 | It is important to understand that this keyword is not meant to rewrite |
| 4697 | errors returned by the server, but errors detected and returned by HAProxy. |
| 4698 | This is why the list of supported errors is limited to a small set. |
| 4699 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 4700 | Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| 4701 | |
Christopher Faulet | 7017067 | 2020-05-18 17:42:48 +0200 | [diff] [blame] | 4702 | The files are parsed when HAProxy starts and must be valid according to the |
| 4703 | HTTP specification. They should not exceed the configured buffer size |
| 4704 | (BUFSIZE), which generally is 16 kB, otherwise an internal error will be |
| 4705 | returned. It is also wise not to put any reference to local contents |
| 4706 | (e.g. images) in order to avoid loops between the client and HAProxy when all |
| 4707 | servers are down, causing an error to be returned instead of an |
| 4708 | image. Finally, The response cannot exceed (tune.bufsize - tune.maxrewrite) |
| 4709 | so that "http-after-response" rules still have room to operate (see |
| 4710 | "tune.maxrewrite"). |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 4711 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4712 | The files are read at the same time as the configuration and kept in memory. |
| 4713 | For this reason, the errors continue to be returned even when the process is |
| 4714 | 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] | 4715 | simple method for developing those files consists in associating them to the |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4716 | 403 status code and interrogating a blocked URL. |
| 4717 | |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 4718 | See also : "http-error", "errorloc", "errorloc302", "errorloc303" |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4719 | |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 4720 | Example : |
| 4721 | errorfile 400 /etc/haproxy/errorfiles/400badreq.http |
Willy Tarreau | 989222a | 2016-01-15 10:26:26 +0100 | [diff] [blame] | 4722 | errorfile 408 /dev/null # work around Chrome pre-connect bug |
Willy Tarreau | 59140a2 | 2009-02-22 12:02:30 +0100 | [diff] [blame] | 4723 | errorfile 403 /etc/haproxy/errorfiles/403forbid.http |
| 4724 | errorfile 503 /etc/haproxy/errorfiles/503sorry.http |
| 4725 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4726 | |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 4727 | errorfiles <name> [<code> ...] |
| 4728 | Import, fully or partially, the error files defined in the <name> http-errors |
| 4729 | section. |
| 4730 | May be used in sections : defaults | frontend | listen | backend |
| 4731 | yes | yes | yes | yes |
| 4732 | Arguments : |
| 4733 | <name> is the name of an existing http-errors section. |
| 4734 | |
| 4735 | <code> is a HTTP status code. Several status code may be listed. |
Christopher Faulet | 612f2ea | 2020-05-27 09:57:28 +0200 | [diff] [blame] | 4736 | Currently, HAProxy is capable of generating codes 200, 400, 401, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 4737 | 403, 404, 405, 407, 408, 410, 413, 425, 429, 500, 501, 502, 503, |
| 4738 | and 504. |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 4739 | |
| 4740 | Errors defined in the http-errors section with the name <name> are imported |
| 4741 | in the current proxy. If no status code is specified, all error files of the |
| 4742 | http-errors section are imported. Otherwise, only error files associated to |
| 4743 | the listed status code are imported. Those error files override the already |
| 4744 | defined custom errors for the proxy. And they may be overridden by following |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 4745 | ones. Functionally, it is exactly the same as declaring all error files by |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 4746 | hand using "errorfile" directives. |
| 4747 | |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 4748 | See also : "http-error", "errorfile", "errorloc", "errorloc302" , |
| 4749 | "errorloc303" and section 3.8 about http-errors. |
Christopher Faulet | 76edc0f | 2020-01-13 15:52:01 +0100 | [diff] [blame] | 4750 | |
| 4751 | Example : |
| 4752 | errorfiles generic |
| 4753 | errorfiles site-1 403 404 |
| 4754 | |
| 4755 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4756 | errorloc <code> <url> |
| 4757 | errorloc302 <code> <url> |
| 4758 | Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| 4759 | May be used in sections : defaults | frontend | listen | backend |
| 4760 | yes | yes | yes | yes |
| 4761 | Arguments : |
| 4762 | <code> is the HTTP status code. Currently, HAProxy is capable of |
Christopher Faulet | 612f2ea | 2020-05-27 09:57:28 +0200 | [diff] [blame] | 4763 | generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 4764 | 413, 425, 429, 500, 501, 502, 503, and 504. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4765 | |
| 4766 | <url> it is the exact contents of the "Location" header. It may contain |
| 4767 | either a relative URI to an error page hosted on the same site, |
| 4768 | or an absolute URI designating an error page on another site. |
| 4769 | Special care should be given to relative URIs to avoid redirect |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4770 | loops if the URI itself may generate the same error (e.g. 500). |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4771 | |
| 4772 | It is important to understand that this keyword is not meant to rewrite |
| 4773 | errors returned by the server, but errors detected and returned by HAProxy. |
| 4774 | This is why the list of supported errors is limited to a small set. |
| 4775 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 4776 | Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| 4777 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4778 | Note that both keyword return the HTTP 302 status code, which tells the |
| 4779 | client to fetch the designated URL using the same HTTP method. This can be |
| 4780 | quite problematic in case of non-GET methods such as POST, because the URL |
| 4781 | sent to the client might not be allowed for something other than GET. To |
Willy Tarreau | 989222a | 2016-01-15 10:26:26 +0100 | [diff] [blame] | 4782 | work around this problem, please use "errorloc303" which send the HTTP 303 |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4783 | status code, indicating to the client that the URL must be fetched with a GET |
| 4784 | request. |
| 4785 | |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 4786 | See also : "http-error", "errorfile", "errorloc303" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4787 | |
| 4788 | |
| 4789 | errorloc303 <code> <url> |
| 4790 | Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| 4791 | May be used in sections : defaults | frontend | listen | backend |
| 4792 | yes | yes | yes | yes |
| 4793 | Arguments : |
| 4794 | <code> is the HTTP status code. Currently, HAProxy is capable of |
Christopher Faulet | 612f2ea | 2020-05-27 09:57:28 +0200 | [diff] [blame] | 4795 | generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 4796 | 413, 425, 429, 500, 501, 502, 503, and 504. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4797 | |
| 4798 | <url> it is the exact contents of the "Location" header. It may contain |
| 4799 | either a relative URI to an error page hosted on the same site, |
| 4800 | or an absolute URI designating an error page on another site. |
| 4801 | Special care should be given to relative URIs to avoid redirect |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4802 | loops if the URI itself may generate the same error (e.g. 500). |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4803 | |
| 4804 | It is important to understand that this keyword is not meant to rewrite |
| 4805 | errors returned by the server, but errors detected and returned by HAProxy. |
| 4806 | This is why the list of supported errors is limited to a small set. |
| 4807 | |
Willy Tarreau | ae94d4d | 2011-05-11 16:28:49 +0200 | [diff] [blame] | 4808 | Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| 4809 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4810 | Note that both keyword return the HTTP 303 status code, which tells the |
| 4811 | client to fetch the designated URL using the same HTTP GET method. This |
| 4812 | solves the usual problems associated with "errorloc" and the 302 code. It is |
| 4813 | 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] | 4814 | it, but no such problem has been reported till now. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4815 | |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 4816 | See also : "http-error", "errorfile", "errorloc", "errorloc302" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4817 | |
| 4818 | |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4819 | email-alert from <emailaddr> |
| 4820 | Declare the from email address to be used in both the envelope and header |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4821 | of email alerts. This is the address that email alerts are sent from. |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4822 | May be used in sections: defaults | frontend | listen | backend |
| 4823 | yes | yes | yes | yes |
| 4824 | |
| 4825 | Arguments : |
| 4826 | |
| 4827 | <emailaddr> is the from email address to use when sending email alerts |
| 4828 | |
| 4829 | Also requires "email-alert mailers" and "email-alert to" to be set |
| 4830 | and if so sending email alerts is enabled for the proxy. |
| 4831 | |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 4832 | See also : "email-alert level", "email-alert mailers", |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 4833 | "email-alert myhostname", "email-alert to", section 3.6 about |
| 4834 | mailers. |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 4835 | |
| 4836 | |
| 4837 | email-alert level <level> |
| 4838 | Declare the maximum log level of messages for which email alerts will be |
| 4839 | sent. This acts as a filter on the sending of email alerts. |
| 4840 | May be used in sections: defaults | frontend | listen | backend |
| 4841 | yes | yes | yes | yes |
| 4842 | |
| 4843 | Arguments : |
| 4844 | |
| 4845 | <level> One of the 8 syslog levels: |
| 4846 | emerg alert crit err warning notice info debug |
| 4847 | The above syslog levels are ordered from lowest to highest. |
| 4848 | |
| 4849 | By default level is alert |
| 4850 | |
| 4851 | Also requires "email-alert from", "email-alert mailers" and |
| 4852 | "email-alert to" to be set and if so sending email alerts is enabled |
| 4853 | for the proxy. |
| 4854 | |
Simon Horman | 1421e21 | 2015-04-30 13:10:35 +0900 | [diff] [blame] | 4855 | Alerts are sent when : |
| 4856 | |
| 4857 | * An un-paused server is marked as down and <level> is alert or lower |
| 4858 | * A paused server is marked as down and <level> is notice or lower |
| 4859 | * A server is marked as up or enters the drain state and <level> |
| 4860 | is notice or lower |
| 4861 | * "option log-health-checks" is enabled, <level> is info or lower, |
| 4862 | and a health check status update occurs |
| 4863 | |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 4864 | See also : "email-alert from", "email-alert mailers", |
| 4865 | "email-alert myhostname", "email-alert to", |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4866 | section 3.6 about mailers. |
| 4867 | |
| 4868 | |
| 4869 | email-alert mailers <mailersect> |
| 4870 | Declare the mailers to be used when sending email alerts |
| 4871 | May be used in sections: defaults | frontend | listen | backend |
| 4872 | yes | yes | yes | yes |
| 4873 | |
| 4874 | Arguments : |
| 4875 | |
| 4876 | <mailersect> is the name of the mailers section to send email alerts. |
| 4877 | |
| 4878 | Also requires "email-alert from" and "email-alert to" to be set |
| 4879 | and if so sending email alerts is enabled for the proxy. |
| 4880 | |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 4881 | See also : "email-alert from", "email-alert level", "email-alert myhostname", |
| 4882 | "email-alert to", section 3.6 about mailers. |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4883 | |
| 4884 | |
| 4885 | email-alert myhostname <hostname> |
| 4886 | Declare the to hostname address to be used when communicating with |
| 4887 | mailers. |
| 4888 | May be used in sections: defaults | frontend | listen | backend |
| 4889 | yes | yes | yes | yes |
| 4890 | |
| 4891 | Arguments : |
| 4892 | |
Baptiste Assmann | 738bad9 | 2015-12-21 15:27:53 +0100 | [diff] [blame] | 4893 | <hostname> is the hostname to use when communicating with mailers |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4894 | |
| 4895 | By default the systems hostname is used. |
| 4896 | |
| 4897 | Also requires "email-alert from", "email-alert mailers" and |
| 4898 | "email-alert to" to be set and if so sending email alerts is enabled |
| 4899 | for the proxy. |
| 4900 | |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 4901 | See also : "email-alert from", "email-alert level", "email-alert mailers", |
| 4902 | "email-alert to", section 3.6 about mailers. |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4903 | |
| 4904 | |
| 4905 | email-alert to <emailaddr> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 4906 | Declare both the recipient address in the envelope and to address in the |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4907 | header of email alerts. This is the address that email alerts are sent to. |
| 4908 | May be used in sections: defaults | frontend | listen | backend |
| 4909 | yes | yes | yes | yes |
| 4910 | |
| 4911 | Arguments : |
| 4912 | |
| 4913 | <emailaddr> is the to email address to use when sending email alerts |
| 4914 | |
| 4915 | Also requires "email-alert mailers" and "email-alert to" to be set |
| 4916 | and if so sending email alerts is enabled for the proxy. |
| 4917 | |
Simon Horman | 64e3416 | 2015-02-06 11:11:57 +0900 | [diff] [blame] | 4918 | See also : "email-alert from", "email-alert level", "email-alert mailers", |
Simon Horman | 51a1cf6 | 2015-02-03 13:00:44 +0900 | [diff] [blame] | 4919 | "email-alert myhostname", section 3.6 about mailers. |
| 4920 | |
| 4921 | |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 4922 | force-persist { if | unless } <condition> |
| 4923 | Declare a condition to force persistence on down servers |
| 4924 | May be used in sections: defaults | frontend | listen | backend |
Cyril Bonté | 4288c5a | 2018-03-12 22:02:59 +0100 | [diff] [blame] | 4925 | no | no | yes | yes |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 4926 | |
| 4927 | By default, requests are not dispatched to down servers. It is possible to |
| 4928 | force this using "option persist", but it is unconditional and redispatches |
| 4929 | to a valid server if "option redispatch" is set. That leaves with very little |
| 4930 | possibilities to force some requests to reach a server which is artificially |
| 4931 | marked down for maintenance operations. |
| 4932 | |
| 4933 | The "force-persist" statement allows one to declare various ACL-based |
| 4934 | conditions which, when met, will cause a request to ignore the down status of |
| 4935 | a server and still try to connect to it. That makes it possible to start a |
| 4936 | server, still replying an error to the health checks, and run a specially |
| 4937 | configured browser to test the service. Among the handy methods, one could |
| 4938 | use a specific source IP address, or a specific cookie. The cookie also has |
| 4939 | the advantage that it can easily be added/removed on the browser from a test |
| 4940 | page. Once the service is validated, it is then possible to open the service |
| 4941 | to the world by returning a valid response to health checks. |
| 4942 | |
| 4943 | The forced persistence is enabled when an "if" condition is met, or unless an |
| 4944 | "unless" condition is met. The final redispatch is always disabled when this |
| 4945 | is used. |
| 4946 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 4947 | See also : "option redispatch", "ignore-persist", "persist", |
Cyril Bonté | a8e7bbc | 2010-04-25 22:29:29 +0200 | [diff] [blame] | 4948 | and section 7 about ACL usage. |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 4949 | |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 4950 | |
| 4951 | filter <name> [param*] |
| 4952 | Add the filter <name> in the filter list attached to the proxy. |
| 4953 | May be used in sections : defaults | frontend | listen | backend |
| 4954 | no | yes | yes | yes |
| 4955 | Arguments : |
| 4956 | <name> is the name of the filter. Officially supported filters are |
| 4957 | referenced in section 9. |
| 4958 | |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 4959 | <param*> is a list of parameters accepted by the filter <name>. The |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 4960 | parsing of these parameters are the responsibility of the |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 4961 | filter. Please refer to the documentation of the corresponding |
| 4962 | filter (section 9) for all details on the supported parameters. |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 4963 | |
| 4964 | Multiple occurrences of the filter line can be used for the same proxy. The |
| 4965 | same filter can be referenced many times if needed. |
| 4966 | |
| 4967 | Example: |
| 4968 | listen |
| 4969 | bind *:80 |
| 4970 | |
| 4971 | filter trace name BEFORE-HTTP-COMP |
| 4972 | filter compression |
| 4973 | filter trace name AFTER-HTTP-COMP |
| 4974 | |
| 4975 | compression algo gzip |
| 4976 | compression offload |
| 4977 | |
| 4978 | server srv1 192.168.0.1:80 |
| 4979 | |
| 4980 | See also : section 9. |
| 4981 | |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 4982 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4983 | fullconn <conns> |
| 4984 | Specify at what backend load the servers will reach their maxconn |
| 4985 | May be used in sections : defaults | frontend | listen | backend |
| 4986 | yes | no | yes | yes |
| 4987 | Arguments : |
| 4988 | <conns> is the number of connections on the backend which will make the |
| 4989 | servers use the maximal number of connections. |
| 4990 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4991 | 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] | 4992 | of concurrent connections will never go higher. Additionally, if it has a |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4993 | "minconn" parameter, it indicates a dynamic limit following the backend's |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 4994 | load. The server will then always accept at least <minconn> connections, |
| 4995 | never more than <maxconn>, and the limit will be on the ramp between both |
| 4996 | values when the backend has less than <conns> concurrent connections. This |
| 4997 | makes it possible to limit the load on the servers during normal loads, but |
| 4998 | push it further for important loads without overloading the servers during |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 4999 | exceptional loads. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5000 | |
Willy Tarreau | fbb7842 | 2011-06-05 15:38:35 +0200 | [diff] [blame] | 5001 | Since it's hard to get this value right, haproxy automatically sets it to |
| 5002 | 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] | 5003 | backend (based on "use_backend" and "default_backend" rules). That way it's |
| 5004 | safe to leave it unset. However, "use_backend" involving dynamic names are |
| 5005 | 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] | 5006 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5007 | Example : |
| 5008 | # The servers will accept between 100 and 1000 concurrent connections each |
| 5009 | # and the maximum of 1000 will be reached when the backend reaches 10000 |
| 5010 | # connections. |
| 5011 | backend dynamic |
| 5012 | fullconn 10000 |
| 5013 | server srv1 dyn1:80 minconn 100 maxconn 1000 |
| 5014 | server srv2 dyn2:80 minconn 100 maxconn 1000 |
| 5015 | |
| 5016 | See also : "maxconn", "server" |
| 5017 | |
| 5018 | |
Willy Tarreau | ab0a519 | 2020-10-09 19:07:01 +0200 | [diff] [blame] | 5019 | grace <time> (deprecated) |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5020 | Maintain a proxy operational for some time after a soft stop |
| 5021 | May be used in sections : defaults | frontend | listen | backend |
Cyril Bonté | 99ed327 | 2010-01-24 23:29:44 +0100 | [diff] [blame] | 5022 | yes | yes | yes | yes |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5023 | Arguments : |
| 5024 | <time> is the time (by default in milliseconds) for which the instance |
| 5025 | will remain operational with the frontend sockets still listening |
| 5026 | when a soft-stop is received via the SIGUSR1 signal. |
| 5027 | |
| 5028 | This may be used to ensure that the services disappear in a certain order. |
| 5029 | 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] | 5030 | external equipment fail immediately while other ones remain up for the time |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5031 | needed by the equipment to detect the failure. |
| 5032 | |
| 5033 | Note that currently, there is very little benefit in using this parameter, |
| 5034 | and it may in fact complicate the soft-reconfiguration process more than |
| 5035 | simplify it. |
| 5036 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 5037 | |
Andrew Rodland | 17be45e | 2016-10-25 17:04:12 -0400 | [diff] [blame] | 5038 | hash-balance-factor <factor> |
| 5039 | Specify the balancing factor for bounded-load consistent hashing |
| 5040 | May be used in sections : defaults | frontend | listen | backend |
| 5041 | yes | no | no | yes |
| 5042 | Arguments : |
| 5043 | <factor> is the control for the maximum number of concurrent requests to |
| 5044 | send to a server, expressed as a percentage of the average number |
Frédéric Lécaille | 93d3316 | 2019-03-06 09:35:59 +0100 | [diff] [blame] | 5045 | of concurrent requests across all of the active servers. |
Andrew Rodland | 17be45e | 2016-10-25 17:04:12 -0400 | [diff] [blame] | 5046 | |
| 5047 | Specifying a "hash-balance-factor" for a server with "hash-type consistent" |
| 5048 | enables an algorithm that prevents any one server from getting too many |
| 5049 | requests at once, even if some hash buckets receive many more requests than |
| 5050 | others. Setting <factor> to 0 (the default) disables the feature. Otherwise, |
| 5051 | <factor> is a percentage greater than 100. For example, if <factor> is 150, |
| 5052 | then no server will be allowed to have a load more than 1.5 times the average. |
| 5053 | If server weights are used, they will be respected. |
| 5054 | |
| 5055 | If the first-choice server is disqualified, the algorithm will choose another |
| 5056 | server based on the request hash, until a server with additional capacity is |
| 5057 | found. A higher <factor> allows more imbalance between the servers, while a |
| 5058 | lower <factor> means that more servers will be checked on average, affecting |
| 5059 | performance. Reasonable values are from 125 to 200. |
| 5060 | |
Willy Tarreau | 760e81d | 2018-05-03 07:20:40 +0200 | [diff] [blame] | 5061 | This setting is also used by "balance random" which internally relies on the |
| 5062 | consistent hashing mechanism. |
| 5063 | |
Andrew Rodland | 17be45e | 2016-10-25 17:04:12 -0400 | [diff] [blame] | 5064 | See also : "balance" and "hash-type". |
| 5065 | |
| 5066 | |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 5067 | hash-type <method> <function> <modifier> |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 5068 | Specify a method to use for mapping hashes to servers |
| 5069 | May be used in sections : defaults | frontend | listen | backend |
| 5070 | yes | no | yes | yes |
| 5071 | Arguments : |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5072 | <method> is the method used to select a server from the hash computed by |
| 5073 | the <function> : |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 5074 | |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5075 | map-based the hash table is a static array containing all alive servers. |
| 5076 | The hashes will be very smooth, will consider weights, but |
| 5077 | will be static in that weight changes while a server is up |
| 5078 | will be ignored. This means that there will be no slow start. |
| 5079 | Also, since a server is selected by its position in the array, |
| 5080 | most mappings are changed when the server count changes. This |
| 5081 | means that when a server goes up or down, or when a server is |
| 5082 | added to a farm, most connections will be redistributed to |
| 5083 | different servers. This can be inconvenient with caches for |
| 5084 | instance. |
Willy Tarreau | 798a39c | 2010-11-24 15:04:29 +0100 | [diff] [blame] | 5085 | |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5086 | consistent the hash table is a tree filled with many occurrences of each |
| 5087 | server. The hash key is looked up in the tree and the closest |
| 5088 | server is chosen. This hash is dynamic, it supports changing |
| 5089 | weights while the servers are up, so it is compatible with the |
| 5090 | slow start feature. It has the advantage that when a server |
| 5091 | goes up or down, only its associations are moved. When a |
| 5092 | server is added to the farm, only a few part of the mappings |
| 5093 | are redistributed, making it an ideal method for caches. |
| 5094 | However, due to its principle, the distribution will never be |
| 5095 | very smooth and it may sometimes be necessary to adjust a |
| 5096 | server's weight or its ID to get a more balanced distribution. |
| 5097 | In order to get the same distribution on multiple load |
| 5098 | balancers, it is important that all servers have the exact |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 5099 | same IDs. Note: consistent hash uses sdbm and avalanche if no |
| 5100 | hash function is specified. |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5101 | |
| 5102 | <function> is the hash function to be used : |
| 5103 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 5104 | sdbm this function was created initially for sdbm (a public-domain |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5105 | reimplementation of ndbm) database library. It was found to do |
| 5106 | well in scrambling bits, causing better distribution of the keys |
| 5107 | and fewer splits. It also happens to be a good general hashing |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 5108 | function with good distribution, unless the total server weight |
| 5109 | is a multiple of 64, in which case applying the avalanche |
| 5110 | modifier may help. |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5111 | |
| 5112 | djb2 this function was first proposed by Dan Bernstein many years ago |
| 5113 | on comp.lang.c. Studies have shown that for certain workload this |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 5114 | function provides a better distribution than sdbm. It generally |
| 5115 | works well with text-based inputs though it can perform extremely |
| 5116 | poorly with numeric-only input or when the total server weight is |
| 5117 | a multiple of 33, unless the avalanche modifier is also used. |
| 5118 | |
Willy Tarreau | a0f4271 | 2013-11-14 14:30:35 +0100 | [diff] [blame] | 5119 | wt6 this function was designed for haproxy while testing other |
| 5120 | functions in the past. It is not as smooth as the other ones, but |
| 5121 | is much less sensible to the input data set or to the number of |
| 5122 | servers. It can make sense as an alternative to sdbm+avalanche or |
| 5123 | djb2+avalanche for consistent hashing or when hashing on numeric |
| 5124 | data such as a source IP address or a visitor identifier in a URL |
| 5125 | parameter. |
| 5126 | |
Willy Tarreau | 324f07f | 2015-01-20 19:44:50 +0100 | [diff] [blame] | 5127 | crc32 this is the most common CRC32 implementation as used in Ethernet, |
| 5128 | gzip, PNG, etc. It is slower than the other ones but may provide |
| 5129 | a better distribution or less predictable results especially when |
| 5130 | used on strings. |
| 5131 | |
Bhaskar Maddala | b6c0ac9 | 2013-11-05 11:54:02 -0500 | [diff] [blame] | 5132 | <modifier> indicates an optional method applied after hashing the key : |
| 5133 | |
| 5134 | avalanche This directive indicates that the result from the hash |
| 5135 | function above should not be used in its raw form but that |
| 5136 | a 4-byte full avalanche hash must be applied first. The |
| 5137 | purpose of this step is to mix the resulting bits from the |
| 5138 | previous hash in order to avoid any undesired effect when |
| 5139 | the input contains some limited values or when the number of |
| 5140 | servers is a multiple of one of the hash's components (64 |
| 5141 | for SDBM, 33 for DJB2). Enabling avalanche tends to make the |
| 5142 | result less predictable, but it's also not as smooth as when |
| 5143 | using the original function. Some testing might be needed |
| 5144 | with some workloads. This hash is one of the many proposed |
| 5145 | by Bob Jenkins. |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 5146 | |
Bhaskar | 98634f0 | 2013-10-29 23:30:51 -0400 | [diff] [blame] | 5147 | The default hash type is "map-based" and is recommended for most usages. The |
| 5148 | default function is "sdbm", the selection of a function should be based on |
| 5149 | the range of the values being hashed. |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 5150 | |
Andrew Rodland | 17be45e | 2016-10-25 17:04:12 -0400 | [diff] [blame] | 5151 | See also : "balance", "hash-balance-factor", "server" |
Willy Tarreau | 6b2e11b | 2009-10-01 07:52:15 +0200 | [diff] [blame] | 5152 | |
| 5153 | |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5154 | http-after-response <action> <options...> [ { if | unless } <condition> ] |
| 5155 | Access control for all Layer 7 responses (server, applet/service and internal |
| 5156 | ones). |
| 5157 | |
| 5158 | May be used in sections: defaults | frontend | listen | backend |
| 5159 | no | yes | yes | yes |
| 5160 | |
| 5161 | The http-after-response statement defines a set of rules which apply to layer |
| 5162 | 7 processing. The rules are evaluated in their declaration order when they |
| 5163 | are met in a frontend, listen or backend section. Any rule may optionally be |
| 5164 | followed by an ACL-based condition, in which case it will only be evaluated |
| 5165 | if the condition is true. Since these rules apply on responses, the backend |
| 5166 | rules are applied first, followed by the frontend's rules. |
| 5167 | |
| 5168 | Unlike http-response rules, these ones are applied on all responses, the |
| 5169 | server ones but also to all responses generated by HAProxy. These rules are |
| 5170 | evaluated at the end of the responses analysis, before the data forwarding. |
| 5171 | |
| 5172 | The first keyword is the rule's action. The supported actions are described |
| 5173 | below. |
| 5174 | |
| 5175 | There is no limit to the number of http-after-response statements per |
| 5176 | instance. |
| 5177 | |
Christopher Faulet | d5ac6de | 2020-12-02 08:40:14 +0100 | [diff] [blame] | 5178 | Note: Errors emitted in early stage of the request parsing are handled by the |
| 5179 | multiplexer at a lower level, before any http analysis. Thus no |
| 5180 | http-after-response ruleset is evaluated on these errors. |
| 5181 | |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5182 | Example: |
| 5183 | http-after-response set-header Strict-Transport-Security "max-age=31536000" |
| 5184 | http-after-response set-header Cache-Control "no-store,no-cache,private" |
| 5185 | http-after-response set-header Pragma "no-cache" |
| 5186 | |
| 5187 | http-after-response add-header <name> <fmt> [ { if | unless } <condition> ] |
| 5188 | |
| 5189 | This appends an HTTP header field whose name is specified in <name> and whose |
| 5190 | value is defined by <fmt> which follows the log-format rules (see Custom Log |
| 5191 | Format in section 8.2.4). This may be used to send a cookie to a client for |
| 5192 | example, or to pass some internal information. |
| 5193 | This rule is not final, so it is possible to add other similar rules. |
| 5194 | Note that header addition is performed immediately, so one rule might reuse |
| 5195 | the resulting header from a previous rule. |
| 5196 | |
| 5197 | http-after-response allow [ { if | unless } <condition> ] |
| 5198 | |
| 5199 | This stops the evaluation of the rules and lets the response pass the check. |
| 5200 | No further "http-after-response" rules are evaluated. |
| 5201 | |
Maciej Zdeb | ebdd4c5 | 2020-11-20 13:58:48 +0000 | [diff] [blame] | 5202 | http-after-response del-header <name> [ -m <meth> ] [ { if | unless } <condition> ] |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5203 | |
Maciej Zdeb | ebdd4c5 | 2020-11-20 13:58:48 +0000 | [diff] [blame] | 5204 | This removes all HTTP header fields whose name is specified in <name>. <meth> |
| 5205 | is the matching method, applied on the header name. Supported matching methods |
| 5206 | are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub" |
| 5207 | (substring match) and "reg" (regex match). If not specified, exact matching |
| 5208 | method is used. |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5209 | |
| 5210 | http-after-response replace-header <name> <regex-match> <replace-fmt> |
| 5211 | [ { if | unless } <condition> ] |
| 5212 | |
| 5213 | This works like "http-response replace-header". |
| 5214 | |
| 5215 | Example: |
| 5216 | http-after-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2 |
| 5217 | |
| 5218 | # applied to: |
| 5219 | Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT |
| 5220 | |
| 5221 | # outputs: |
| 5222 | Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT |
| 5223 | |
| 5224 | # assuming the backend IP is 192.168.1.20. |
| 5225 | |
| 5226 | http-after-response replace-value <name> <regex-match> <replace-fmt> |
| 5227 | [ { if | unless } <condition> ] |
| 5228 | |
| 5229 | This works like "http-response replace-value". |
| 5230 | |
| 5231 | Example: |
| 5232 | http-after-response replace-value Cache-control ^public$ private |
| 5233 | |
| 5234 | # applied to: |
| 5235 | Cache-Control: max-age=3600, public |
| 5236 | |
| 5237 | # outputs: |
| 5238 | Cache-Control: max-age=3600, private |
| 5239 | |
| 5240 | http-after-response set-header <name> <fmt> [ { if | unless } <condition> ] |
| 5241 | |
| 5242 | This does the same as "add-header" except that the header name is first |
| 5243 | removed if it existed. This is useful when passing security information to |
| 5244 | the server, where the header must not be manipulated by external users. |
| 5245 | |
| 5246 | http-after-response set-status <status> [reason <str>] |
| 5247 | [ { if | unless } <condition> ] |
| 5248 | |
| 5249 | This replaces the response status code with <status> which must be an integer |
| 5250 | between 100 and 999. Optionally, a custom reason text can be provided defined |
| 5251 | by <str>, or the default reason for the specified code will be used as a |
| 5252 | fallback. |
| 5253 | |
| 5254 | Example: |
| 5255 | # return "431 Request Header Fields Too Large" |
| 5256 | http-response set-status 431 |
| 5257 | # return "503 Slow Down", custom reason |
| 5258 | http-response set-status 503 reason "Slow Down" |
| 5259 | |
| 5260 | http-after-response set-var(<var-name>) <expr> [ { if | unless } <condition> ] |
| 5261 | |
| 5262 | This is used to set the contents of a variable. The variable is declared |
| 5263 | inline. |
| 5264 | |
| 5265 | Arguments: |
| 5266 | <var-name> The name of the variable starts with an indication about its |
| 5267 | scope. The scopes allowed are: |
| 5268 | "proc" : the variable is shared with the whole process |
| 5269 | "sess" : the variable is shared with the whole session |
| 5270 | "txn" : the variable is shared with the transaction |
| 5271 | (request and response) |
| 5272 | "req" : the variable is shared only during request |
| 5273 | processing |
| 5274 | "res" : the variable is shared only during response |
| 5275 | processing |
| 5276 | This prefix is followed by a name. The separator is a '.'. |
| 5277 | The name may only contain characters 'a-z', 'A-Z', '0-9', '.' |
| 5278 | and '_'. |
| 5279 | |
| 5280 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 5281 | followed by some converters. |
| 5282 | |
| 5283 | Example: |
| 5284 | http-after-response set-var(sess.last_redir) res.hdr(location) |
| 5285 | |
| 5286 | http-after-response strict-mode { on | off } |
| 5287 | |
| 5288 | This enables or disables the strict rewriting mode for following rules. It |
| 5289 | does not affect rules declared before it and it is only applicable on rules |
| 5290 | performing a rewrite on the responses. When the strict mode is enabled, any |
| 5291 | rewrite failure triggers an internal error. Otherwise, such errors are |
| 5292 | silently ignored. The purpose of the strict rewriting mode is to make some |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 5293 | rewrites optional while others must be performed to continue the response |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5294 | processing. |
| 5295 | |
| 5296 | By default, the strict rewriting mode is enabled. Its value is also reset |
| 5297 | when a ruleset evaluation ends. So, for instance, if you change the mode on |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 5298 | the backend, the default mode is restored when HAProxy starts the frontend |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5299 | rules evaluation. |
| 5300 | |
| 5301 | http-after-response unset-var(<var-name>) [ { if | unless } <condition> ] |
| 5302 | |
| 5303 | This is used to unset a variable. See "http-after-response set-var" for |
| 5304 | details about <var-name>. |
| 5305 | |
| 5306 | Example: |
| 5307 | http-after-response unset-var(sess.last_redir) |
| 5308 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5309 | |
| 5310 | http-check comment <string> |
| 5311 | Defines a comment for the following the http-check rule, reported in logs if |
| 5312 | it fails. |
| 5313 | May be used in sections : defaults | frontend | listen | backend |
| 5314 | yes | no | yes | yes |
| 5315 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5316 | Arguments : |
| 5317 | <string> is the comment message to add in logs if the following http-check |
| 5318 | rule fails. |
| 5319 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5320 | It only works for connect, send and expect rules. It is useful to make |
| 5321 | user-friendly error reporting. |
| 5322 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 5323 | See also : "option httpchk", "http-check connect", "http-check send" and |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5324 | "http-check expect". |
| 5325 | |
| 5326 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5327 | http-check connect [default] [port <expr>] [addr <ip>] [send-proxy] |
| 5328 | [via-socks4] [ssl] [sni <sni>] [alpn <alpn>] [linger] |
Christopher Faulet | edc6ed9 | 2020-04-23 16:27:59 +0200 | [diff] [blame] | 5329 | [proto <name>] [comment <msg>] |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5330 | Opens a new connection to perform an HTTP health check |
| 5331 | May be used in sections : defaults | frontend | listen | backend |
| 5332 | yes | no | yes | yes |
| 5333 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5334 | Arguments : |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5335 | comment <msg> defines a message to report if the rule evaluation fails. |
| 5336 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5337 | default Use default options of the server line to do the health |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 5338 | checks. The server options are used only if not redefined. |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5339 | |
| 5340 | port <expr> if not set, check port or server port is used. |
| 5341 | It tells HAProxy where to open the connection to. |
| 5342 | <port> must be a valid TCP port source integer, from 1 to |
| 5343 | 65535 or an sample-fetch expression. |
| 5344 | |
| 5345 | addr <ip> defines the IP address to do the health check. |
| 5346 | |
| 5347 | send-proxy send a PROXY protocol string |
| 5348 | |
| 5349 | via-socks4 enables outgoing health checks using upstream socks4 proxy. |
| 5350 | |
| 5351 | ssl opens a ciphered connection |
| 5352 | |
| 5353 | sni <sni> specifies the SNI to use to do health checks over SSL. |
| 5354 | |
| 5355 | alpn <alpn> defines which protocols to advertise with ALPN. The protocol |
| 5356 | list consists in a comma-delimited list of protocol names, |
| 5357 | for instance: "h2,http/1.1". If it is not set, the server ALPN |
| 5358 | is used. |
| 5359 | |
Christopher Faulet | edc6ed9 | 2020-04-23 16:27:59 +0200 | [diff] [blame] | 5360 | proto <name> forces the multiplexer's protocol to use for this connection. |
| 5361 | It must be an HTTP mux protocol and it must be usable on the |
| 5362 | backend side. The list of available protocols is reported in |
| 5363 | haproxy -vv. |
| 5364 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5365 | linger cleanly close the connection instead of using a single RST. |
| 5366 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5367 | Just like tcp-check health checks, it is possible to configure the connection |
| 5368 | to use to perform HTTP health check. This directive should also be used to |
| 5369 | describe a scenario involving several request/response exchanges, possibly on |
| 5370 | different ports or with different servers. |
| 5371 | |
| 5372 | When there are no TCP port configured on the server line neither server port |
| 5373 | directive, then the first step of the http-check sequence must be to specify |
| 5374 | the port with a "http-check connect". |
| 5375 | |
| 5376 | In an http-check ruleset a 'connect' is required, it is also mandatory to start |
| 5377 | the ruleset with a 'connect' rule. Purpose is to ensure admin know what they |
| 5378 | do. |
| 5379 | |
| 5380 | When a connect must start the ruleset, if may still be preceded by set-var, |
| 5381 | unset-var or comment rules. |
| 5382 | |
| 5383 | Examples : |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5384 | # check HTTP and HTTPs services on a server. |
| 5385 | # first open port 80 thanks to server line port directive, then |
| 5386 | # tcp-check opens port 443, ciphered and run a request on it: |
| 5387 | option httpchk |
| 5388 | |
| 5389 | http-check connect |
Christopher Faulet | a5c14ef | 2020-04-29 14:19:13 +0200 | [diff] [blame] | 5390 | http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu |
Christopher Faulet | 8021a5f | 2020-04-24 13:53:12 +0200 | [diff] [blame] | 5391 | http-check expect status 200-399 |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5392 | http-check connect port 443 ssl sni haproxy.1wt.eu |
Christopher Faulet | a5c14ef | 2020-04-29 14:19:13 +0200 | [diff] [blame] | 5393 | http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu |
Christopher Faulet | 8021a5f | 2020-04-24 13:53:12 +0200 | [diff] [blame] | 5394 | http-check expect status 200-399 |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5395 | |
| 5396 | server www 10.0.0.1 check port 80 |
| 5397 | |
| 5398 | See also : "option httpchk", "http-check send", "http-check expect" |
Christopher Faulet | 6d0c3df | 2020-01-22 09:26:35 +0100 | [diff] [blame] | 5399 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5400 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 5401 | http-check disable-on-404 |
| 5402 | Enable a maintenance mode upon HTTP/404 response to health-checks |
| 5403 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5404 | yes | no | yes | yes |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 5405 | Arguments : none |
| 5406 | |
| 5407 | When this option is set, a server which returns an HTTP code 404 will be |
| 5408 | excluded from further load-balancing, but will still receive persistent |
| 5409 | connections. This provides a very convenient method for Web administrators |
| 5410 | to perform a graceful shutdown of their servers. It is also important to note |
| 5411 | that a server which is detected as failed while it was in this mode will not |
| 5412 | generate an alert, just a notice. If the server responds 2xx or 3xx again, it |
| 5413 | will immediately be reinserted into the farm. The status on the stats page |
| 5414 | 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] | 5415 | option only works in conjunction with the "httpchk" option. If this option |
| 5416 | is used with "http-check expect", then it has precedence over it so that 404 |
Christopher Faulet | fa8b89a | 2020-11-20 18:54:13 +0100 | [diff] [blame] | 5417 | responses will still be considered as soft-stop. Note also that a stopped |
| 5418 | server will stay stopped even if it replies 404s. This option is only |
| 5419 | evaluated for running servers. |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5420 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5421 | See also : "option httpchk" and "http-check expect". |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5422 | |
| 5423 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5424 | http-check expect [min-recv <int>] [comment <msg>] |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5425 | [ok-status <st>] [error-status <st>] [tout-status <st>] |
| 5426 | [on-success <fmt>] [on-error <fmt>] [status-code <expr>] |
| 5427 | [!] <match> <pattern> |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 5428 | Make HTTP health checks consider response contents or specific status codes |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5429 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 1ee51a6 | 2011-08-19 20:04:17 +0200 | [diff] [blame] | 5430 | yes | no | yes | yes |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5431 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5432 | Arguments : |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5433 | comment <msg> defines a message to report if the rule evaluation fails. |
| 5434 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5435 | min-recv is optional and can define the minimum amount of data required to |
| 5436 | evaluate the current expect rule. If the number of received bytes |
| 5437 | is under this limit, the check will wait for more data. This |
| 5438 | option can be used to resolve some ambiguous matching rules or to |
| 5439 | avoid executing costly regex matches on content known to be still |
| 5440 | incomplete. If an exact string is used, the minimum between the |
| 5441 | string length and this parameter is used. This parameter is |
| 5442 | ignored if it is set to -1. If the expect rule does not match, |
| 5443 | the check will wait for more data. If set to 0, the evaluation |
| 5444 | result is always conclusive. |
| 5445 | |
| 5446 | ok-status <st> is optional and can be used to set the check status if |
| 5447 | the expect rule is successfully evaluated and if it is |
| 5448 | the last rule in the tcp-check ruleset. "L7OK", "L7OKC", |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 5449 | "L6OK" and "L4OK" are supported : |
| 5450 | - L7OK : check passed on layer 7 |
Christopher Faulet | 83662b5 | 2020-11-20 17:47:47 +0100 | [diff] [blame] | 5451 | - L7OKC : check conditionally passed on layer 7, set |
| 5452 | server to NOLB state. |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 5453 | - L6OK : check passed on layer 6 |
| 5454 | - L4OK : check passed on layer 4 |
| 5455 | By default "L7OK" is used. |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5456 | |
| 5457 | error-status <st> is optional and can be used to set the check status if |
| 5458 | an error occurred during the expect rule evaluation. |
Christopher Faulet | 83662b5 | 2020-11-20 17:47:47 +0100 | [diff] [blame] | 5459 | "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are |
| 5460 | supported : |
| 5461 | - L7OKC : check conditionally passed on layer 7, set |
| 5462 | server to NOLB state. |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 5463 | - L7RSP : layer 7 invalid response - protocol error |
| 5464 | - L7STS : layer 7 response error, for example HTTP 5xx |
| 5465 | - L6RSP : layer 6 invalid response - protocol error |
| 5466 | - L4CON : layer 1-4 connection problem |
| 5467 | By default "L7RSP" is used. |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5468 | |
| 5469 | tout-status <st> is optional and can be used to set the check status if |
| 5470 | a timeout occurred during the expect rule evaluation. |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 5471 | "L7TOUT", "L6TOUT", and "L4TOUT" are supported : |
| 5472 | - L7TOUT : layer 7 (HTTP/SMTP) timeout |
| 5473 | - L6TOUT : layer 6 (SSL) timeout |
| 5474 | - L4TOUT : layer 1-4 timeout |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5475 | By default "L7TOUT" is used. |
| 5476 | |
| 5477 | on-success <fmt> is optional and can be used to customize the |
| 5478 | informational message reported in logs if the expect |
| 5479 | rule is successfully evaluated and if it is the last rule |
| 5480 | in the tcp-check ruleset. <fmt> is a log-format string. |
| 5481 | |
| 5482 | on-error <fmt> is optional and can be used to customize the |
| 5483 | informational message reported in logs if an error |
| 5484 | occurred during the expect rule evaluation. <fmt> is a |
| 5485 | log-format string. |
| 5486 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5487 | <match> is a keyword indicating how to look for a specific pattern in the |
Christopher Faulet | b559426 | 2020-05-05 20:23:13 +0200 | [diff] [blame] | 5488 | response. The keyword may be one of "status", "rstatus", "hdr", |
| 5489 | "fhdr", "string", or "rstring". The keyword may be preceded by an |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5490 | exclamation mark ("!") to negate the match. Spaces are allowed |
| 5491 | between the exclamation mark and the keyword. See below for more |
| 5492 | details on the supported keywords. |
| 5493 | |
Christopher Faulet | 3970819 | 2020-05-05 10:47:36 +0200 | [diff] [blame] | 5494 | <pattern> is the pattern to look for. It may be a string, a regular |
| 5495 | expression or a more complex pattern with several arguments. If |
| 5496 | the string pattern contains spaces, they must be escaped with the |
| 5497 | usual backslash ('\'). |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5498 | |
| 5499 | By default, "option httpchk" considers that response statuses 2xx and 3xx |
| 5500 | are valid, and that others are invalid. When "http-check expect" is used, |
| 5501 | it defines what is considered valid or invalid. Only one "http-check" |
| 5502 | statement is supported in a backend. If a server fails to respond or times |
| 5503 | out, the check obviously fails. The available matches are : |
| 5504 | |
Christopher Faulet | 8021a5f | 2020-04-24 13:53:12 +0200 | [diff] [blame] | 5505 | status <codes> : test the status codes found parsing <codes> string. it |
| 5506 | must be a comma-separated list of status codes or range |
| 5507 | codes. A health check response will be considered as |
| 5508 | valid if the response's status code matches any status |
| 5509 | code or is inside any range of the list. If the "status" |
| 5510 | keyword is prefixed with "!", then the response will be |
| 5511 | considered invalid if the status code matches. |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5512 | |
| 5513 | rstatus <regex> : test a regular expression for the HTTP status code. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 5514 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5515 | response's status code matches the expression. If the |
| 5516 | "rstatus" keyword is prefixed with "!", then the response |
| 5517 | will be considered invalid if the status code matches. |
| 5518 | This is mostly used to check for multiple codes. |
| 5519 | |
Christopher Faulet | b559426 | 2020-05-05 20:23:13 +0200 | [diff] [blame] | 5520 | hdr { name | name-lf } [ -m <meth> ] <name> |
| 5521 | [ { value | value-lf } [ -m <meth> ] <value> : |
Christopher Faulet | 3970819 | 2020-05-05 10:47:36 +0200 | [diff] [blame] | 5522 | test the specified header pattern on the HTTP response |
| 5523 | headers. The name pattern is mandatory but the value |
| 5524 | pattern is optional. If not specified, only the header |
| 5525 | presence is verified. <meth> is the matching method, |
| 5526 | applied on the header name or the header value. Supported |
| 5527 | matching methods are "str" (exact match), "beg" (prefix |
| 5528 | match), "end" (suffix match), "sub" (substring match) or |
| 5529 | "reg" (regex match). If not specified, exact matching |
Christopher Faulet | b559426 | 2020-05-05 20:23:13 +0200 | [diff] [blame] | 5530 | method is used. If the "name-lf" parameter is used, |
| 5531 | <name> is evaluated as a log-format string. If "value-lf" |
| 5532 | parameter is used, <value> is evaluated as a log-format |
| 5533 | string. These parameters cannot be used with the regex |
| 5534 | matching method. Finally, the header value is considered |
| 5535 | as comma-separated list. Note that matchings are case |
| 5536 | insensitive on the header names. |
| 5537 | |
| 5538 | fhdr { name | name-lf } [ -m <meth> ] <name> |
| 5539 | [ { value | value-lf } [ -m <meth> ] <value> : |
| 5540 | test the specified full header pattern on the HTTP |
| 5541 | response headers. It does exactly the same than "hdr" |
| 5542 | keyword, except the full header value is tested, commas |
| 5543 | are not considered as delimiters. |
Christopher Faulet | 3970819 | 2020-05-05 10:47:36 +0200 | [diff] [blame] | 5544 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5545 | string <string> : test the exact string match in the HTTP response body. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 5546 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5547 | response's body contains this exact string. If the |
| 5548 | "string" keyword is prefixed with "!", then the response |
| 5549 | will be considered invalid if the body contains this |
| 5550 | string. This can be used to look for a mandatory word at |
| 5551 | the end of a dynamic page, or to detect a failure when a |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 5552 | specific error appears on the check page (e.g. a stack |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5553 | trace). |
| 5554 | |
| 5555 | rstring <regex> : test a regular expression on the HTTP response body. |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 5556 | A health check response will be considered valid if the |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5557 | response's body matches this expression. If the "rstring" |
| 5558 | keyword is prefixed with "!", then the response will be |
| 5559 | considered invalid if the body matches the expression. |
| 5560 | This can be used to look for a mandatory word at the end |
| 5561 | of a dynamic page, or to detect a failure when a specific |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 5562 | error appears on the check page (e.g. a stack trace). |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5563 | |
Christopher Faulet | aaab083 | 2020-05-05 15:54:22 +0200 | [diff] [blame] | 5564 | string-lf <fmt> : test a log-format string match in the HTTP response body. |
| 5565 | A health check response will be considered valid if the |
| 5566 | response's body contains the string resulting of the |
| 5567 | evaluation of <fmt>, which follows the log-format rules. |
| 5568 | If prefixed with "!", then the response will be |
| 5569 | considered invalid if the body contains the string. |
| 5570 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5571 | It is important to note that the responses will be limited to a certain size |
Christopher Faulet | bb9fb8b | 2020-11-25 17:20:57 +0100 | [diff] [blame] | 5572 | defined by the global "tune.bufsize" option, which defaults to 16384 bytes. |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5573 | Thus, too large responses may not contain the mandatory pattern when using |
| 5574 | "string" or "rstring". If a large response is absolutely required, it is |
| 5575 | possible to change the default max size by setting the global variable. |
| 5576 | However, it is worth keeping in mind that parsing very large responses can |
| 5577 | waste some CPU cycles, especially when regular expressions are used, and that |
| 5578 | it is always better to focus the checks on smaller resources. |
| 5579 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5580 | In an http-check ruleset, the last expect rule may be implicit. If no expect |
| 5581 | rule is specified after the last "http-check send", an implicit expect rule |
| 5582 | is defined to match on 2xx or 3xx status codes. It means this rule is also |
| 5583 | defined if there is no "http-check" rule at all, when only "option httpchk" |
| 5584 | is set. |
Cyril Bonté | 32602d2 | 2015-01-30 00:07:07 +0100 | [diff] [blame] | 5585 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5586 | Last, if "http-check expect" is combined with "http-check disable-on-404", |
| 5587 | then this last one has precedence when the server responds with 404. |
| 5588 | |
| 5589 | Examples : |
| 5590 | # only accept status 200 as valid |
Christopher Faulet | 8021a5f | 2020-04-24 13:53:12 +0200 | [diff] [blame] | 5591 | http-check expect status 200,201,300-310 |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5592 | |
Christopher Faulet | 3970819 | 2020-05-05 10:47:36 +0200 | [diff] [blame] | 5593 | # be sure a sessid coookie is set |
| 5594 | http-check expect header name "set-cookie" value -m beg "sessid=" |
| 5595 | |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5596 | # consider SQL errors as errors |
Willy Tarreau | 8f2a1e7 | 2011-01-06 16:36:10 +0100 | [diff] [blame] | 5597 | http-check expect ! string SQL\ Error |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5598 | |
| 5599 | # consider status 5xx only as errors |
Willy Tarreau | 8f2a1e7 | 2011-01-06 16:36:10 +0100 | [diff] [blame] | 5600 | http-check expect ! rstatus ^5 |
Willy Tarreau | bd74154 | 2010-03-16 18:46:54 +0100 | [diff] [blame] | 5601 | |
| 5602 | # check that we have a correct hexadecimal tag before /html |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 5603 | http-check expect rstring <!--tag:[0-9a-f]*--></html> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 5604 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5605 | See also : "option httpchk", "http-check connect", "http-check disable-on-404" |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5606 | and "http-check send". |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 5607 | |
| 5608 | |
Christopher Faulet | 7c95f5f | 2020-05-06 15:06:34 +0200 | [diff] [blame] | 5609 | http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>] |
Christopher Faulet | 574e7bd | 2020-05-06 15:38:58 +0200 | [diff] [blame] | 5610 | [hdr <name> <fmt>]* [{ body <string> | body-lf <fmt> }] |
| 5611 | [comment <msg>] |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 5612 | Add a possible list of headers and/or a body to the request sent during HTTP |
| 5613 | health checks. |
| 5614 | May be used in sections : defaults | frontend | listen | backend |
| 5615 | yes | no | yes | yes |
| 5616 | Arguments : |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 5617 | comment <msg> defines a message to report if the rule evaluation fails. |
| 5618 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5619 | meth <method> is the optional HTTP method used with the requests. When not |
| 5620 | set, the "OPTIONS" method is used, as it generally requires |
| 5621 | low server processing and is easy to filter out from the |
| 5622 | logs. Any method may be used, though it is not recommended |
| 5623 | to invent non-standard ones. |
| 5624 | |
Christopher Faulet | 7c95f5f | 2020-05-06 15:06:34 +0200 | [diff] [blame] | 5625 | uri <uri> is optional and set the URI referenced in the HTTP requests |
| 5626 | to the string <uri>. It defaults to "/" which is accessible |
| 5627 | by default on almost any server, but may be changed to any |
| 5628 | other URI. Query strings are permitted. |
| 5629 | |
| 5630 | uri-lf <fmt> is optional and set the URI referenced in the HTTP requests |
| 5631 | using the log-format string <fmt>. It defaults to "/" which |
| 5632 | is accessible by default on almost any server, but may be |
| 5633 | changed to any other URI. Query strings are permitted. |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 5634 | |
Christopher Faulet | 907701b | 2020-04-28 09:37:00 +0200 | [diff] [blame] | 5635 | ver <version> is the optional HTTP version string. It defaults to |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5636 | "HTTP/1.0" but some servers might behave incorrectly in HTTP |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 5637 | 1.0, so turning it to HTTP/1.1 may sometimes help. Note that |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5638 | the Host field is mandatory in HTTP/1.1, use "hdr" argument |
| 5639 | to add it. |
| 5640 | |
| 5641 | hdr <name> <fmt> adds the HTTP header field whose name is specified in |
| 5642 | <name> and whose value is defined by <fmt>, which follows |
| 5643 | to the log-format rules. |
| 5644 | |
| 5645 | body <string> add the body defined by <string> to the request sent during |
| 5646 | HTTP health checks. If defined, the "Content-Length" header |
| 5647 | is thus automatically added to the request. |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 5648 | |
Christopher Faulet | 574e7bd | 2020-05-06 15:38:58 +0200 | [diff] [blame] | 5649 | body-lf <fmt> add the body defined by the log-format string <fmt> to the |
| 5650 | request sent during HTTP health checks. If defined, the |
| 5651 | "Content-Length" header is thus automatically added to the |
| 5652 | request. |
| 5653 | |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 5654 | In addition to the request line defined by the "option httpchk" directive, |
| 5655 | this one is the valid way to add some headers and optionally a body to the |
| 5656 | request sent during HTTP health checks. If a body is defined, the associate |
Christopher Faulet | 9df910c | 2020-04-29 14:20:47 +0200 | [diff] [blame] | 5657 | "Content-Length" header is automatically added. Thus, this header or |
| 5658 | "Transfer-encoding" header should not be present in the request provided by |
| 5659 | "http-check send". If so, it will be ignored. The old trick consisting to add |
| 5660 | headers after the version string on the "option httpchk" line is now |
Amaury Denoyelle | 6d975f0 | 2020-12-22 14:08:52 +0100 | [diff] [blame] | 5661 | deprecated. |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 5662 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5663 | Also "http-check send" doesn't support HTTP keep-alive. Keep in mind that it |
Amaury Denoyelle | 6d975f0 | 2020-12-22 14:08:52 +0100 | [diff] [blame] | 5664 | will automatically append a "Connection: close" header, unless a Connection |
| 5665 | header has already already been configured via a hdr entry. |
Christopher Faulet | 9df910c | 2020-04-29 14:20:47 +0200 | [diff] [blame] | 5666 | |
| 5667 | Note that the Host header and the request authority, when both defined, are |
| 5668 | automatically synchronized. It means when the HTTP request is sent, when a |
| 5669 | Host is inserted in the request, the request authority is accordingly |
| 5670 | updated. Thus, don't be surprised if the Host header value overwrites the |
| 5671 | configured request authority. |
| 5672 | |
| 5673 | Note also for now, no Host header is automatically added in HTTP/1.1 or above |
| 5674 | requests. You should add it explicitly. |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5675 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5676 | See also : "option httpchk", "http-check send-state" and "http-check expect". |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 5677 | |
| 5678 | |
Willy Tarreau | ef78104 | 2010-01-27 11:53:01 +0100 | [diff] [blame] | 5679 | http-check send-state |
| 5680 | Enable emission of a state header with HTTP health checks |
| 5681 | May be used in sections : defaults | frontend | listen | backend |
| 5682 | yes | no | yes | yes |
| 5683 | Arguments : none |
| 5684 | |
| 5685 | When this option is set, haproxy will systematically send a special header |
| 5686 | "X-Haproxy-Server-State" with a list of parameters indicating to each server |
| 5687 | how they are seen by haproxy. This can be used for instance when a server is |
| 5688 | manipulated without access to haproxy and the operator needs to know whether |
| 5689 | haproxy still sees it up or not, or if the server is the last one in a farm. |
| 5690 | |
| 5691 | The header is composed of fields delimited by semi-colons, the first of which |
| 5692 | is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid |
| 5693 | checks on the total number before transition, just as appears in the stats |
| 5694 | interface. Next headers are in the form "<variable>=<value>", indicating in |
| 5695 | no specific order some values available in the stats interface : |
Joseph Lynch | 514061c | 2015-01-15 17:52:59 -0800 | [diff] [blame] | 5696 | - a variable "address", containing the address of the backend server. |
| 5697 | This corresponds to the <address> field in the server declaration. For |
| 5698 | unix domain sockets, it will read "unix". |
| 5699 | |
| 5700 | - a variable "port", containing the port of the backend server. This |
| 5701 | corresponds to the <port> field in the server declaration. For unix |
| 5702 | domain sockets, it will read "unix". |
| 5703 | |
Willy Tarreau | ef78104 | 2010-01-27 11:53:01 +0100 | [diff] [blame] | 5704 | - a variable "name", containing the name of the backend followed by a slash |
| 5705 | ("/") then the name of the server. This can be used when a server is |
| 5706 | checked in multiple backends. |
| 5707 | |
| 5708 | - a variable "node" containing the name of the haproxy node, as set in the |
| 5709 | global "node" variable, otherwise the system's hostname if unspecified. |
| 5710 | |
| 5711 | - a variable "weight" indicating the weight of the server, a slash ("/") |
| 5712 | and the total weight of the farm (just counting usable servers). This |
| 5713 | helps to know if other servers are available to handle the load when this |
| 5714 | one fails. |
| 5715 | |
| 5716 | - a variable "scur" indicating the current number of concurrent connections |
| 5717 | on the server, followed by a slash ("/") then the total number of |
| 5718 | connections on all servers of the same backend. |
| 5719 | |
| 5720 | - a variable "qcur" indicating the current number of requests in the |
| 5721 | server's queue. |
| 5722 | |
| 5723 | Example of a header received by the application server : |
| 5724 | >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \ |
| 5725 | scur=13/22; qcur=0 |
| 5726 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5727 | See also : "option httpchk", "http-check disable-on-404" and |
| 5728 | "http-check send". |
Willy Tarreau | ef78104 | 2010-01-27 11:53:01 +0100 | [diff] [blame] | 5729 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5730 | |
| 5731 | http-check set-var(<var-name>) <expr> |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5732 | This operation sets the content of a variable. The variable is declared inline. |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5733 | May be used in sections: defaults | frontend | listen | backend |
| 5734 | yes | no | yes | yes |
| 5735 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5736 | Arguments : |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5737 | <var-name> The name of the variable starts with an indication about its |
| 5738 | scope. The scopes allowed for http-check are: |
| 5739 | "proc" : the variable is shared with the whole process. |
| 5740 | "sess" : the variable is shared with the tcp-check session. |
| 5741 | "check": the variable is declared for the lifetime of the tcp-check. |
| 5742 | This prefix is followed by a name. The separator is a '.'. |
| 5743 | The name may only contain characters 'a-z', 'A-Z', '0-9', '.', |
| 5744 | and '-'. |
| 5745 | |
| 5746 | <expr> Is a sample-fetch expression potentially followed by converters. |
| 5747 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5748 | Examples : |
| 5749 | http-check set-var(check.port) int(1234) |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5750 | |
| 5751 | |
| 5752 | http-check unset-var(<var-name>) |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5753 | Free a reference to a variable within its scope. |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5754 | May be used in sections: defaults | frontend | listen | backend |
| 5755 | yes | no | yes | yes |
| 5756 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5757 | Arguments : |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5758 | <var-name> The name of the variable starts with an indication about its |
| 5759 | scope. The scopes allowed for http-check are: |
| 5760 | "proc" : the variable is shared with the whole process. |
| 5761 | "sess" : the variable is shared with the tcp-check session. |
| 5762 | "check": the variable is declared for the lifetime of the tcp-check. |
| 5763 | This prefix is followed by a name. The separator is a '.'. |
| 5764 | The name may only contain characters 'a-z', 'A-Z', '0-9', '.', |
| 5765 | and '-'. |
| 5766 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 5767 | Examples : |
| 5768 | http-check unset-var(check.port) |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 5769 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5770 | |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 5771 | http-error status <code> [content-type <type>] |
| 5772 | [ { default-errorfiles | errorfile <file> | errorfiles <name> | |
| 5773 | file <file> | lf-file <file> | string <str> | lf-string <fmt> } ] |
| 5774 | [ hdr <name> <fmt> ]* |
| 5775 | Defines a custom error message to use instead of errors generated by HAProxy. |
| 5776 | May be used in sections : defaults | frontend | listen | backend |
| 5777 | yes | yes | yes | yes |
| 5778 | Arguments : |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 5779 | status <code> is the HTTP status code. It must be specified. |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 5780 | Currently, HAProxy is capable of generating codes |
Anthonin Bonnefoy | 85048f8 | 2020-06-22 09:17:01 +0200 | [diff] [blame] | 5781 | 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 425, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 5782 | 429, 500, 501, 502, 503, and 504. |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 5783 | |
| 5784 | content-type <type> is the response content type, for instance |
| 5785 | "text/plain". This parameter is ignored and should be |
| 5786 | omitted when an errorfile is configured or when the |
| 5787 | payload is empty. Otherwise, it must be defined. |
| 5788 | |
| 5789 | default-errorfiles Reset the previously defined error message for current |
| 5790 | proxy for the status <code>. If used on a backend, the |
| 5791 | frontend error message is used, if defined. If used on |
| 5792 | a frontend, the default error message is used. |
| 5793 | |
| 5794 | errorfile <file> designates a file containing the full HTTP response. |
| 5795 | It is recommended to follow the common practice of |
| 5796 | appending ".http" to the filename so that people do |
| 5797 | not confuse the response with HTML error pages, and to |
| 5798 | use absolute paths, since files are read before any |
| 5799 | chroot is performed. |
| 5800 | |
| 5801 | errorfiles <name> designates the http-errors section to use to import |
| 5802 | the error message with the status code <code>. If no |
| 5803 | such message is found, the proxy's error messages are |
| 5804 | considered. |
| 5805 | |
| 5806 | file <file> specifies the file to use as response payload. If the |
| 5807 | file is not empty, its content-type must be set as |
| 5808 | argument to "content-type", otherwise, any |
| 5809 | "content-type" argument is ignored. <file> is |
| 5810 | considered as a raw string. |
| 5811 | |
| 5812 | string <str> specifies the raw string to use as response payload. |
| 5813 | The content-type must always be set as argument to |
| 5814 | "content-type". |
| 5815 | |
| 5816 | lf-file <file> specifies the file to use as response payload. If the |
| 5817 | file is not empty, its content-type must be set as |
| 5818 | argument to "content-type", otherwise, any |
| 5819 | "content-type" argument is ignored. <file> is |
| 5820 | evaluated as a log-format string. |
| 5821 | |
| 5822 | lf-string <str> specifies the log-format string to use as response |
| 5823 | payload. The content-type must always be set as |
| 5824 | argument to "content-type". |
| 5825 | |
| 5826 | hdr <name> <fmt> adds to the response the HTTP header field whose name |
| 5827 | is specified in <name> and whose value is defined by |
| 5828 | <fmt>, which follows to the log-format rules. |
| 5829 | This parameter is ignored if an errorfile is used. |
| 5830 | |
| 5831 | This directive may be used instead of "errorfile", to define a custom error |
| 5832 | message. As "errorfile" directive, it is used for errors detected and |
| 5833 | returned by HAProxy. If an errorfile is defined, it is parsed when HAProxy |
| 5834 | starts and must be valid according to the HTTP standards. The generated |
| 5835 | response must not exceed the configured buffer size (BUFFSIZE), otherwise an |
| 5836 | internal error will be returned. Finally, if you consider to use some |
| 5837 | http-after-response rules to rewrite these errors, the reserved buffer space |
| 5838 | should be available (see "tune.maxrewrite"). |
| 5839 | |
| 5840 | The files are read at the same time as the configuration and kept in memory. |
| 5841 | For this reason, the errors continue to be returned even when the process is |
| 5842 | chrooted, and no file change is considered while the process is running. |
| 5843 | |
Christopher Faulet | d5ac6de | 2020-12-02 08:40:14 +0100 | [diff] [blame] | 5844 | Note: 400/408/500 errors emitted in early stage of the request parsing are |
| 5845 | handled by the multiplexer at a lower level. No custom formatting is |
| 5846 | supported at this level. Thus only static error messages, defined with |
| 5847 | "errorfile" directive, are supported. However, this limitation only |
| 5848 | exists during the request headers parsing or between two transactions. |
| 5849 | |
Christopher Faulet | 3b967c1 | 2020-05-15 15:47:44 +0200 | [diff] [blame] | 5850 | See also : "errorfile", "errorfiles", "errorloc", "errorloc302", |
| 5851 | "errorloc303" and section 3.8 about http-errors. |
| 5852 | |
| 5853 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5854 | http-request <action> [options...] [ { if | unless } <condition> ] |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 5855 | Access control for Layer 7 requests |
| 5856 | |
| 5857 | May be used in sections: defaults | frontend | listen | backend |
| 5858 | no | yes | yes | yes |
| 5859 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 5860 | The http-request statement defines a set of rules which apply to layer 7 |
| 5861 | processing. The rules are evaluated in their declaration order when they are |
| 5862 | met in a frontend, listen or backend section. Any rule may optionally be |
| 5863 | followed by an ACL-based condition, in which case it will only be evaluated |
| 5864 | if the condition is true. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 5865 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5866 | The first keyword is the rule's action. The supported actions are described |
| 5867 | below. |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 5868 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5869 | There is no limit to the number of http-request statements per instance. |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 5870 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5871 | Example: |
| 5872 | acl nagios src 192.168.129.3 |
| 5873 | acl local_net src 192.168.0.0/16 |
| 5874 | acl auth_ok http_auth(L1) |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 5875 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5876 | http-request allow if nagios |
| 5877 | http-request allow if local_net auth_ok |
| 5878 | http-request auth realm Gimme if local_net auth_ok |
| 5879 | http-request deny |
Willy Tarreau | 81499eb | 2012-12-27 12:19:02 +0100 | [diff] [blame] | 5880 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5881 | Example: |
| 5882 | acl key req.hdr(X-Add-Acl-Key) -m found |
| 5883 | acl add path /addacl |
| 5884 | acl del path /delacl |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 5885 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5886 | acl myhost hdr(Host) -f myhost.lst |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 5887 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5888 | http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add |
| 5889 | http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del |
Thierry FOURNIER | dad3d1d | 2014-04-22 18:07:25 +0200 | [diff] [blame] | 5890 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5891 | Example: |
| 5892 | acl value req.hdr(X-Value) -m found |
| 5893 | acl setmap path /setmap |
| 5894 | acl delmap path /delmap |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5895 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5896 | use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5897 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5898 | http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value |
| 5899 | http-request del-map(map.lst) %[src] if delmap |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5900 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5901 | See also : "stats http-request", section 3.4 about userlists and section 7 |
| 5902 | about ACL usage. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5903 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5904 | http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5905 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5906 | This is used to add a new entry into an ACL. The ACL must be loaded from a |
| 5907 | file (even a dummy empty file). The file name of the ACL to be updated is |
| 5908 | passed between parentheses. It takes one argument: <key fmt>, which follows |
| 5909 | log-format rules, to collect content of the new entry. It performs a lookup |
| 5910 | in the ACL before insertion, to avoid duplicated (or more) values. This |
| 5911 | lookup is done by a linear search and can be expensive with large lists! |
| 5912 | It is the equivalent of the "add acl" command from the stats socket, but can |
| 5913 | be triggered by an HTTP request. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5914 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5915 | http-request add-header <name> <fmt> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5916 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5917 | This appends an HTTP header field whose name is specified in <name> and |
| 5918 | whose value is defined by <fmt> which follows the log-format rules (see |
| 5919 | Custom Log Format in section 8.2.4). This is particularly useful to pass |
| 5920 | connection-specific information to the server (e.g. the client's SSL |
| 5921 | certificate), or to combine several headers into one. This rule is not |
| 5922 | final, so it is possible to add other similar rules. Note that header |
| 5923 | addition is performed immediately, so one rule might reuse the resulting |
| 5924 | header from a previous rule. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5925 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5926 | http-request allow [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5927 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5928 | This stops the evaluation of the rules and lets the request pass the check. |
| 5929 | No further "http-request" rules are evaluated. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5930 | |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5931 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5932 | http-request auth [realm <realm>] [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5933 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5934 | This stops the evaluation of the rules and immediately responds with an |
| 5935 | HTTP 401 or 407 error code to invite the user to present a valid user name |
| 5936 | and password. No further "http-request" rules are evaluated. An optional |
| 5937 | "realm" parameter is supported, it sets the authentication realm that is |
| 5938 | returned with the response (typically the application's name). |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5939 | |
Christopher Faulet | 612f2ea | 2020-05-27 09:57:28 +0200 | [diff] [blame] | 5940 | The corresponding proxy's error message is used. It may be customized using |
| 5941 | an "errorfile" or an "http-error" directive. For 401 responses, all |
| 5942 | occurrences of the WWW-Authenticate header are removed and replaced by a new |
| 5943 | one with a basic authentication challenge for realm "<realm>". For 407 |
| 5944 | responses, the same is done on the Proxy-Authenticate header. If the error |
| 5945 | message must not be altered, consider to use "http-request return" rule |
| 5946 | instead. |
| 5947 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5948 | Example: |
| 5949 | acl auth_ok http_auth_group(L1) G1 |
| 5950 | http-request auth unless auth_ok |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5951 | |
Jarno Huuskonen | 251a6b7 | 2019-01-04 14:05:02 +0200 | [diff] [blame] | 5952 | http-request cache-use <name> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 5953 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 5954 | See section 6.2 about cache setup. |
Willy Tarreau | a0dc23f | 2015-01-22 20:46:11 +0100 | [diff] [blame] | 5955 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5956 | http-request capture <sample> [ len <length> | id <id> ] |
| 5957 | [ { if | unless } <condition> ] |
Willy Tarreau | a0dc23f | 2015-01-22 20:46:11 +0100 | [diff] [blame] | 5958 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5959 | This captures sample expression <sample> from the request buffer, and |
| 5960 | converts it to a string of at most <len> characters. The resulting string is |
| 5961 | stored into the next request "capture" slot, so it will possibly appear next |
| 5962 | to some captured HTTP headers. It will then automatically appear in the logs, |
| 5963 | and it will be possible to extract it using sample fetch rules to feed it |
| 5964 | into headers or anything. The length should be limited given that this size |
| 5965 | will be allocated for each capture during the whole session life. |
| 5966 | Please check section 7.3 (Fetching samples) and "capture request header" for |
| 5967 | more information. |
Willy Tarreau | a0dc23f | 2015-01-22 20:46:11 +0100 | [diff] [blame] | 5968 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5969 | If the keyword "id" is used instead of "len", the action tries to store the |
| 5970 | captured string in a previously declared capture slot. This is useful to run |
| 5971 | captures in backends. The slot id can be declared by a previous directive |
Baptiste Assmann | 19a69b3 | 2020-01-16 14:34:22 +0100 | [diff] [blame] | 5972 | "http-request capture" or with the "declare capture" keyword. |
| 5973 | |
| 5974 | When using this action in a backend, double check that the relevant |
| 5975 | frontend(s) have the required capture slots otherwise, this rule will be |
| 5976 | ignored at run time. This can't be detected at configuration parsing time |
| 5977 | due to HAProxy's ability to dynamically resolve backend name at runtime. |
Willy Tarreau | a0dc23f | 2015-01-22 20:46:11 +0100 | [diff] [blame] | 5978 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5979 | http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ] |
Willy Tarreau | a0dc23f | 2015-01-22 20:46:11 +0100 | [diff] [blame] | 5980 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5981 | This is used to delete an entry from an ACL. The ACL must be loaded from a |
| 5982 | file (even a dummy empty file). The file name of the ACL to be updated is |
| 5983 | passed between parentheses. It takes one argument: <key fmt>, which follows |
| 5984 | log-format rules, to collect content of the entry to delete. |
| 5985 | It is the equivalent of the "del acl" command from the stats socket, but can |
| 5986 | be triggered by an HTTP request. |
Willy Tarreau | a0dc23f | 2015-01-22 20:46:11 +0100 | [diff] [blame] | 5987 | |
Maciej Zdeb | ebdd4c5 | 2020-11-20 13:58:48 +0000 | [diff] [blame] | 5988 | http-request del-header <name> [ -m <meth> ] [ { if | unless } <condition> ] |
Willy Tarreau | f4c43c1 | 2013-06-11 17:01:13 +0200 | [diff] [blame] | 5989 | |
Maciej Zdeb | ebdd4c5 | 2020-11-20 13:58:48 +0000 | [diff] [blame] | 5990 | This removes all HTTP header fields whose name is specified in <name>. <meth> |
| 5991 | is the matching method, applied on the header name. Supported matching methods |
| 5992 | are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub" |
| 5993 | (substring match) and "reg" (regex match). If not specified, exact matching |
| 5994 | method is used. |
Willy Tarreau | 9a355ec | 2013-06-11 17:45:46 +0200 | [diff] [blame] | 5995 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5996 | http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ] |
Willy Tarreau | 42cf39e | 2013-06-11 18:51:32 +0200 | [diff] [blame] | 5997 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 5998 | This is used to delete an entry from a MAP. The MAP must be loaded from a |
| 5999 | file (even a dummy empty file). The file name of the MAP to be updated is |
| 6000 | passed between parentheses. It takes one argument: <key fmt>, which follows |
| 6001 | log-format rules, to collect content of the entry to delete. |
| 6002 | It takes one argument: "file name" It is the equivalent of the "del map" |
| 6003 | command from the stats socket, but can be triggered by an HTTP request. |
Willy Tarreau | 51347ed | 2013-06-11 19:34:13 +0200 | [diff] [blame] | 6004 | |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6005 | http-request deny [deny_status <status>] [ { if | unless } <condition> ] |
| 6006 | http-request deny [ { status | deny_status } <code>] [content-type <type>] |
| 6007 | [ { default-errorfiles | errorfile <file> | errorfiles <name> | |
| 6008 | file <file> | lf-file <file> | string <str> | lf-string <fmt> } ] |
| 6009 | [ hdr <name> <fmt> ]* |
| 6010 | [ { if | unless } <condition> ] |
Patrick Hemmer | 268a707 | 2018-05-11 12:52:31 -0400 | [diff] [blame] | 6011 | |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6012 | This stops the evaluation of the rules and immediately rejects the request. |
| 6013 | By default an HTTP 403 error is returned. But the response may be customized |
| 6014 | using same syntax than "http-request return" rules. Thus, see "http-request |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 6015 | return" for details. For compatibility purpose, when no argument is defined, |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6016 | or only "deny_status", the argument "default-errorfiles" is implied. It means |
| 6017 | "http-request deny [deny_status <status>]" is an alias of |
| 6018 | "http-request deny [status <status>] default-errorfiles". |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6019 | No further "http-request" rules are evaluated. |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6020 | See also "http-request return". |
Patrick Hemmer | 268a707 | 2018-05-11 12:52:31 -0400 | [diff] [blame] | 6021 | |
Olivier Houchard | 602bf7d | 2019-05-10 13:59:15 +0200 | [diff] [blame] | 6022 | http-request disable-l7-retry [ { if | unless } <condition> ] |
| 6023 | This disables any attempt to retry the request if it fails for any other |
| 6024 | reason than a connection failure. This can be useful for example to make |
| 6025 | sure POST requests aren't retried on failure. |
| 6026 | |
Baptiste Assmann | 333939c | 2019-01-21 08:34:50 +0100 | [diff] [blame] | 6027 | http-request do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr> : |
| 6028 | |
| 6029 | This action performs a DNS resolution of the output of <expr> and stores |
| 6030 | the result in the variable <var>. It uses the DNS resolvers section |
| 6031 | pointed by <resolvers>. |
| 6032 | It is possible to choose a resolution preference using the optional |
| 6033 | arguments 'ipv4' or 'ipv6'. |
| 6034 | When performing the DNS resolution, the client side connection is on |
| 6035 | pause waiting till the end of the resolution. |
| 6036 | If an IP address can be found, it is stored into <var>. If any kind of |
| 6037 | error occurs, then <var> is not set. |
| 6038 | One can use this action to discover a server IP address at run time and |
| 6039 | based on information found in the request (IE a Host header). |
| 6040 | If this action is used to find the server's IP address (using the |
| 6041 | "set-dst" action), then the server IP address in the backend must be set |
| 6042 | to 0.0.0.0. |
| 6043 | |
| 6044 | Example: |
| 6045 | resolvers mydns |
| 6046 | nameserver local 127.0.0.53:53 |
| 6047 | nameserver google 8.8.8.8:53 |
| 6048 | timeout retry 1s |
| 6049 | hold valid 10s |
| 6050 | hold nx 3s |
| 6051 | hold other 3s |
| 6052 | hold obsolete 0s |
| 6053 | accepted_payload_size 8192 |
| 6054 | |
| 6055 | frontend fe |
| 6056 | bind 10.42.0.1:80 |
| 6057 | http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),lower |
| 6058 | http-request capture var(txn.myip) len 40 |
| 6059 | |
| 6060 | # return 503 when the variable is not set, |
| 6061 | # which mean DNS resolution error |
| 6062 | use_backend b_503 unless { var(txn.myip) -m found } |
| 6063 | |
| 6064 | default_backend be |
| 6065 | |
| 6066 | backend b_503 |
| 6067 | # dummy backend used to return 503. |
| 6068 | # one can use the errorfile directive to send a nice |
| 6069 | # 503 error page to end users |
| 6070 | |
| 6071 | backend be |
| 6072 | # rule to prevent HAProxy from reconnecting to services |
| 6073 | # on the local network (forged DNS name used to scan the network) |
| 6074 | http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 } |
| 6075 | http-request set-dst var(txn.myip) |
| 6076 | server clear 0.0.0.0:0 |
| 6077 | |
| 6078 | NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't |
| 6079 | be used to scan the network or worst won't loop over itself... |
| 6080 | |
Frédéric Lécaille | 06f5b64 | 2018-11-12 11:01:10 +0100 | [diff] [blame] | 6081 | http-request early-hint <name> <fmt> [ { if | unless } <condition> ] |
| 6082 | |
| 6083 | This is used to build an HTTP 103 Early Hints response prior to any other one. |
| 6084 | This appends an HTTP header field to this response whose name is specified in |
| 6085 | <name> and whose value is defined by <fmt> which follows the log-format rules |
| 6086 | (see Custom Log Format in section 8.2.4). This is particularly useful to pass |
Frédéric Lécaille | 3aac106 | 2018-11-13 09:42:13 +0100 | [diff] [blame] | 6087 | to the client some Link headers to preload resources required to render the |
| 6088 | HTML documents. |
Frédéric Lécaille | 06f5b64 | 2018-11-12 11:01:10 +0100 | [diff] [blame] | 6089 | |
| 6090 | See RFC 8297 for more information. |
| 6091 | |
Tim Duesterhus | d371e99 | 2021-04-15 21:45:58 +0200 | [diff] [blame] | 6092 | http-request normalize-uri <normalizer> [ { if | unless } <condition> ] |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6093 | http-request normalize-uri path-merge-slashes [ { if | unless } <condition> ] |
Maximilian Mader | ff3bb8b | 2021-04-21 00:22:50 +0200 | [diff] [blame] | 6094 | http-request normalize-uri path-strip-dot [ { if | unless } <condition> ] |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6095 | http-request normalize-uri path-strip-dotdot [ full ] [ { if | unless } <condition> ] |
Tim Duesterhus | 2e4a18e | 2021-04-21 21:20:36 +0200 | [diff] [blame] | 6096 | http-request normalize-uri percent-decode-unreserved [ strict ] [ { if | unless } <condition> ] |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6097 | http-request normalize-uri percent-to-uppercase [ strict ] [ { if | unless } <condition> ] |
| 6098 | http-request normalize-uri query-sort-by-name [ { if | unless } <condition> ] |
Tim Duesterhus | d371e99 | 2021-04-15 21:45:58 +0200 | [diff] [blame] | 6099 | |
Tim Duesterhus | b918a4a | 2021-04-16 23:52:29 +0200 | [diff] [blame] | 6100 | Performs normalization of the request's URI. |
| 6101 | |
Tim Duesterhus | 2963fd3 | 2021-04-17 00:24:56 +0200 | [diff] [blame] | 6102 | URI normalization in HAProxy 2.4 is currently available as an experimental |
| 6103 | technical preview. You should be prepared that the behavior of normalizers |
| 6104 | might change to fix possible issues, possibly breaking proper request |
| 6105 | processing in your infrastructure. |
| 6106 | |
Tim Duesterhus | b918a4a | 2021-04-16 23:52:29 +0200 | [diff] [blame] | 6107 | Each normalizer handles a single type of normalization to allow for a |
| 6108 | fine-grained selection of the level of normalization that is appropriate for |
| 6109 | the supported backend. |
| 6110 | |
| 6111 | As an example the "path-strip-dotdot" normalizer might be useful for a static |
| 6112 | fileserver that directly maps the requested URI to the path within the local |
| 6113 | filesystem. However it might break routing of an API that expects a specific |
| 6114 | number of segments in the path. |
| 6115 | |
Tim Duesterhus | 2e4a18e | 2021-04-21 21:20:36 +0200 | [diff] [blame] | 6116 | It is important to note that some normalizers might result in unsafe |
| 6117 | transformations for broken URIs. It might also be possible that a combination |
| 6118 | of normalizers that are safe by themselves results in unsafe transformations |
| 6119 | when improperly combined. |
| 6120 | |
| 6121 | As an example the "percent-decode-unreserved" normalizer might result in |
| 6122 | unexpected results when a broken URI includes bare percent characters. One |
| 6123 | such a broken URI is "/%%36%36" which would be decoded to "/%66" which in |
| 6124 | turn is equivalent to "/f". By specifying the "strict" option requests to |
| 6125 | such a broken URI would safely be rejected. |
| 6126 | |
Tim Duesterhus | b918a4a | 2021-04-16 23:52:29 +0200 | [diff] [blame] | 6127 | The following normalizers are available: |
Tim Duesterhus | d371e99 | 2021-04-15 21:45:58 +0200 | [diff] [blame] | 6128 | |
Tim Duesterhus | d6d33de | 2021-04-21 21:20:35 +0200 | [diff] [blame] | 6129 | - path-strip-dot: Removes "/./" segments within the "path" component |
| 6130 | (RFC 3986#6.2.2.3). |
Maximilian Mader | ff3bb8b | 2021-04-21 00:22:50 +0200 | [diff] [blame] | 6131 | |
Tim Duesterhus | 2e4a18e | 2021-04-21 21:20:36 +0200 | [diff] [blame] | 6132 | Segments including percent encoded dots ("%2E") will not be detected. Use |
| 6133 | the "percent-decode-unreserved" normalizer first if this is undesired. |
| 6134 | |
Tim Duesterhus | 7a95f41 | 2021-04-21 21:20:33 +0200 | [diff] [blame] | 6135 | Example: |
| 6136 | - /. -> / |
| 6137 | - /./bar/ -> /bar/ |
| 6138 | - /a/./a -> /a/a |
| 6139 | - /.well-known/ -> /.well-known/ (no change) |
Maximilian Mader | ff3bb8b | 2021-04-21 00:22:50 +0200 | [diff] [blame] | 6140 | |
Tim Duesterhus | d6d33de | 2021-04-21 21:20:35 +0200 | [diff] [blame] | 6141 | - path-strip-dotdot: Normalizes "/../" segments within the "path" component |
| 6142 | (RFC 3986#6.2.2.3). |
| 6143 | |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6144 | This merges segments that attempt to access the parent directory with |
Tim Duesterhus | 2e4a18e | 2021-04-21 21:20:36 +0200 | [diff] [blame] | 6145 | their preceding segment. |
| 6146 | |
| 6147 | Empty segments do not receive special treatment. Use the "merge-slashes" |
| 6148 | normalizer first if this is undesired. |
| 6149 | |
| 6150 | Segments including percent encoded dots ("%2E") will not be detected. Use |
| 6151 | the "percent-decode-unreserved" normalizer first if this is undesired. |
Tim Duesterhus | 9982fc2 | 2021-04-15 21:45:59 +0200 | [diff] [blame] | 6152 | |
| 6153 | Example: |
| 6154 | - /foo/../ -> / |
| 6155 | - /foo/../bar/ -> /bar/ |
| 6156 | - /foo/bar/../ -> /foo/ |
| 6157 | - /../bar/ -> /../bar/ |
Tim Duesterhus | 560e1a6 | 2021-04-15 21:46:00 +0200 | [diff] [blame] | 6158 | - /bar/../../ -> /../ |
Tim Duesterhus | 9982fc2 | 2021-04-15 21:45:59 +0200 | [diff] [blame] | 6159 | - /foo//../ -> /foo/ |
Tim Duesterhus | 2e4a18e | 2021-04-21 21:20:36 +0200 | [diff] [blame] | 6160 | - /foo/%2E%2E/ -> /foo/%2E%2E/ |
Tim Duesterhus | 9982fc2 | 2021-04-15 21:45:59 +0200 | [diff] [blame] | 6161 | |
Tim Duesterhus | 560e1a6 | 2021-04-15 21:46:00 +0200 | [diff] [blame] | 6162 | If the "full" option is specified then "../" at the beginning will be |
| 6163 | removed as well: |
| 6164 | |
| 6165 | Example: |
| 6166 | - /../bar/ -> /bar/ |
| 6167 | - /bar/../../ -> / |
| 6168 | |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6169 | - path-merge-slashes: Merges adjacent slashes within the "path" component |
| 6170 | into a single slash. |
Tim Duesterhus | d371e99 | 2021-04-15 21:45:58 +0200 | [diff] [blame] | 6171 | |
| 6172 | Example: |
| 6173 | - // -> / |
| 6174 | - /foo//bar -> /foo/bar |
| 6175 | |
Tim Duesterhus | 2e4a18e | 2021-04-21 21:20:36 +0200 | [diff] [blame] | 6176 | - percent-decode-unreserved: Decodes unreserved percent encoded characters to |
| 6177 | their representation as a regular character (RFC 3986#6.2.2.2). |
| 6178 | |
| 6179 | The set of unreserved characters includes all letters, all digits, "-", |
| 6180 | ".", "_", and "~". |
| 6181 | |
| 6182 | Example: |
| 6183 | - /%61dmin -> /admin |
| 6184 | - /foo%3Fbar=baz -> /foo%3Fbar=baz (no change) |
| 6185 | - /%%36%36 -> /%66 (unsafe) |
| 6186 | - /%ZZ -> /%ZZ |
| 6187 | |
| 6188 | If the "strict" option is specified then invalid sequences will result |
| 6189 | in a HTTP 400 Bad Request being returned. |
| 6190 | |
| 6191 | Example: |
| 6192 | - /%%36%36 -> HTTP 400 |
| 6193 | - /%ZZ -> HTTP 400 |
| 6194 | |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6195 | - percent-to-uppercase: Uppercases letters within percent-encoded sequences |
Tim Duesterhus | c315efd | 2021-04-21 21:20:34 +0200 | [diff] [blame] | 6196 | (RFC 3986#6.2.2.1). |
Tim Duesterhus | a407193 | 2021-04-15 21:46:02 +0200 | [diff] [blame] | 6197 | |
| 6198 | Example: |
| 6199 | - /%6f -> /%6F |
| 6200 | - /%zz -> /%zz |
| 6201 | |
| 6202 | If the "strict" option is specified then invalid sequences will result |
| 6203 | in a HTTP 400 Bad Request being returned. |
| 6204 | |
| 6205 | Example: |
| 6206 | - /%zz -> HTTP 400 |
| 6207 | |
Tim Duesterhus | 5be6ab2 | 2021-04-17 11:21:10 +0200 | [diff] [blame] | 6208 | - query-sort-by-name: Sorts the query string parameters by parameter name. |
Tim Duesterhus | d7b89be | 2021-04-15 21:46:01 +0200 | [diff] [blame] | 6209 | Parameters are assumed to be delimited by '&'. Shorter names sort before |
| 6210 | longer names and identical parameter names maintain their relative order. |
| 6211 | |
| 6212 | Example: |
| 6213 | - /?c=3&a=1&b=2 -> /?a=1&b=2&c=3 |
| 6214 | - /?aaa=3&a=1&aa=2 -> /?a=1&aa=2&aaa=3 |
| 6215 | - /?a=3&b=4&a=1&b=5&a=2 -> /?a=3&a=1&a=2&b=4&b=5 |
| 6216 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6217 | http-request redirect <rule> [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6218 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6219 | This performs an HTTP redirection based on a redirect rule. This is exactly |
| 6220 | the same as the "redirect" statement except that it inserts a redirect rule |
| 6221 | which can be processed in the middle of other "http-request" rules and that |
| 6222 | these rules use the "log-format" strings. See the "redirect" keyword for the |
| 6223 | rule's syntax. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6224 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6225 | http-request reject [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6226 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6227 | This stops the evaluation of the rules and immediately closes the connection |
| 6228 | without sending any response. It acts similarly to the |
| 6229 | "tcp-request content reject" rules. It can be useful to force an immediate |
| 6230 | connection closure on HTTP/2 connections. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6231 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6232 | http-request replace-header <name> <match-regex> <replace-fmt> |
| 6233 | [ { if | unless } <condition> ] |
Willy Tarreau | a9083d0 | 2015-05-08 15:27:59 +0200 | [diff] [blame] | 6234 | |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 6235 | This matches the value of all occurrences of header field <name> against |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6236 | <match-regex>. Matching is performed case-sensitively. Matching values are |
| 6237 | completely replaced by <replace-fmt>. Format characters are allowed in |
| 6238 | <replace-fmt> and work like <fmt> arguments in "http-request add-header". |
| 6239 | Standard back-references using the backslash ('\') followed by a number are |
| 6240 | supported. |
Thierry FOURNIER | 82bf70d | 2015-05-26 17:58:29 +0200 | [diff] [blame] | 6241 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6242 | This action acts on whole header lines, regardless of the number of values |
| 6243 | they may contain. Thus it is well-suited to process headers naturally |
| 6244 | containing commas in their value, such as If-Modified-Since. Headers that |
| 6245 | contain a comma-separated list of values, such as Accept, should be processed |
| 6246 | using "http-request replace-value". |
William Lallemand | 86d0df0 | 2017-11-24 21:36:45 +0100 | [diff] [blame] | 6247 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6248 | Example: |
| 6249 | http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2 |
| 6250 | |
| 6251 | # applied to: |
| 6252 | Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT; |
| 6253 | |
| 6254 | # outputs: |
| 6255 | Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT; |
| 6256 | |
| 6257 | # assuming the backend IP is 192.168.1.20 |
Willy Tarreau | 09448f7 | 2014-06-25 18:12:15 +0200 | [diff] [blame] | 6258 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6259 | http-request replace-header User-Agent curl foo |
| 6260 | |
| 6261 | # applied to: |
| 6262 | User-Agent: curl/7.47.0 |
Willy Tarreau | 09448f7 | 2014-06-25 18:12:15 +0200 | [diff] [blame] | 6263 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6264 | # outputs: |
| 6265 | User-Agent: foo |
Willy Tarreau | 09448f7 | 2014-06-25 18:12:15 +0200 | [diff] [blame] | 6266 | |
Willy Tarreau | 262c3f1 | 2019-12-17 06:52:51 +0100 | [diff] [blame] | 6267 | http-request replace-path <match-regex> <replace-fmt> |
| 6268 | [ { if | unless } <condition> ] |
| 6269 | |
| 6270 | This works like "replace-header" except that it works on the request's path |
| 6271 | component instead of a header. The path component starts at the first '/' |
Christopher Faulet | 82c8332 | 2020-09-02 14:16:59 +0200 | [diff] [blame] | 6272 | after an optional scheme+authority and ends before the question mark. Thus, |
| 6273 | the replacement does not modify the scheme, the authority and the |
| 6274 | query-string. |
Willy Tarreau | 262c3f1 | 2019-12-17 06:52:51 +0100 | [diff] [blame] | 6275 | |
| 6276 | It is worth noting that regular expressions may be more expensive to evaluate |
| 6277 | than certain ACLs, so rare replacements may benefit from a condition to avoid |
| 6278 | performing the evaluation at all if it does not match. |
| 6279 | |
| 6280 | Example: |
| 6281 | # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 : |
| 6282 | http-request replace-path (.*) /foo\1 |
| 6283 | |
Willy Tarreau | 262c3f1 | 2019-12-17 06:52:51 +0100 | [diff] [blame] | 6284 | # strip /foo : turn /foo/bar?q=1 into /bar?q=1 |
| 6285 | http-request replace-path /foo/(.*) /\1 |
| 6286 | # or more efficient if only some requests match : |
| 6287 | http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ } |
| 6288 | |
Christopher Faulet | 312294f | 2020-09-02 17:17:44 +0200 | [diff] [blame] | 6289 | http-request replace-pathq <match-regex> <replace-fmt> |
| 6290 | [ { if | unless } <condition> ] |
| 6291 | |
| 6292 | This does the same as "http-request replace-path" except that the path |
| 6293 | contains the query-string if any is present. Thus, the path and the |
| 6294 | query-string are replaced. |
| 6295 | |
| 6296 | Example: |
| 6297 | # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 : |
| 6298 | http-request replace-pathq ([^?]*)(\?(.*))? \1/foo\2 |
| 6299 | |
Willy Tarreau | 3381022 | 2019-06-12 17:44:02 +0200 | [diff] [blame] | 6300 | http-request replace-uri <match-regex> <replace-fmt> |
| 6301 | [ { if | unless } <condition> ] |
| 6302 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6303 | This works like "replace-header" except that it works on the request's URI part |
| 6304 | instead of a header. The URI part may contain an optional scheme, authority or |
| 6305 | query string. These are considered to be part of the value that is matched |
| 6306 | against. |
| 6307 | |
| 6308 | It is worth noting that regular expressions may be more expensive to evaluate |
| 6309 | than certain ACLs, so rare replacements may benefit from a condition to avoid |
| 6310 | performing the evaluation at all if it does not match. |
Willy Tarreau | 3381022 | 2019-06-12 17:44:02 +0200 | [diff] [blame] | 6311 | |
Willy Tarreau | 62b5913 | 2019-12-17 06:51:20 +0100 | [diff] [blame] | 6312 | IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent |
| 6313 | by browsers use the "origin form", which differs from the "absolute form" in |
| 6314 | that they do not contain a scheme nor authority in the URI portion. Mostly |
| 6315 | only requests sent to proxies, those forged by hand and some emitted by |
| 6316 | certain applications use the absolute form. As such, "replace-uri" usually |
| 6317 | works fine most of the time in HTTP/1.x with rules starting with a "/". But |
| 6318 | with HTTP/2, clients are encouraged to send absolute URIs only, which look |
| 6319 | like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri |
| 6320 | rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need |
Willy Tarreau | 262c3f1 | 2019-12-17 06:52:51 +0100 | [diff] [blame] | 6321 | to be adapted to optionally match a scheme and authority, or replace-path |
| 6322 | should be used. |
Willy Tarreau | 3381022 | 2019-06-12 17:44:02 +0200 | [diff] [blame] | 6323 | |
Willy Tarreau | 62b5913 | 2019-12-17 06:51:20 +0100 | [diff] [blame] | 6324 | Example: |
| 6325 | # rewrite all "http" absolute requests to "https": |
| 6326 | http-request replace-uri ^http://(.*) https://\1 |
Willy Tarreau | 3381022 | 2019-06-12 17:44:02 +0200 | [diff] [blame] | 6327 | |
Willy Tarreau | 62b5913 | 2019-12-17 06:51:20 +0100 | [diff] [blame] | 6328 | # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 : |
| 6329 | http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2 |
Willy Tarreau | 3381022 | 2019-06-12 17:44:02 +0200 | [diff] [blame] | 6330 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6331 | http-request replace-value <name> <match-regex> <replace-fmt> |
| 6332 | [ { if | unless } <condition> ] |
Willy Tarreau | 09448f7 | 2014-06-25 18:12:15 +0200 | [diff] [blame] | 6333 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6334 | This works like "replace-header" except that it matches the regex against |
| 6335 | every comma-delimited value of the header field <name> instead of the |
| 6336 | entire header. This is suited for all headers which are allowed to carry |
| 6337 | more than one value. An example could be the Accept header. |
Willy Tarreau | 09448f7 | 2014-06-25 18:12:15 +0200 | [diff] [blame] | 6338 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6339 | Example: |
| 6340 | http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1 |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 6341 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6342 | # applied to: |
| 6343 | X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37 |
Thierry FOURNIER | e0627bd | 2015-08-04 08:20:33 +0200 | [diff] [blame] | 6344 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 6345 | # outputs: |
| 6346 | X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37 |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 6347 | |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6348 | http-request return [status <code>] [content-type <type>] |
| 6349 | [ { default-errorfiles | errorfile <file> | errorfiles <name> | |
| 6350 | file <file> | lf-file <file> | string <str> | lf-string <fmt> } ] |
Christopher Faulet | 4a2c142 | 2020-01-31 17:36:01 +0100 | [diff] [blame] | 6351 | [ hdr <name> <fmt> ]* |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6352 | [ { if | unless } <condition> ] |
| 6353 | |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 6354 | This stops the evaluation of the rules and immediately returns a response. The |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6355 | default status code used for the response is 200. It can be optionally |
| 6356 | specified as an arguments to "status". The response content-type may also be |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 6357 | specified as an argument to "content-type". Finally the response itself may |
Sébastien Gross | ab87712 | 2020-10-08 10:06:03 +0200 | [diff] [blame] | 6358 | be defined. It can be a full HTTP response specifying the errorfile to use, |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 6359 | or the response payload specifying the file or the string to use. These rules |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6360 | are followed to create the response : |
| 6361 | |
| 6362 | * If neither the errorfile nor the payload to use is defined, a dummy |
| 6363 | response is returned. Only the "status" argument is considered. It can be |
| 6364 | any code in the range [200, 599]. The "content-type" argument, if any, is |
| 6365 | ignored. |
| 6366 | |
| 6367 | * If "default-errorfiles" argument is set, the proxy's errorfiles are |
| 6368 | considered. If the "status" argument is defined, it must be one of the |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 6369 | status code handled by haproxy (200, 400, 403, 404, 405, 408, 410, 413, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 6370 | 425, 429, 500, 501, 502, 503, and 504). The "content-type" argument, if |
| 6371 | any, is ignored. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6372 | |
| 6373 | * If a specific errorfile is defined, with an "errorfile" argument, the |
| 6374 | corresponding file, containing a full HTTP response, is returned. Only the |
| 6375 | "status" argument is considered. It must be one of the status code handled |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 6376 | by haproxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 501, |
| 6377 | 502, 503, and 504). The "content-type" argument, if any, is ignored. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6378 | |
| 6379 | * If an http-errors section is defined, with an "errorfiles" argument, the |
| 6380 | corresponding file in the specified http-errors section, containing a full |
| 6381 | HTTP response, is returned. Only the "status" argument is considered. It |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 6382 | must be one of the status code handled by haproxy (200, 400, 403, 404, 405, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 6383 | 408, 410, 413, 425, 429, 500, 501, 502, 503, and 504). The "content-type" |
Anthonin Bonnefoy | 85048f8 | 2020-06-22 09:17:01 +0200 | [diff] [blame] | 6384 | argument, if any, is ignored. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6385 | |
| 6386 | * If a "file" or a "lf-file" argument is specified, the file's content is |
| 6387 | used as the response payload. If the file is not empty, its content-type |
| 6388 | must be set as argument to "content-type". Otherwise, any "content-type" |
| 6389 | argument is ignored. With a "lf-file" argument, the file's content is |
| 6390 | evaluated as a log-format string. With a "file" argument, it is considered |
| 6391 | as a raw content. |
| 6392 | |
| 6393 | * If a "string" or "lf-string" argument is specified, the defined string is |
| 6394 | used as the response payload. The content-type must always be set as |
| 6395 | argument to "content-type". With a "lf-string" argument, the string is |
| 6396 | evaluated as a log-format string. With a "string" argument, it is |
| 6397 | considered as a raw string. |
| 6398 | |
Sébastien Gross | ab87712 | 2020-10-08 10:06:03 +0200 | [diff] [blame] | 6399 | When the response is not based on an errorfile, it is possible to append HTTP |
Christopher Faulet | 4a2c142 | 2020-01-31 17:36:01 +0100 | [diff] [blame] | 6400 | header fields to the response using "hdr" arguments. Otherwise, all "hdr" |
| 6401 | arguments are ignored. For each one, the header name is specified in <name> |
| 6402 | and its value is defined by <fmt> which follows the log-format rules. |
| 6403 | |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6404 | Note that the generated response must be smaller than a buffer. And to avoid |
| 6405 | any warning, when an errorfile or a raw file is loaded, the buffer space |
Sébastien Gross | ab87712 | 2020-10-08 10:06:03 +0200 | [diff] [blame] | 6406 | reserved for the headers rewriting should also be free. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6407 | |
| 6408 | No further "http-request" rules are evaluated. |
| 6409 | |
| 6410 | Example: |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 6411 | http-request return errorfile /etc/haproxy/errorfiles/200.http \ |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 6412 | if { path /ping } |
| 6413 | |
| 6414 | http-request return content-type image/x-icon file /var/www/favicon.ico \ |
| 6415 | if { path /favicon.ico } |
| 6416 | |
| 6417 | http-request return status 403 content-type text/plain \ |
| 6418 | lf-string "Access denied. IP %[src] is blacklisted." \ |
| 6419 | if { src -f /etc/haproxy/blacklist.lst } |
| 6420 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6421 | http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ] |
| 6422 | http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ] |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 6423 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6424 | This actions increments the GPC0 or GPC1 counter according with the sticky |
| 6425 | counter designated by <sc-id>. If an error occurs, this action silently fails |
| 6426 | and the actions evaluation continues. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 6427 | |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 6428 | http-request sc-set-gpt0(<sc-id>) { <int> | <expr> } |
| 6429 | [ { if | unless } <condition> ] |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 6430 | |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 6431 | This action sets the 32-bit unsigned GPT0 tag according to the sticky counter |
| 6432 | designated by <sc-id> and the value of <int>/<expr>. The expected result is a |
| 6433 | boolean. If an error occurs, this action silently fails and the actions |
| 6434 | evaluation continues. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 6435 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6436 | http-request set-dst <expr> [ { if | unless } <condition> ] |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 6437 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6438 | This is used to set the destination IP address to the value of specified |
| 6439 | expression. Useful when a proxy in front of HAProxy rewrites destination IP, |
| 6440 | but provides the correct IP in a HTTP header; or you want to mask the IP for |
| 6441 | privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a |
| 6442 | server address in the backend. |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 6443 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6444 | Arguments: |
| 6445 | <expr> Is a standard HAProxy expression formed by a sample-fetch followed |
| 6446 | by some converters. |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 6447 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6448 | Example: |
| 6449 | http-request set-dst hdr(x-dst) |
| 6450 | http-request set-dst dst,ipmask(24) |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 6451 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6452 | When possible, set-dst preserves the original destination port as long as the |
| 6453 | address family allows it, otherwise the destination port is set to 0. |
Adis Nezirovic | 2fbcafc | 2015-07-06 15:44:30 +0200 | [diff] [blame] | 6454 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6455 | http-request set-dst-port <expr> [ { if | unless } <condition> ] |
Adis Nezirovic | 2fbcafc | 2015-07-06 15:44:30 +0200 | [diff] [blame] | 6456 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6457 | This is used to set the destination port address to the value of specified |
| 6458 | expression. If you want to connect to the new address/port, use '0.0.0.0:0' |
| 6459 | as a server address in the backend. |
Adis Nezirovic | 2fbcafc | 2015-07-06 15:44:30 +0200 | [diff] [blame] | 6460 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6461 | Arguments: |
| 6462 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 6463 | followed by some converters. |
Adis Nezirovic | 2fbcafc | 2015-07-06 15:44:30 +0200 | [diff] [blame] | 6464 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6465 | Example: |
| 6466 | http-request set-dst-port hdr(x-port) |
| 6467 | http-request set-dst-port int(4000) |
Adis Nezirovic | 2fbcafc | 2015-07-06 15:44:30 +0200 | [diff] [blame] | 6468 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6469 | When possible, set-dst-port preserves the original destination address as |
| 6470 | long as the address family supports a port, otherwise it forces the |
| 6471 | destination address to IPv4 "0.0.0.0" before rewriting the port. |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 6472 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6473 | http-request set-header <name> <fmt> [ { if | unless } <condition> ] |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 6474 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6475 | This does the same as "http-request add-header" except that the header name |
| 6476 | is first removed if it existed. This is useful when passing security |
| 6477 | information to the server, where the header must not be manipulated by |
| 6478 | external users. Note that the new value is computed before the removal so it |
| 6479 | is possible to concatenate a value to an existing header. |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 6480 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6481 | Example: |
| 6482 | http-request set-header X-Haproxy-Current-Date %T |
| 6483 | http-request set-header X-SSL %[ssl_fc] |
| 6484 | http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex] |
| 6485 | http-request set-header X-SSL-Client-Verify %[ssl_c_verify] |
| 6486 | http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn] |
| 6487 | http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)] |
| 6488 | http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn] |
| 6489 | http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore] |
| 6490 | http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter] |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 6491 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6492 | http-request set-log-level <level> [ { if | unless } <condition> ] |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 6493 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6494 | This is used to change the log level of the current request when a certain |
| 6495 | condition is met. Valid levels are the 8 syslog levels (see the "log" |
| 6496 | keyword) plus the special level "silent" which disables logging for this |
| 6497 | request. This rule is not final so the last matching rule wins. This rule |
| 6498 | can be useful to disable health checks coming from another equipment. |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6499 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6500 | http-request set-map(<file-name>) <key fmt> <value fmt> |
| 6501 | [ { if | unless } <condition> ] |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6502 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6503 | This is used to add a new entry into a MAP. The MAP must be loaded from a |
| 6504 | file (even a dummy empty file). The file name of the MAP to be updated is |
| 6505 | passed between parentheses. It takes 2 arguments: <key fmt>, which follows |
| 6506 | log-format rules, used to collect MAP key, and <value fmt>, which follows |
| 6507 | log-format rules, used to collect content for the new entry. |
| 6508 | It performs a lookup in the MAP before insertion, to avoid duplicated (or |
| 6509 | more) values. This lookup is done by a linear search and can be expensive |
| 6510 | with large lists! It is the equivalent of the "set map" command from the |
| 6511 | stats socket, but can be triggered by an HTTP request. |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6512 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6513 | http-request set-mark <mark> [ { if | unless } <condition> ] |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6514 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6515 | This is used to set the Netfilter MARK on all packets sent to the client to |
| 6516 | the value passed in <mark> on platforms which support it. This value is an |
| 6517 | unsigned 32 bit value which can be matched by netfilter and by the routing |
| 6518 | table. It can be expressed both in decimal or hexadecimal format (prefixed by |
| 6519 | "0x"). This can be useful to force certain packets to take a different route |
| 6520 | (for example a cheaper network path for bulk downloads). This works on Linux |
| 6521 | kernels 2.6.32 and above and requires admin privileges. |
Willy Tarreau | 00005ce | 2016-10-21 15:07:45 +0200 | [diff] [blame] | 6522 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6523 | http-request set-method <fmt> [ { if | unless } <condition> ] |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6524 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6525 | This rewrites the request method with the result of the evaluation of format |
| 6526 | string <fmt>. There should be very few valid reasons for having to do so as |
| 6527 | this is more likely to break something than to fix it. |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6528 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6529 | http-request set-nice <nice> [ { if | unless } <condition> ] |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6530 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6531 | This sets the "nice" factor of the current request being processed. It only |
| 6532 | has effect against the other requests being processed at the same time. |
| 6533 | The default value is 0, unless altered by the "nice" setting on the "bind" |
| 6534 | line. The accepted range is -1024..1024. The higher the value, the nicest |
| 6535 | the request will be. Lower values will make the request more important than |
| 6536 | other ones. This can be useful to improve the speed of some requests, or |
| 6537 | lower the priority of non-important requests. Using this setting without |
| 6538 | prior experimentation can cause some major slowdown. |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 6539 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6540 | http-request set-path <fmt> [ { if | unless } <condition> ] |
Willy Tarreau | 00005ce | 2016-10-21 15:07:45 +0200 | [diff] [blame] | 6541 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6542 | This rewrites the request path with the result of the evaluation of format |
| 6543 | string <fmt>. The query string, if any, is left intact. If a scheme and |
| 6544 | authority is found before the path, they are left intact as well. If the |
| 6545 | request doesn't have a path ("*"), this one is replaced with the format. |
| 6546 | This can be used to prepend a directory component in front of a path for |
| 6547 | example. See also "http-request set-query" and "http-request set-uri". |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 6548 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6549 | Example : |
| 6550 | # prepend the host name before the path |
| 6551 | http-request set-path /%[hdr(host)]%[path] |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 6552 | |
Christopher Faulet | 312294f | 2020-09-02 17:17:44 +0200 | [diff] [blame] | 6553 | http-request set-pathq <fmt> [ { if | unless } <condition> ] |
| 6554 | |
| 6555 | This does the same as "http-request set-path" except that the query-string is |
| 6556 | also rewritten. It may be used to remove the query-string, including the |
| 6557 | question mark (it is not possible using "http-request set-query"). |
| 6558 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6559 | http-request set-priority-class <expr> [ { if | unless } <condition> ] |
Olivier Houchard | ccaa7de | 2017-10-02 11:51:03 +0200 | [diff] [blame] | 6560 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6561 | This is used to set the queue priority class of the current request. |
| 6562 | The value must be a sample expression which converts to an integer in the |
| 6563 | range -2047..2047. Results outside this range will be truncated. |
| 6564 | The priority class determines the order in which queued requests are |
| 6565 | processed. Lower values have higher priority. |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 6566 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6567 | http-request set-priority-offset <expr> [ { if | unless } <condition> ] |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 6568 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6569 | This is used to set the queue priority timestamp offset of the current |
| 6570 | request. The value must be a sample expression which converts to an integer |
| 6571 | in the range -524287..524287. Results outside this range will be truncated. |
| 6572 | When a request is queued, it is ordered first by the priority class, then by |
| 6573 | the current timestamp adjusted by the given offset in milliseconds. Lower |
| 6574 | values have higher priority. |
| 6575 | Note that the resulting timestamp is is only tracked with enough precision |
| 6576 | for 524,287ms (8m44s287ms). If the request is queued long enough to where the |
| 6577 | adjusted timestamp exceeds this value, it will be misidentified as highest |
| 6578 | priority. Thus it is important to set "timeout queue" to a value, where when |
| 6579 | combined with the offset, does not exceed this limit. |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 6580 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6581 | http-request set-query <fmt> [ { if | unless } <condition> ] |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 6582 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6583 | This rewrites the request's query string which appears after the first |
| 6584 | question mark ("?") with the result of the evaluation of format string <fmt>. |
| 6585 | The part prior to the question mark is left intact. If the request doesn't |
| 6586 | contain a question mark and the new value is not empty, then one is added at |
| 6587 | the end of the URI, followed by the new value. If a question mark was |
| 6588 | present, it will never be removed even if the value is empty. This can be |
| 6589 | used to add or remove parameters from the query string. |
Ruoshan Huang | eb5a363 | 2015-12-08 21:00:23 +0800 | [diff] [blame] | 6590 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6591 | See also "http-request set-query" and "http-request set-uri". |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 6592 | |
| 6593 | Example: |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6594 | # replace "%3D" with "=" in the query string |
| 6595 | http-request set-query %[query,regsub(%3D,=,g)] |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 6596 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6597 | http-request set-src <expr> [ { if | unless } <condition> ] |
| 6598 | This is used to set the source IP address to the value of specified |
| 6599 | expression. Useful when a proxy in front of HAProxy rewrites source IP, but |
| 6600 | provides the correct IP in a HTTP header; or you want to mask source IP for |
Olivier Doucet | 56e3120 | 2020-04-21 09:32:56 +0200 | [diff] [blame] | 6601 | privacy. All subsequent calls to "src" fetch will return this value |
| 6602 | (see example). |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6603 | |
| 6604 | Arguments : |
| 6605 | <expr> Is a standard HAProxy expression formed by a sample-fetch followed |
| 6606 | by some converters. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 6607 | |
Olivier Doucet | 56e3120 | 2020-04-21 09:32:56 +0200 | [diff] [blame] | 6608 | See also "option forwardfor". |
| 6609 | |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 6610 | Example: |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6611 | http-request set-src hdr(x-forwarded-for) |
| 6612 | http-request set-src src,ipmask(24) |
| 6613 | |
Olivier Doucet | 56e3120 | 2020-04-21 09:32:56 +0200 | [diff] [blame] | 6614 | # After the masking this will track connections |
| 6615 | # based on the IP address with the last byte zeroed out. |
| 6616 | http-request track-sc0 src |
| 6617 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6618 | When possible, set-src preserves the original source port as long as the |
| 6619 | address family allows it, otherwise the source port is set to 0. |
| 6620 | |
| 6621 | http-request set-src-port <expr> [ { if | unless } <condition> ] |
| 6622 | |
| 6623 | This is used to set the source port address to the value of specified |
| 6624 | expression. |
| 6625 | |
| 6626 | Arguments: |
| 6627 | <expr> Is a standard HAProxy expression formed by a sample-fetch followed |
| 6628 | by some converters. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 6629 | |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 6630 | Example: |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6631 | http-request set-src-port hdr(x-port) |
| 6632 | http-request set-src-port int(4000) |
| 6633 | |
| 6634 | When possible, set-src-port preserves the original source address as long as |
| 6635 | the address family supports a port, otherwise it forces the source address to |
| 6636 | IPv4 "0.0.0.0" before rewriting the port. |
| 6637 | |
Alex | 59c5335 | 2021-04-27 12:57:07 +0200 | [diff] [blame] | 6638 | http-request set-timeout { server | tunnel } { <timeout> | <expr> } |
Amaury Denoyelle | 8d22823 | 2020-12-10 13:43:54 +0100 | [diff] [blame] | 6639 | [ { if | unless } <condition> ] |
| 6640 | |
| 6641 | This action overrides the specified "server" or "tunnel" timeout for the |
| 6642 | current stream only. The timeout can be specified in millisecond or with any |
| 6643 | other unit if the number is suffixed by the unit as explained at the top of |
| 6644 | this document. It is also possible to write an expression which must returns |
| 6645 | a number interpreted as a timeout in millisecond. |
| 6646 | |
| 6647 | Note that the server/tunnel timeouts are only relevant on the backend side |
| 6648 | and thus this rule is only available for the proxies with backend |
| 6649 | capabilities. Also the timeout value must be non-null to obtain the expected |
| 6650 | results. |
| 6651 | |
| 6652 | Example: |
Alex | 59c5335 | 2021-04-27 12:57:07 +0200 | [diff] [blame] | 6653 | http-request set-timeout tunnel 5s |
| 6654 | http-request set-timeout server req.hdr(host),map_int(host.lst) |
Amaury Denoyelle | 8d22823 | 2020-12-10 13:43:54 +0100 | [diff] [blame] | 6655 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6656 | http-request set-tos <tos> [ { if | unless } <condition> ] |
| 6657 | |
| 6658 | This is used to set the TOS or DSCP field value of packets sent to the client |
| 6659 | to the value passed in <tos> on platforms which support this. This value |
| 6660 | represents the whole 8 bits of the IP TOS field, and can be expressed both in |
| 6661 | decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher |
| 6662 | bits are used in DSCP or TOS, and the two lower bits are always 0. This can |
| 6663 | be used to adjust some routing behavior on border routers based on some |
| 6664 | information from the request. |
| 6665 | |
| 6666 | See RFC 2474, 2597, 3260 and 4594 for more information. |
| 6667 | |
| 6668 | http-request set-uri <fmt> [ { if | unless } <condition> ] |
| 6669 | |
| 6670 | This rewrites the request URI with the result of the evaluation of format |
| 6671 | string <fmt>. The scheme, authority, path and query string are all replaced |
| 6672 | at once. This can be used to rewrite hosts in front of proxies, or to |
| 6673 | perform complex modifications to the URI such as moving parts between the |
| 6674 | path and the query string. |
| 6675 | See also "http-request set-path" and "http-request set-query". |
| 6676 | |
| 6677 | http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ] |
| 6678 | |
| 6679 | This is used to set the contents of a variable. The variable is declared |
| 6680 | inline. |
| 6681 | |
| 6682 | Arguments: |
| 6683 | <var-name> The name of the variable starts with an indication about its |
| 6684 | scope. The scopes allowed are: |
| 6685 | "proc" : the variable is shared with the whole process |
| 6686 | "sess" : the variable is shared with the whole session |
| 6687 | "txn" : the variable is shared with the transaction |
| 6688 | (request and response) |
| 6689 | "req" : the variable is shared only during request |
| 6690 | processing |
| 6691 | "res" : the variable is shared only during response |
| 6692 | processing |
| 6693 | This prefix is followed by a name. The separator is a '.'. |
| 6694 | The name may only contain characters 'a-z', 'A-Z', '0-9' |
| 6695 | and '_'. |
| 6696 | |
| 6697 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 6698 | followed by some converters. |
Willy Tarreau | 20b0de5 | 2012-12-24 15:45:22 +0100 | [diff] [blame] | 6699 | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6700 | Example: |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6701 | http-request set-var(req.my_var) req.fhdr(user-agent),lower |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6702 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6703 | http-request send-spoe-group <engine-name> <group-name> |
| 6704 | [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6705 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6706 | This action is used to trigger sending of a group of SPOE messages. To do so, |
| 6707 | the SPOE engine used to send messages must be defined, as well as the SPOE |
| 6708 | group to send. Of course, the SPOE engine must refer to an existing SPOE |
| 6709 | filter. If not engine name is provided on the SPOE filter line, the SPOE |
| 6710 | agent name must be used. |
| 6711 | |
| 6712 | Arguments: |
| 6713 | <engine-name> The SPOE engine name. |
| 6714 | |
| 6715 | <group-name> The SPOE group name as specified in the engine |
| 6716 | configuration. |
| 6717 | |
| 6718 | http-request silent-drop [ { if | unless } <condition> ] |
| 6719 | |
| 6720 | This stops the evaluation of the rules and makes the client-facing connection |
| 6721 | suddenly disappear using a system-dependent way that tries to prevent the |
| 6722 | client from being notified. The effect it then that the client still sees an |
| 6723 | established connection while there's none on HAProxy. The purpose is to |
| 6724 | achieve a comparable effect to "tarpit" except that it doesn't use any local |
| 6725 | resource at all on the machine running HAProxy. It can resist much higher |
| 6726 | loads than "tarpit", and slow down stronger attackers. It is important to |
| 6727 | understand the impact of using this mechanism. All stateful equipment placed |
| 6728 | between the client and HAProxy (firewalls, proxies, load balancers) will also |
| 6729 | keep the established connection for a long time and may suffer from this |
| 6730 | action. |
| 6731 | On modern Linux systems running with enough privileges, the TCP_REPAIR socket |
| 6732 | option is used to block the emission of a TCP reset. On other systems, the |
| 6733 | socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first |
| 6734 | router, though it's still delivered to local networks. Do not use it unless |
| 6735 | you fully understand how it works. |
| 6736 | |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 6737 | http-request strict-mode { on | off } |
| 6738 | |
| 6739 | This enables or disables the strict rewriting mode for following rules. It |
| 6740 | does not affect rules declared before it and it is only applicable on rules |
| 6741 | performing a rewrite on the requests. When the strict mode is enabled, any |
| 6742 | rewrite failure triggers an internal error. Otherwise, such errors are |
| 6743 | silently ignored. The purpose of the strict rewriting mode is to make some |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 6744 | rewrites optional while others must be performed to continue the request |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 6745 | processing. |
| 6746 | |
Christopher Faulet | 1aea50e | 2020-01-17 16:03:53 +0100 | [diff] [blame] | 6747 | By default, the strict rewriting mode is enabled. Its value is also reset |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 6748 | when a ruleset evaluation ends. So, for instance, if you change the mode on |
| 6749 | the frontend, the default mode is restored when HAProxy starts the backend |
| 6750 | rules evaluation. |
| 6751 | |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6752 | http-request tarpit [deny_status <status>] [ { if | unless } <condition> ] |
| 6753 | http-request tarpit [ { status | deny_status } <code>] [content-type <type>] |
| 6754 | [ { default-errorfiles | errorfile <file> | errorfiles <name> | |
| 6755 | file <file> | lf-file <file> | string <str> | lf-string <fmt> } ] |
| 6756 | [ hdr <name> <fmt> ]* |
| 6757 | [ { if | unless } <condition> ] |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6758 | |
| 6759 | This stops the evaluation of the rules and immediately blocks the request |
| 6760 | without responding for a delay specified by "timeout tarpit" or |
| 6761 | "timeout connect" if the former is not set. After that delay, if the client |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6762 | is still connected, a response is returned so that the client does not |
| 6763 | suspect it has been tarpitted. Logs will report the flags "PT". The goal of |
| 6764 | the tarpit rule is to slow down robots during an attack when they're limited |
| 6765 | on the number of concurrent requests. It can be very efficient against very |
| 6766 | dumb robots, and will significantly reduce the load on firewalls compared to |
| 6767 | a "deny" rule. But when facing "correctly" developed robots, it can make |
| 6768 | things worse by forcing haproxy and the front firewall to support insane |
| 6769 | number of concurrent connections. By default an HTTP error 500 is returned. |
| 6770 | But the response may be customized using same syntax than |
| 6771 | "http-request return" rules. Thus, see "http-request return" for details. |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 6772 | For compatibility purpose, when no argument is defined, or only "deny_status", |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6773 | the argument "default-errorfiles" is implied. It means |
| 6774 | "http-request tarpit [deny_status <status>]" is an alias of |
| 6775 | "http-request tarpit [status <status>] default-errorfiles". |
| 6776 | No further "http-request" rules are evaluated. |
| 6777 | See also "http-request return" and "http-request silent-drop". |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6778 | |
| 6779 | http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ] |
| 6780 | http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ] |
| 6781 | http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ] |
| 6782 | |
| 6783 | This enables tracking of sticky counters from current request. These rules do |
| 6784 | not stop evaluation and do not change default action. The number of counters |
| 6785 | that may be simultaneously tracked by the same connection is set in |
| 6786 | MAX_SESS_STKCTR at build time (reported in haproxy -vv) which defaults to 3, |
Matteo Contrini | 1857b8c | 2020-10-16 17:35:54 +0200 | [diff] [blame] | 6787 | so the track-sc number is between 0 and (MAX_SESS_STKCTR-1). The first |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6788 | "track-sc0" rule executed enables tracking of the counters of the specified |
| 6789 | table as the first set. The first "track-sc1" rule executed enables tracking |
| 6790 | of the counters of the specified table as the second set. The first |
| 6791 | "track-sc2" rule executed enables tracking of the counters of the specified |
| 6792 | table as the third set. It is a recommended practice to use the first set of |
| 6793 | counters for the per-frontend counters and the second set for the per-backend |
| 6794 | ones. But this is just a guideline, all may be used everywhere. |
| 6795 | |
| 6796 | Arguments : |
| 6797 | <key> is mandatory, and is a sample expression rule as described in |
| 6798 | section 7.3. It describes what elements of the incoming request or |
| 6799 | connection will be analyzed, extracted, combined, and used to |
| 6800 | select which table entry to update the counters. |
| 6801 | |
| 6802 | <table> is an optional table to be used instead of the default one, which |
| 6803 | is the stick-table declared in the current proxy. All the counters |
| 6804 | for the matches and updates for the key will then be performed in |
| 6805 | that table until the session ends. |
| 6806 | |
| 6807 | Once a "track-sc*" rule is executed, the key is looked up in the table and if |
| 6808 | it is not found, an entry is allocated for it. Then a pointer to that entry |
| 6809 | is kept during all the session's life, and this entry's counters are updated |
| 6810 | as often as possible, every time the session's counters are updated, and also |
| 6811 | systematically when the session ends. Counters are only updated for events |
| 6812 | that happen after the tracking has been started. As an exception, connection |
| 6813 | counters and request counters are systematically updated so that they reflect |
| 6814 | useful information. |
| 6815 | |
| 6816 | If the entry tracks concurrent connection counters, one connection is counted |
| 6817 | for as long as the entry is tracked, and the entry will not expire during |
| 6818 | that time. Tracking counters also provides a performance advantage over just |
| 6819 | checking the keys, because only one table lookup is performed for all ACL |
| 6820 | checks that make use of it. |
| 6821 | |
| 6822 | http-request unset-var(<var-name>) [ { if | unless } <condition> ] |
| 6823 | |
| 6824 | This is used to unset a variable. See above for details about <var-name>. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6825 | |
| 6826 | Example: |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6827 | http-request unset-var(req.my_var) |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6828 | |
Christopher Faulet | 579d83b | 2019-11-22 15:34:17 +0100 | [diff] [blame] | 6829 | http-request use-service <service-name> [ { if | unless } <condition> ] |
| 6830 | |
| 6831 | This directive executes the configured HTTP service to reply to the request |
| 6832 | and stops the evaluation of the rules. An HTTP service may choose to reply by |
| 6833 | sending any valid HTTP response or it may immediately close the connection |
| 6834 | without sending any response. Outside natives services, for instance the |
| 6835 | Prometheus exporter, it is possible to write your own services in Lua. No |
| 6836 | further "http-request" rules are evaluated. |
| 6837 | |
| 6838 | Arguments : |
| 6839 | <service-name> is mandatory. It is the service to call |
| 6840 | |
| 6841 | Example: |
| 6842 | http-request use-service prometheus-exporter if { path /metrics } |
| 6843 | |
Christopher Faulet | 021a8e4 | 2021-03-29 10:46:38 +0200 | [diff] [blame] | 6844 | http-request wait-for-body time <time> [ at-least <bytes> ] |
| 6845 | [ { if | unless } <condition> ] |
| 6846 | |
| 6847 | This will delay the processing of the request waiting for the payload for at |
| 6848 | most <time> milliseconds. if "at-least" argument is specified, HAProxy stops |
| 6849 | to wait the payload when the first <bytes> bytes are received. 0 means no |
| 6850 | limit, it is the default value. Regardless the "at-least" argument value, |
| 6851 | HAProxy stops to wait if the whole payload is received or if the request |
| 6852 | buffer is full. This action may be used as a replacement to "option |
| 6853 | http-buffer-request". |
| 6854 | |
| 6855 | Arguments : |
| 6856 | |
| 6857 | <time> is mandatory. It is the maximum time to wait for the body. It |
| 6858 | follows the HAProxy time format and is expressed in milliseconds. |
| 6859 | |
| 6860 | <bytes> is optional. It is the minimum payload size to receive to stop to |
Ilya Shipitsin | b2be9a1 | 2021-04-24 13:25:42 +0500 | [diff] [blame] | 6861 | wait. It follows the HAProxy size format and is expressed in |
Christopher Faulet | 021a8e4 | 2021-03-29 10:46:38 +0200 | [diff] [blame] | 6862 | bytes. |
| 6863 | |
| 6864 | Example: |
| 6865 | http-request wait-for-body time 1s at-least 1k if METH_POST |
| 6866 | |
| 6867 | See also : "option http-buffer-request" |
| 6868 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6869 | http-request wait-for-handshake [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6870 | |
Cyril Bonté | c6ad23b | 2018-10-17 00:14:50 +0200 | [diff] [blame] | 6871 | This will delay the processing of the request until the SSL handshake |
| 6872 | happened. This is mostly useful to delay processing early data until we're |
| 6873 | sure they are valid. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6874 | |
Willy Tarreau | ef78104 | 2010-01-27 11:53:01 +0100 | [diff] [blame] | 6875 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6876 | http-response <action> <options...> [ { if | unless } <condition> ] |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 6877 | Access control for Layer 7 responses |
| 6878 | |
| 6879 | May be used in sections: defaults | frontend | listen | backend |
| 6880 | no | yes | yes | yes |
| 6881 | |
| 6882 | The http-response statement defines a set of rules which apply to layer 7 |
| 6883 | processing. The rules are evaluated in their declaration order when they are |
| 6884 | met in a frontend, listen or backend section. Any rule may optionally be |
| 6885 | followed by an ACL-based condition, in which case it will only be evaluated |
| 6886 | if the condition is true. Since these rules apply on responses, the backend |
| 6887 | rules are applied first, followed by the frontend's rules. |
| 6888 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6889 | The first keyword is the rule's action. The supported actions are described |
| 6890 | below. |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 6891 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6892 | There is no limit to the number of http-response statements per instance. |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 6893 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6894 | Example: |
| 6895 | acl key_acl res.hdr(X-Acl-Key) -m found |
Thierry FOURNIER | dad3d1d | 2014-04-22 18:07:25 +0200 | [diff] [blame] | 6896 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6897 | acl myhost hdr(Host) -f myhost.lst |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6898 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6899 | http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl |
| 6900 | http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6901 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6902 | Example: |
| 6903 | acl value res.hdr(X-Value) -m found |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6904 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6905 | use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6906 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6907 | http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value |
| 6908 | http-response del-map(map.lst) %[src] if ! value |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6909 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6910 | See also : "http-request", section 3.4 about userlists and section 7 about |
| 6911 | ACL usage. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6912 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6913 | http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6914 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6915 | This is used to add a new entry into an ACL. The ACL must be loaded from a |
| 6916 | file (even a dummy empty file). The file name of the ACL to be updated is |
| 6917 | passed between parentheses. It takes one argument: <key fmt>, which follows |
| 6918 | log-format rules, to collect content of the new entry. It performs a lookup |
| 6919 | in the ACL before insertion, to avoid duplicated (or more) values. |
| 6920 | This lookup is done by a linear search and can be expensive with large lists! |
| 6921 | It is the equivalent of the "add acl" command from the stats socket, but can |
| 6922 | be triggered by an HTTP response. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6923 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6924 | http-response add-header <name> <fmt> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6925 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6926 | This appends an HTTP header field whose name is specified in <name> and whose |
| 6927 | value is defined by <fmt> which follows the log-format rules (see Custom Log |
| 6928 | Format in section 8.2.4). This may be used to send a cookie to a client for |
| 6929 | example, or to pass some internal information. |
| 6930 | This rule is not final, so it is possible to add other similar rules. |
| 6931 | Note that header addition is performed immediately, so one rule might reuse |
| 6932 | the resulting header from a previous rule. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6933 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6934 | http-response allow [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6935 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6936 | This stops the evaluation of the rules and lets the response pass the check. |
| 6937 | No further "http-response" rules are evaluated for the current section. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6938 | |
Jarno Huuskonen | 251a6b7 | 2019-01-04 14:05:02 +0200 | [diff] [blame] | 6939 | http-response cache-store <name> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6940 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 6941 | See section 6.2 about cache setup. |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6942 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6943 | http-response capture <sample> id <id> [ { if | unless } <condition> ] |
Sasha Pachev | 218f064 | 2014-06-16 12:05:59 -0600 | [diff] [blame] | 6944 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6945 | This captures sample expression <sample> from the response buffer, and |
| 6946 | converts it to a string. The resulting string is stored into the next request |
| 6947 | "capture" slot, so it will possibly appear next to some captured HTTP |
| 6948 | headers. It will then automatically appear in the logs, and it will be |
| 6949 | possible to extract it using sample fetch rules to feed it into headers or |
| 6950 | anything. Please check section 7.3 (Fetching samples) and |
| 6951 | "capture response header" for more information. |
Thierry FOURNIER | 35d70ef | 2015-08-26 16:21:56 +0200 | [diff] [blame] | 6952 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6953 | The keyword "id" is the id of the capture slot which is used for storing the |
| 6954 | string. The capture slot must be defined in an associated frontend. |
| 6955 | This is useful to run captures in backends. The slot id can be declared by a |
| 6956 | previous directive "http-response capture" or with the "declare capture" |
| 6957 | keyword. |
Baptiste Assmann | 19a69b3 | 2020-01-16 14:34:22 +0100 | [diff] [blame] | 6958 | |
| 6959 | When using this action in a backend, double check that the relevant |
| 6960 | frontend(s) have the required capture slots otherwise, this rule will be |
| 6961 | ignored at run time. This can't be detected at configuration parsing time |
| 6962 | due to HAProxy's ability to dynamically resolve backend name at runtime. |
Thierry FOURNIER | 35d70ef | 2015-08-26 16:21:56 +0200 | [diff] [blame] | 6963 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6964 | http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ] |
Thierry FOURNIER | 35d70ef | 2015-08-26 16:21:56 +0200 | [diff] [blame] | 6965 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6966 | This is used to delete an entry from an ACL. The ACL must be loaded from a |
| 6967 | file (even a dummy empty file). The file name of the ACL to be updated is |
| 6968 | passed between parentheses. It takes one argument: <key fmt>, which follows |
| 6969 | log-format rules, to collect content of the entry to delete. |
| 6970 | It is the equivalent of the "del acl" command from the stats socket, but can |
| 6971 | be triggered by an HTTP response. |
Willy Tarreau | f4c43c1 | 2013-06-11 17:01:13 +0200 | [diff] [blame] | 6972 | |
Maciej Zdeb | ebdd4c5 | 2020-11-20 13:58:48 +0000 | [diff] [blame] | 6973 | http-response del-header <name> [ -m <meth> ] [ { if | unless } <condition> ] |
Willy Tarreau | 9a355ec | 2013-06-11 17:45:46 +0200 | [diff] [blame] | 6974 | |
Maciej Zdeb | ebdd4c5 | 2020-11-20 13:58:48 +0000 | [diff] [blame] | 6975 | This removes all HTTP header fields whose name is specified in <name>. <meth> |
| 6976 | is the matching method, applied on the header name. Supported matching methods |
| 6977 | are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub" |
| 6978 | (substring match) and "reg" (regex match). If not specified, exact matching |
| 6979 | method is used. |
Willy Tarreau | 42cf39e | 2013-06-11 18:51:32 +0200 | [diff] [blame] | 6980 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6981 | http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ] |
Willy Tarreau | 51347ed | 2013-06-11 19:34:13 +0200 | [diff] [blame] | 6982 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 6983 | This is used to delete an entry from a MAP. The MAP must be loaded from a |
| 6984 | file (even a dummy empty file). The file name of the MAP to be updated is |
| 6985 | passed between parentheses. It takes one argument: <key fmt>, which follows |
| 6986 | log-format rules, to collect content of the entry to delete. |
| 6987 | It takes one argument: "file name" It is the equivalent of the "del map" |
| 6988 | command from the stats socket, but can be triggered by an HTTP response. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6989 | |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6990 | http-response deny [deny_status <status>] [ { if | unless } <condition> ] |
| 6991 | http-response deny [ { status | deny_status } <code>] [content-type <type>] |
| 6992 | [ { default-errorfiles | errorfile <file> | errorfiles <name> | |
| 6993 | file <file> | lf-file <file> | string <str> | lf-string <fmt> } ] |
| 6994 | [ hdr <name> <fmt> ]* |
| 6995 | [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 6996 | |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 6997 | This stops the evaluation of the rules and immediately rejects the response. |
| 6998 | By default an HTTP 502 error is returned. But the response may be customized |
| 6999 | using same syntax than "http-response return" rules. Thus, see |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 7000 | "http-response return" for details. For compatibility purpose, when no |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 7001 | argument is defined, or only "deny_status", the argument "default-errorfiles" |
| 7002 | is implied. It means "http-response deny [deny_status <status>]" is an alias |
| 7003 | of "http-response deny [status <status>] default-errorfiles". |
Christopher Faulet | 040c8cd | 2020-01-13 16:43:45 +0100 | [diff] [blame] | 7004 | No further "http-response" rules are evaluated. |
Christopher Faulet | 5cb513a | 2020-05-13 17:56:56 +0200 | [diff] [blame] | 7005 | See also "http-response return". |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7006 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7007 | http-response redirect <rule> [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7008 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7009 | This performs an HTTP redirection based on a redirect rule. |
| 7010 | This supports a format string similarly to "http-request redirect" rules, |
| 7011 | with the exception that only the "location" type of redirect is possible on |
| 7012 | the response. See the "redirect" keyword for the rule's syntax. When a |
| 7013 | redirect rule is applied during a response, connections to the server are |
| 7014 | closed so that no data can be forwarded from the server to the client. |
Thierry FOURNIER | e80fada | 2015-05-26 18:06:31 +0200 | [diff] [blame] | 7015 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7016 | http-response replace-header <name> <regex-match> <replace-fmt> |
| 7017 | [ { if | unless } <condition> ] |
Thierry FOURNIER | e80fada | 2015-05-26 18:06:31 +0200 | [diff] [blame] | 7018 | |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 7019 | This works like "http-request replace-header" except that it works on the |
| 7020 | server's response instead of the client's request. |
William Lallemand | 86d0df0 | 2017-11-24 21:36:45 +0100 | [diff] [blame] | 7021 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7022 | Example: |
| 7023 | http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2 |
Willy Tarreau | 51d861a | 2015-05-22 17:30:48 +0200 | [diff] [blame] | 7024 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7025 | # applied to: |
| 7026 | Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 7027 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7028 | # outputs: |
| 7029 | Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 7030 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7031 | # assuming the backend IP is 192.168.1.20. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 7032 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7033 | http-response replace-value <name> <regex-match> <replace-fmt> |
| 7034 | [ { if | unless } <condition> ] |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 7035 | |
Tim Duesterhus | 6bd909b | 2020-01-17 15:53:18 +0100 | [diff] [blame] | 7036 | This works like "http-request replace-value" except that it works on the |
Tim Duesterhus | 2252beb | 2019-10-29 00:05:13 +0100 | [diff] [blame] | 7037 | server's response instead of the client's request. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 7038 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7039 | Example: |
| 7040 | http-response replace-value Cache-control ^public$ private |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 7041 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7042 | # applied to: |
| 7043 | Cache-Control: max-age=3600, public |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 7044 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7045 | # outputs: |
| 7046 | Cache-Control: max-age=3600, private |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 7047 | |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7048 | http-response return [status <code>] [content-type <type>] |
| 7049 | [ { default-errorfiles | errorfile <file> | errorfiles <name> | |
| 7050 | file <file> | lf-file <file> | string <str> | lf-string <fmt> } ] |
Christopher Faulet | 4a2c142 | 2020-01-31 17:36:01 +0100 | [diff] [blame] | 7051 | [ hdr <name> <value> ]* |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7052 | [ { if | unless } <condition> ] |
| 7053 | |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 7054 | This stops the evaluation of the rules and immediately returns a response. The |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7055 | default status code used for the response is 200. It can be optionally |
| 7056 | specified as an arguments to "status". The response content-type may also be |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 7057 | specified as an argument to "content-type". Finally the response itself may |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7058 | be defined. If can be a full HTTP response specifying the errorfile to use, |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 7059 | or the response payload specifying the file or the string to use. These rules |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7060 | are followed to create the response : |
| 7061 | |
| 7062 | * If neither the errorfile nor the payload to use is defined, a dummy |
| 7063 | response is returned. Only the "status" argument is considered. It can be |
| 7064 | any code in the range [200, 599]. The "content-type" argument, if any, is |
| 7065 | ignored. |
| 7066 | |
| 7067 | * If "default-errorfiles" argument is set, the proxy's errorfiles are |
| 7068 | considered. If the "status" argument is defined, it must be one of the |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 7069 | status code handled by haproxy (200, 400, 403, 404, 405, 408, 410, 413, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 7070 | 425, 429, 500, 501, 502, 503, and 504). The "content-type" argument, if |
| 7071 | any, is ignored. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7072 | |
| 7073 | * If a specific errorfile is defined, with an "errorfile" argument, the |
| 7074 | corresponding file, containing a full HTTP response, is returned. Only the |
| 7075 | "status" argument is considered. It must be one of the status code handled |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 7076 | by haproxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 501, |
| 7077 | 502, 503, and 504). The "content-type" argument, if any, is ignored. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7078 | |
| 7079 | * If an http-errors section is defined, with an "errorfiles" argument, the |
| 7080 | corresponding file in the specified http-errors section, containing a full |
| 7081 | HTTP response, is returned. Only the "status" argument is considered. It |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 7082 | must be one of the status code handled by haproxy (200, 400, 403, 404, 405, |
Christopher Faulet | e095f31 | 2020-12-07 11:22:24 +0100 | [diff] [blame] | 7083 | 408, 410, 413, 425, 429, 500, 501, 502, 503, and 504). The "content-type" |
Anthonin Bonnefoy | 85048f8 | 2020-06-22 09:17:01 +0200 | [diff] [blame] | 7084 | argument, if any, is ignored. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7085 | |
| 7086 | * If a "file" or a "lf-file" argument is specified, the file's content is |
| 7087 | used as the response payload. If the file is not empty, its content-type |
| 7088 | must be set as argument to "content-type". Otherwise, any "content-type" |
| 7089 | argument is ignored. With a "lf-file" argument, the file's content is |
| 7090 | evaluated as a log-format string. With a "file" argument, it is considered |
| 7091 | as a raw content. |
| 7092 | |
| 7093 | * If a "string" or "lf-string" argument is specified, the defined string is |
| 7094 | used as the response payload. The content-type must always be set as |
| 7095 | argument to "content-type". With a "lf-string" argument, the string is |
| 7096 | evaluated as a log-format string. With a "string" argument, it is |
| 7097 | considered as a raw string. |
| 7098 | |
Christopher Faulet | 4a2c142 | 2020-01-31 17:36:01 +0100 | [diff] [blame] | 7099 | When the response is not based an errorfile, it is possible to appends HTTP |
| 7100 | header fields to the response using "hdr" arguments. Otherwise, all "hdr" |
| 7101 | arguments are ignored. For each one, the header name is specified in <name> |
| 7102 | and its value is defined by <fmt> which follows the log-format rules. |
| 7103 | |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7104 | Note that the generated response must be smaller than a buffer. And to avoid |
| 7105 | any warning, when an errorfile or a raw file is loaded, the buffer space |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 7106 | reserved to the headers rewriting should also be free. |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7107 | |
| 7108 | No further "http-response" rules are evaluated. |
| 7109 | |
| 7110 | Example: |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 7111 | http-response return errorfile /etc/haproxy/errorfiles/200.http \ |
Christopher Faulet | 24231ab | 2020-01-24 17:44:23 +0100 | [diff] [blame] | 7112 | if { status eq 404 } |
| 7113 | |
| 7114 | http-response return content-type text/plain \ |
| 7115 | string "This is the end !" \ |
| 7116 | if { status eq 500 } |
| 7117 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7118 | http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ] |
| 7119 | http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ] |
Ruoshan Huang | e4edc6b | 2016-07-14 15:07:45 +0800 | [diff] [blame] | 7120 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7121 | This action increments the GPC0 or GPC1 counter according with the sticky |
| 7122 | counter designated by <sc-id>. If an error occurs, this action silently fails |
| 7123 | and the actions evaluation continues. |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 7124 | |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 7125 | http-response sc-set-gpt0(<sc-id>) { <int> | <expr> } |
| 7126 | [ { if | unless } <condition> ] |
Thierry FOURNIER | e0627bd | 2015-08-04 08:20:33 +0200 | [diff] [blame] | 7127 | |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 7128 | This action sets the 32-bit unsigned GPT0 tag according to the sticky counter |
| 7129 | designated by <sc-id> and the value of <int>/<expr>. The expected result is a |
| 7130 | boolean. If an error occurs, this action silently fails and the actions |
| 7131 | evaluation continues. |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 7132 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7133 | http-response send-spoe-group [ { if | unless } <condition> ] |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 7134 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7135 | This action is used to trigger sending of a group of SPOE messages. To do so, |
| 7136 | the SPOE engine used to send messages must be defined, as well as the SPOE |
| 7137 | group to send. Of course, the SPOE engine must refer to an existing SPOE |
| 7138 | filter. If not engine name is provided on the SPOE filter line, the SPOE |
| 7139 | agent name must be used. |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 7140 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7141 | Arguments: |
| 7142 | <engine-name> The SPOE engine name. |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 7143 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7144 | <group-name> The SPOE group name as specified in the engine |
| 7145 | configuration. |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 7146 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7147 | http-response set-header <name> <fmt> [ { if | unless } <condition> ] |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 7148 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7149 | This does the same as "add-header" except that the header name is first |
| 7150 | removed if it existed. This is useful when passing security information to |
| 7151 | the server, where the header must not be manipulated by external users. |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 7152 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7153 | http-response set-log-level <level> [ { if | unless } <condition> ] |
| 7154 | |
| 7155 | This is used to change the log level of the current request when a certain |
| 7156 | condition is met. Valid levels are the 8 syslog levels (see the "log" |
| 7157 | keyword) plus the special level "silent" which disables logging for this |
| 7158 | request. This rule is not final so the last matching rule wins. This rule can |
| 7159 | be useful to disable health checks coming from another equipment. |
| 7160 | |
| 7161 | http-response set-map(<file-name>) <key fmt> <value fmt> |
| 7162 | |
| 7163 | This is used to add a new entry into a MAP. The MAP must be loaded from a |
| 7164 | file (even a dummy empty file). The file name of the MAP to be updated is |
| 7165 | passed between parentheses. It takes 2 arguments: <key fmt>, which follows |
| 7166 | log-format rules, used to collect MAP key, and <value fmt>, which follows |
| 7167 | log-format rules, used to collect content for the new entry. It performs a |
| 7168 | lookup in the MAP before insertion, to avoid duplicated (or more) values. |
| 7169 | This lookup is done by a linear search and can be expensive with large lists! |
| 7170 | It is the equivalent of the "set map" command from the stats socket, but can |
| 7171 | be triggered by an HTTP response. |
| 7172 | |
| 7173 | http-response set-mark <mark> [ { if | unless } <condition> ] |
| 7174 | |
| 7175 | This is used to set the Netfilter MARK on all packets sent to the client to |
| 7176 | the value passed in <mark> on platforms which support it. This value is an |
| 7177 | unsigned 32 bit value which can be matched by netfilter and by the routing |
| 7178 | table. It can be expressed both in decimal or hexadecimal format (prefixed |
| 7179 | by "0x"). This can be useful to force certain packets to take a different |
| 7180 | route (for example a cheaper network path for bulk downloads). This works on |
| 7181 | Linux kernels 2.6.32 and above and requires admin privileges. |
| 7182 | |
| 7183 | http-response set-nice <nice> [ { if | unless } <condition> ] |
| 7184 | |
| 7185 | This sets the "nice" factor of the current request being processed. |
| 7186 | It only has effect against the other requests being processed at the same |
| 7187 | time. The default value is 0, unless altered by the "nice" setting on the |
| 7188 | "bind" line. The accepted range is -1024..1024. The higher the value, the |
| 7189 | nicest the request will be. Lower values will make the request more important |
| 7190 | than other ones. This can be useful to improve the speed of some requests, or |
| 7191 | lower the priority of non-important requests. Using this setting without |
| 7192 | prior experimentation can cause some major slowdown. |
| 7193 | |
| 7194 | http-response set-status <status> [reason <str>] |
| 7195 | [ { if | unless } <condition> ] |
| 7196 | |
| 7197 | This replaces the response status code with <status> which must be an integer |
| 7198 | between 100 and 999. Optionally, a custom reason text can be provided defined |
| 7199 | by <str>, or the default reason for the specified code will be used as a |
| 7200 | fallback. |
Ruoshan Huang | eb5a363 | 2015-12-08 21:00:23 +0800 | [diff] [blame] | 7201 | |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7202 | Example: |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7203 | # return "431 Request Header Fields Too Large" |
| 7204 | http-response set-status 431 |
| 7205 | # return "503 Slow Down", custom reason |
| 7206 | http-response set-status 503 reason "Slow Down". |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7207 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7208 | http-response set-tos <tos> [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7209 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7210 | This is used to set the TOS or DSCP field value of packets sent to the client |
| 7211 | to the value passed in <tos> on platforms which support this. |
| 7212 | This value represents the whole 8 bits of the IP TOS field, and can be |
| 7213 | expressed both in decimal or hexadecimal format (prefixed by "0x"). Note that |
| 7214 | only the 6 higher bits are used in DSCP or TOS, and the two lower bits are |
| 7215 | always 0. This can be used to adjust some routing behavior on border routers |
| 7216 | based on some information from the request. |
| 7217 | |
| 7218 | See RFC 2474, 2597, 3260 and 4594 for more information. |
| 7219 | |
| 7220 | http-response set-var(<var-name>) <expr> [ { if | unless } <condition> ] |
| 7221 | |
| 7222 | This is used to set the contents of a variable. The variable is declared |
| 7223 | inline. |
| 7224 | |
| 7225 | Arguments: |
| 7226 | <var-name> The name of the variable starts with an indication about its |
| 7227 | scope. The scopes allowed are: |
| 7228 | "proc" : the variable is shared with the whole process |
| 7229 | "sess" : the variable is shared with the whole session |
| 7230 | "txn" : the variable is shared with the transaction |
| 7231 | (request and response) |
| 7232 | "req" : the variable is shared only during request |
| 7233 | processing |
| 7234 | "res" : the variable is shared only during response |
| 7235 | processing |
| 7236 | This prefix is followed by a name. The separator is a '.'. |
| 7237 | The name may only contain characters 'a-z', 'A-Z', '0-9', '.' |
| 7238 | and '_'. |
| 7239 | |
| 7240 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 7241 | followed by some converters. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7242 | |
| 7243 | Example: |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7244 | http-response set-var(sess.last_redir) res.hdr(location) |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7245 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7246 | http-response silent-drop [ { if | unless } <condition> ] |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7247 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7248 | This stops the evaluation of the rules and makes the client-facing connection |
| 7249 | suddenly disappear using a system-dependent way that tries to prevent the |
| 7250 | client from being notified. The effect it then that the client still sees an |
| 7251 | established connection while there's none on HAProxy. The purpose is to |
| 7252 | achieve a comparable effect to "tarpit" except that it doesn't use any local |
| 7253 | resource at all on the machine running HAProxy. It can resist much higher |
| 7254 | loads than "tarpit", and slow down stronger attackers. It is important to |
| 7255 | understand the impact of using this mechanism. All stateful equipment placed |
| 7256 | between the client and HAProxy (firewalls, proxies, load balancers) will also |
| 7257 | keep the established connection for a long time and may suffer from this |
| 7258 | action. |
| 7259 | On modern Linux systems running with enough privileges, the TCP_REPAIR socket |
| 7260 | option is used to block the emission of a TCP reset. On other systems, the |
| 7261 | socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first |
| 7262 | router, though it's still delivered to local networks. Do not use it unless |
| 7263 | you fully understand how it works. |
Baptiste Assmann | fabcbe0 | 2014-04-24 22:16:59 +0200 | [diff] [blame] | 7264 | |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 7265 | http-response strict-mode { on | off } |
| 7266 | |
| 7267 | This enables or disables the strict rewriting mode for following rules. It |
| 7268 | does not affect rules declared before it and it is only applicable on rules |
| 7269 | performing a rewrite on the responses. When the strict mode is enabled, any |
| 7270 | rewrite failure triggers an internal error. Otherwise, such errors are |
| 7271 | silently ignored. The purpose of the strict rewriting mode is to make some |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 7272 | rewrites optional while others must be performed to continue the response |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 7273 | processing. |
| 7274 | |
Christopher Faulet | 1aea50e | 2020-01-17 16:03:53 +0100 | [diff] [blame] | 7275 | By default, the strict rewriting mode is enabled. Its value is also reset |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 7276 | when a ruleset evaluation ends. So, for instance, if you change the mode on |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 7277 | the backend, the default mode is restored when HAProxy starts the frontend |
Christopher Faulet | 46f9554 | 2019-12-20 10:07:22 +0100 | [diff] [blame] | 7278 | rules evaluation. |
| 7279 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7280 | http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ] |
| 7281 | http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ] |
| 7282 | http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ] |
Willy Tarreau | e365c0b | 2013-06-11 16:06:12 +0200 | [diff] [blame] | 7283 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 7284 | This enables tracking of sticky counters from current response. Please refer |
| 7285 | to "http-request track-sc" for a complete description. The only difference |
| 7286 | from "http-request track-sc" is the <key> sample expression can only make use |
| 7287 | of samples in response (e.g. res.*, status etc.) and samples below Layer 6 |
| 7288 | (e.g. SSL-related samples, see section 7.3.4). If the sample is not |
| 7289 | supported, haproxy will fail and warn while parsing the config. |
| 7290 | |
| 7291 | http-response unset-var(<var-name>) [ { if | unless } <condition> ] |
| 7292 | |
| 7293 | This is used to unset a variable. See "http-response set-var" for details |
| 7294 | about <var-name>. |
| 7295 | |
| 7296 | Example: |
| 7297 | http-response unset-var(sess.last_redir) |
| 7298 | |
Christopher Faulet | 021a8e4 | 2021-03-29 10:46:38 +0200 | [diff] [blame] | 7299 | http-response wait-for-body time <time> [ at-least <bytes> ] |
| 7300 | [ { if | unless } <condition> ] |
| 7301 | |
| 7302 | This will delay the processing of the response waiting for the payload for at |
| 7303 | most <time> milliseconds. if "at-least" argument is specified, HAProxy stops |
| 7304 | to wait the payload when the first <bytes> bytes are received. 0 means no |
| 7305 | limit, it is the default value. Regardless the "at-least" argument value, |
| 7306 | HAProxy stops to wait if the whole payload is received or if the response |
| 7307 | buffer is full. |
| 7308 | |
| 7309 | Arguments : |
| 7310 | |
| 7311 | <time> is mandatory. It is the maximum time to wait for the body. It |
| 7312 | follows the HAProxy time format and is expressed in milliseconds. |
| 7313 | |
| 7314 | <bytes> is optional. It is the minimum payload size to receive to stop to |
Ilya Shipitsin | b2be9a1 | 2021-04-24 13:25:42 +0500 | [diff] [blame] | 7315 | wait. It follows the HAProxy size format and is expressed in |
Christopher Faulet | 021a8e4 | 2021-03-29 10:46:38 +0200 | [diff] [blame] | 7316 | bytes. |
| 7317 | |
| 7318 | Example: |
| 7319 | http-response wait-for-body time 1s at-least 10k |
Baptiste Assmann | 5ecb77f | 2013-10-06 23:24:13 +0200 | [diff] [blame] | 7320 | |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7321 | http-reuse { never | safe | aggressive | always } |
| 7322 | Declare how idle HTTP connections may be shared between requests |
| 7323 | |
| 7324 | May be used in sections: defaults | frontend | listen | backend |
| 7325 | yes | no | yes | yes |
| 7326 | |
| 7327 | By default, a connection established between haproxy and the backend server |
Olivier Houchard | 86006a5 | 2018-12-14 19:37:49 +0100 | [diff] [blame] | 7328 | which is considered safe for reuse is moved back to the server's idle |
| 7329 | connections pool so that any other request can make use of it. This is the |
| 7330 | "safe" strategy below. |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7331 | |
| 7332 | The argument indicates the desired connection reuse strategy : |
| 7333 | |
Olivier Houchard | 86006a5 | 2018-12-14 19:37:49 +0100 | [diff] [blame] | 7334 | - "never" : idle connections are never shared between sessions. This mode |
| 7335 | may be enforced to cancel a different strategy inherited from |
| 7336 | a defaults section or for troubleshooting. For example, if an |
| 7337 | old bogus application considers that multiple requests over |
| 7338 | the same connection come from the same client and it is not |
| 7339 | possible to fix the application, it may be desirable to |
| 7340 | disable connection sharing in a single backend. An example of |
| 7341 | such an application could be an old haproxy using cookie |
| 7342 | insertion in tunnel mode and not checking any request past the |
| 7343 | first one. |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7344 | |
Olivier Houchard | 86006a5 | 2018-12-14 19:37:49 +0100 | [diff] [blame] | 7345 | - "safe" : this is the default and the recommended strategy. The first |
| 7346 | request of a session is always sent over its own connection, |
| 7347 | and only subsequent requests may be dispatched over other |
| 7348 | existing connections. This ensures that in case the server |
| 7349 | closes the connection when the request is being sent, the |
| 7350 | browser can decide to silently retry it. Since it is exactly |
| 7351 | equivalent to regular keep-alive, there should be no side |
Amaury Denoyelle | 2717965 | 2020-10-14 18:17:12 +0200 | [diff] [blame] | 7352 | effects. There is also a special handling for the connections |
| 7353 | using protocols subject to Head-of-line blocking (backend with |
| 7354 | h2 or fcgi). In this case, when at least one stream is |
| 7355 | processed, the used connection is reserved to handle streams |
| 7356 | of the same session. When no more streams are processed, the |
| 7357 | connection is released and can be reused. |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7358 | |
| 7359 | - "aggressive" : this mode may be useful in webservices environments where |
| 7360 | all servers are not necessarily known and where it would be |
| 7361 | appreciable to deliver most first requests over existing |
| 7362 | connections. In this case, first requests are only delivered |
| 7363 | over existing connections that have been reused at least once, |
| 7364 | proving that the server correctly supports connection reuse. |
| 7365 | It should only be used when it's sure that the client can |
| 7366 | retry a failed request once in a while and where the benefit |
Michael Prokop | 4438c60 | 2019-05-24 10:25:45 +0200 | [diff] [blame] | 7367 | of aggressive connection reuse significantly outweighs the |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7368 | downsides of rare connection failures. |
| 7369 | |
| 7370 | - "always" : this mode is only recommended when the path to the server is |
| 7371 | known for never breaking existing connections quickly after |
| 7372 | releasing them. It allows the first request of a session to be |
| 7373 | sent to an existing connection. This can provide a significant |
| 7374 | performance increase over the "safe" strategy when the backend |
| 7375 | is a cache farm, since such components tend to show a |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7376 | consistent behavior and will benefit from the connection |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7377 | sharing. It is recommended that the "http-keep-alive" timeout |
| 7378 | remains low in this mode so that no dead connections remain |
| 7379 | usable. In most cases, this will lead to the same performance |
| 7380 | gains as "aggressive" but with more risks. It should only be |
| 7381 | used when it improves the situation over "aggressive". |
| 7382 | |
| 7383 | When http connection sharing is enabled, a great care is taken to respect the |
Amaury Denoyelle | d773a4e | 2021-01-29 15:18:49 +0100 | [diff] [blame] | 7384 | connection properties and compatibility. Indeed, some properties are specific |
| 7385 | and it is not possibly to reuse it blindly. Those are the SSL SNI, source |
| 7386 | and destination address and proxy protocol block. A connection is reused only |
| 7387 | if it shares the same set of properties with the request. |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7388 | |
Amaury Denoyelle | d773a4e | 2021-01-29 15:18:49 +0100 | [diff] [blame] | 7389 | Also note that connections with certain bogus authentication schemes (relying |
| 7390 | on the connection) like NTLM are marked private and never shared. |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7391 | |
Lukas Tribus | e8adfeb | 2019-11-06 11:50:25 +0100 | [diff] [blame] | 7392 | A connection pool is involved and configurable with "pool-max-conn". |
Willy Tarreau | 3063195 | 2015-08-06 15:05:24 +0200 | [diff] [blame] | 7393 | |
| 7394 | Note: connection reuse improves the accuracy of the "server maxconn" setting, |
| 7395 | because almost no new connection will be established while idle connections |
| 7396 | remain available. This is particularly true with the "always" strategy. |
| 7397 | |
| 7398 | See also : "option http-keep-alive", "server maxconn" |
| 7399 | |
| 7400 | |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 7401 | http-send-name-header [<header>] |
| 7402 | Add the server name to a request. Use the header string given by <header> |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 7403 | May be used in sections: defaults | frontend | listen | backend |
| 7404 | yes | no | yes | yes |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 7405 | Arguments : |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 7406 | <header> The header string to use to send the server name |
| 7407 | |
Willy Tarreau | 81bef7e | 2019-10-07 14:58:02 +0200 | [diff] [blame] | 7408 | The "http-send-name-header" statement causes the header field named <header> |
| 7409 | to be set to the name of the target server at the moment the request is about |
| 7410 | to be sent on the wire. Any existing occurrences of this header are removed. |
| 7411 | Upon retries and redispatches, the header field is updated to always reflect |
| 7412 | the server being attempted to connect to. Given that this header is modified |
| 7413 | very late in the connection setup, it may have unexpected effects on already |
| 7414 | modified headers. For example using it with transport-level header such as |
| 7415 | connection, content-length, transfer-encoding and so on will likely result in |
| 7416 | invalid requests being sent to the server. Additionally it has been reported |
| 7417 | that this directive is currently being used as a way to overwrite the Host |
| 7418 | header field in outgoing requests; while this trick has been known to work |
| 7419 | as a side effect of the feature for some time, it is not officially supported |
| 7420 | and might possibly not work anymore in a future version depending on the |
| 7421 | technical difficulties this feature induces. A long-term solution instead |
| 7422 | consists in fixing the application which required this trick so that it binds |
| 7423 | to the correct host name. |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 7424 | |
| 7425 | See also : "server" |
| 7426 | |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 7427 | id <value> |
Willy Tarreau | 53fb4ae | 2009-10-04 23:04:08 +0200 | [diff] [blame] | 7428 | Set a persistent ID to a proxy. |
| 7429 | May be used in sections : defaults | frontend | listen | backend |
| 7430 | no | yes | yes | yes |
| 7431 | Arguments : none |
| 7432 | |
| 7433 | Set a persistent ID for the proxy. This ID must be unique and positive. |
| 7434 | An unused ID will automatically be assigned if unset. The first assigned |
| 7435 | 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] | 7436 | |
| 7437 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 7438 | ignore-persist { if | unless } <condition> |
| 7439 | Declare a condition to ignore persistence |
| 7440 | May be used in sections: defaults | frontend | listen | backend |
Cyril Bonté | 4288c5a | 2018-03-12 22:02:59 +0100 | [diff] [blame] | 7441 | no | no | yes | yes |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 7442 | |
| 7443 | By default, when cookie persistence is enabled, every requests containing |
| 7444 | the cookie are unconditionally persistent (assuming the target server is up |
| 7445 | and running). |
| 7446 | |
| 7447 | The "ignore-persist" statement allows one to declare various ACL-based |
| 7448 | conditions which, when met, will cause a request to ignore persistence. |
| 7449 | This is sometimes useful to load balance requests for static files, which |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 7450 | 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] | 7451 | persistence for a specific User-Agent (for example, some web crawler bots). |
| 7452 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 7453 | The persistence is ignored when an "if" condition is met, or unless an |
| 7454 | "unless" condition is met. |
| 7455 | |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 7456 | Example: |
| 7457 | acl url_static path_beg /static /images /img /css |
| 7458 | acl url_static path_end .gif .png .jpg .css .js |
| 7459 | ignore-persist if url_static |
| 7460 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 7461 | See also : "force-persist", "cookie", and section 7 about ACL usage. |
| 7462 | |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7463 | load-server-state-from-file { global | local | none } |
| 7464 | Allow seamless reload of HAProxy |
| 7465 | May be used in sections: defaults | frontend | listen | backend |
| 7466 | yes | no | yes | yes |
| 7467 | |
| 7468 | This directive points HAProxy to a file where server state from previous |
| 7469 | running process has been saved. That way, when starting up, before handling |
| 7470 | traffic, the new process can apply old states to servers exactly has if no |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7471 | reload occurred. The purpose of the "load-server-state-from-file" directive is |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7472 | to tell haproxy which file to use. For now, only 2 arguments to either prevent |
| 7473 | loading state or load states from a file containing all backends and servers. |
| 7474 | The state file can be generated by running the command "show servers state" |
| 7475 | over the stats socket and redirect output. |
| 7476 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7477 | The format of the file is versioned and is very specific. To understand it, |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7478 | please read the documentation of the "show servers state" command (chapter |
Willy Tarreau | 1af20c7 | 2017-06-23 16:01:14 +0200 | [diff] [blame] | 7479 | 9.3 of Management Guide). |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7480 | |
| 7481 | Arguments: |
| 7482 | global load the content of the file pointed by the global directive |
| 7483 | named "server-state-file". |
| 7484 | |
| 7485 | local load the content of the file pointed by the directive |
| 7486 | "server-state-file-name" if set. If not set, then the backend |
| 7487 | name is used as a file name. |
| 7488 | |
| 7489 | none don't load any stat for this backend |
| 7490 | |
| 7491 | Notes: |
Willy Tarreau | e5a6068 | 2016-11-09 14:54:53 +0100 | [diff] [blame] | 7492 | - server's IP address is preserved across reloads by default, but the |
| 7493 | order can be changed thanks to the server's "init-addr" setting. This |
| 7494 | means that an IP address change performed on the CLI at run time will |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7495 | be preserved, and that any change to the local resolver (e.g. /etc/hosts) |
Willy Tarreau | e5a6068 | 2016-11-09 14:54:53 +0100 | [diff] [blame] | 7496 | will possibly not have any effect if the state file is in use. |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7497 | |
| 7498 | - server's weight is applied from previous running process unless it has |
| 7499 | has changed between previous and new configuration files. |
| 7500 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 7501 | Example: Minimal configuration |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7502 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 7503 | global |
| 7504 | stats socket /tmp/socket |
| 7505 | server-state-file /tmp/server_state |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7506 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 7507 | defaults |
| 7508 | load-server-state-from-file global |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7509 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 7510 | backend bk |
| 7511 | server s1 127.0.0.1:22 check weight 11 |
| 7512 | server s2 127.0.0.1:22 check weight 12 |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7513 | |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7514 | |
| 7515 | Then one can run : |
| 7516 | |
| 7517 | socat /tmp/socket - <<< "show servers state" > /tmp/server_state |
| 7518 | |
| 7519 | Content of the file /tmp/server_state would be like this: |
| 7520 | |
| 7521 | 1 |
| 7522 | # <field names skipped for the doc example> |
| 7523 | 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0 |
| 7524 | 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0 |
| 7525 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 7526 | Example: Minimal configuration |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7527 | |
| 7528 | global |
| 7529 | stats socket /tmp/socket |
| 7530 | server-state-base /etc/haproxy/states |
| 7531 | |
| 7532 | defaults |
| 7533 | load-server-state-from-file local |
| 7534 | |
| 7535 | backend bk |
| 7536 | server s1 127.0.0.1:22 check weight 11 |
| 7537 | server s2 127.0.0.1:22 check weight 12 |
| 7538 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 7539 | |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 7540 | Then one can run : |
| 7541 | |
| 7542 | socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk |
| 7543 | |
| 7544 | Content of the file /etc/haproxy/states/bk would be like this: |
| 7545 | |
| 7546 | 1 |
| 7547 | # <field names skipped for the doc example> |
| 7548 | 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0 |
| 7549 | 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0 |
| 7550 | |
| 7551 | See also: "server-state-file", "server-state-file-name", and |
| 7552 | "show servers state" |
| 7553 | |
Cyril Bonté | 0d4bf01 | 2010-04-25 23:21:46 +0200 | [diff] [blame] | 7554 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7555 | log global |
Jan Wagner | 3e67860 | 2020-12-17 22:22:32 +0100 | [diff] [blame] | 7556 | log <address> [len <length>] [format <format>] [sample <ranges>:<sample_size>] |
Frédéric Lécaille | d690dfa | 2019-04-25 10:52:17 +0200 | [diff] [blame] | 7557 | <facility> [<level> [<minlevel>]] |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 7558 | no log |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7559 | Enable per-instance logging of events and traffic. |
| 7560 | May be used in sections : defaults | frontend | listen | backend |
| 7561 | yes | yes | yes | yes |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 7562 | |
| 7563 | Prefix : |
| 7564 | no should be used when the logger list must be flushed. For example, |
| 7565 | if you don't want to inherit from the default logger list. This |
| 7566 | prefix does not allow arguments. |
| 7567 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7568 | Arguments : |
| 7569 | global should be used when the instance's logging parameters are the |
| 7570 | same as the global ones. This is the most common usage. "global" |
| 7571 | replaces <address>, <facility> and <level> with those of the log |
| 7572 | entries found in the "global" section. Only one "log global" |
| 7573 | statement may be used per instance, and this form takes no other |
| 7574 | parameter. |
| 7575 | |
| 7576 | <address> indicates where to send the logs. It takes the same format as |
| 7577 | for the "global" section's logs, and can be one of : |
| 7578 | |
| 7579 | - An IPv4 address optionally followed by a colon (':') and a UDP |
| 7580 | port. If no port is specified, 514 is used by default (the |
| 7581 | standard syslog port). |
| 7582 | |
David du Colombier | 24bb5f5 | 2011-03-17 10:40:23 +0100 | [diff] [blame] | 7583 | - An IPv6 address followed by a colon (':') and optionally a UDP |
| 7584 | port. If no port is specified, 514 is used by default (the |
| 7585 | standard syslog port). |
| 7586 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7587 | - A filesystem path to a UNIX domain socket, keeping in mind |
| 7588 | considerations for chroot (be sure the path is accessible |
| 7589 | inside the chroot) and uid/gid (be sure the path is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7590 | appropriately writable). |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7591 | |
Willy Tarreau | 5a32ecc | 2018-11-12 07:34:59 +0100 | [diff] [blame] | 7592 | - A file descriptor number in the form "fd@<number>", which may |
| 7593 | point to a pipe, terminal, or socket. In this case unbuffered |
| 7594 | logs are used and one writev() call per log is performed. This |
| 7595 | is a bit expensive but acceptable for most workloads. Messages |
| 7596 | sent this way will not be truncated but may be dropped, in |
| 7597 | which case the DroppedLogs counter will be incremented. The |
| 7598 | writev() call is atomic even on pipes for messages up to |
| 7599 | PIPE_BUF size, which POSIX recommends to be at least 512 and |
| 7600 | which is 4096 bytes on most modern operating systems. Any |
| 7601 | larger message may be interleaved with messages from other |
| 7602 | processes. Exceptionally for debugging purposes the file |
| 7603 | descriptor may also be directed to a file, but doing so will |
| 7604 | significantly slow haproxy down as non-blocking calls will be |
| 7605 | ignored. Also there will be no way to purge nor rotate this |
| 7606 | file without restarting the process. Note that the configured |
| 7607 | syslog format is preserved, so the output is suitable for use |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 7608 | with a TCP syslog server. See also the "short" and "raw" |
| 7609 | formats below. |
Willy Tarreau | 5a32ecc | 2018-11-12 07:34:59 +0100 | [diff] [blame] | 7610 | |
| 7611 | - "stdout" / "stderr", which are respectively aliases for "fd@1" |
| 7612 | and "fd@2", see above. |
| 7613 | |
Willy Tarreau | c046d16 | 2019-08-30 15:24:59 +0200 | [diff] [blame] | 7614 | - A ring buffer in the form "ring@<name>", which will correspond |
| 7615 | to an in-memory ring buffer accessible over the CLI using the |
| 7616 | "show events" command, which will also list existing rings and |
| 7617 | their sizes. Such buffers are lost on reload or restart but |
| 7618 | when used as a complement this can help troubleshooting by |
| 7619 | having the logs instantly available. |
| 7620 | |
Emeric Brun | 94aab06 | 2021-04-02 10:41:36 +0200 | [diff] [blame] | 7621 | - An explicit stream address prefix such as "tcp@","tcp6@", |
| 7622 | "tcp4@" or "uxst@" will allocate an implicit ring buffer with |
| 7623 | a stream forward server targeting the given address. |
| 7624 | |
Willy Tarreau | 5a32ecc | 2018-11-12 07:34:59 +0100 | [diff] [blame] | 7625 | You may want to reference some environment variables in the |
| 7626 | address parameter, see section 2.3 about environment variables. |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 7627 | |
Willy Tarreau | 18324f5 | 2014-06-27 18:10:07 +0200 | [diff] [blame] | 7628 | <length> is an optional maximum line length. Log lines larger than this |
| 7629 | value will be truncated before being sent. The reason is that |
| 7630 | syslog servers act differently on log line length. All servers |
| 7631 | support the default value of 1024, but some servers simply drop |
| 7632 | larger lines while others do log them. If a server supports long |
| 7633 | lines, it may make sense to set this value here in order to avoid |
| 7634 | truncating long lines. Similarly, if a server drops long lines, |
| 7635 | it is preferable to truncate them before sending them. Accepted |
| 7636 | values are 80 to 65535 inclusive. The default value of 1024 is |
| 7637 | generally fine for all standard usages. Some specific cases of |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7638 | long captures or JSON-formatted logs may require larger values. |
Willy Tarreau | 18324f5 | 2014-06-27 18:10:07 +0200 | [diff] [blame] | 7639 | |
Frédéric Lécaille | d690dfa | 2019-04-25 10:52:17 +0200 | [diff] [blame] | 7640 | <ranges> A list of comma-separated ranges to identify the logs to sample. |
| 7641 | This is used to balance the load of the logs to send to the log |
| 7642 | server. The limits of the ranges cannot be null. They are numbered |
| 7643 | from 1. The size or period (in number of logs) of the sample must |
| 7644 | be set with <sample_size> parameter. |
| 7645 | |
| 7646 | <sample_size> |
| 7647 | The size of the sample in number of logs to consider when balancing |
| 7648 | their logging loads. It is used to balance the load of the logs to |
| 7649 | send to the syslog server. This size must be greater or equal to the |
| 7650 | maximum of the high limits of the ranges. |
| 7651 | (see also <ranges> parameter). |
| 7652 | |
Willy Tarreau | adb345d | 2018-11-12 07:56:13 +0100 | [diff] [blame] | 7653 | <format> is the log format used when generating syslog messages. It may be |
| 7654 | one of the following : |
| 7655 | |
Emeric Brun | 0237c4e | 2020-11-27 16:24:34 +0100 | [diff] [blame] | 7656 | local Analog to rfc3164 syslog message format except that hostname |
| 7657 | field is stripped. This is the default. |
| 7658 | Note: option "log-send-hostname" switches the default to |
| 7659 | rfc3164. |
| 7660 | |
| 7661 | rfc3164 The RFC3164 syslog message format. |
Willy Tarreau | adb345d | 2018-11-12 07:56:13 +0100 | [diff] [blame] | 7662 | (https://tools.ietf.org/html/rfc3164) |
| 7663 | |
| 7664 | rfc5424 The RFC5424 syslog message format. |
| 7665 | (https://tools.ietf.org/html/rfc5424) |
| 7666 | |
Emeric Brun | 5464885 | 2020-07-06 15:54:06 +0200 | [diff] [blame] | 7667 | priority A message containing only a level plus syslog facility between |
| 7668 | angle brackets such as '<63>', followed by the text. The PID, |
| 7669 | date, time, process name and system name are omitted. This is |
| 7670 | designed to be used with a local log server. |
| 7671 | |
Willy Tarreau | e8746a0 | 2018-11-12 08:45:00 +0100 | [diff] [blame] | 7672 | short A message containing only a level between angle brackets such as |
| 7673 | '<3>', followed by the text. The PID, date, time, process name |
| 7674 | and system name are omitted. This is designed to be used with a |
| 7675 | local log server. This format is compatible with what the |
| 7676 | systemd logger consumes. |
| 7677 | |
Emeric Brun | 5464885 | 2020-07-06 15:54:06 +0200 | [diff] [blame] | 7678 | timed A message containing only a level between angle brackets such as |
| 7679 | '<3>', followed by ISO date and by the text. The PID, process |
| 7680 | name and system name are omitted. This is designed to be |
| 7681 | used with a local log server. |
| 7682 | |
| 7683 | iso A message containing only the ISO date, followed by the text. |
| 7684 | The PID, process name and system name are omitted. This is |
| 7685 | designed to be used with a local log server. |
| 7686 | |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 7687 | raw A message containing only the text. The level, PID, date, time, |
| 7688 | process name and system name are omitted. This is designed to |
| 7689 | be used in containers or during development, where the severity |
| 7690 | only depends on the file descriptor used (stdout/stderr). |
| 7691 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7692 | <facility> must be one of the 24 standard syslog facilities : |
| 7693 | |
Willy Tarreau | e8746a0 | 2018-11-12 08:45:00 +0100 | [diff] [blame] | 7694 | kern user mail daemon auth syslog lpr news |
| 7695 | uucp cron auth2 ftp ntp audit alert cron2 |
| 7696 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 7697 | |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 7698 | Note that the facility is ignored for the "short" and "raw" |
| 7699 | formats, but still required as a positional field. It is |
| 7700 | recommended to use "daemon" in this case to make it clear that |
| 7701 | it's only supposed to be used locally. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7702 | |
| 7703 | <level> is optional and can be specified to filter outgoing messages. By |
| 7704 | default, all messages are sent. If a level is specified, only |
| 7705 | messages with a severity at least as important as this level |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 7706 | will be sent. An optional minimum level can be specified. If it |
| 7707 | is set, logs emitted with a more severe level than this one will |
| 7708 | be capped to this level. This is used to avoid sending "emerg" |
| 7709 | messages on all terminals on some default syslog configurations. |
| 7710 | Eight levels are known : |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7711 | |
| 7712 | emerg alert crit err warning notice info debug |
| 7713 | |
William Lallemand | 0f99e34 | 2011-10-12 17:50:54 +0200 | [diff] [blame] | 7714 | It is important to keep in mind that it is the frontend which decides what to |
| 7715 | log from a connection, and that in case of content switching, the log entries |
| 7716 | from the backend will be ignored. Connections are logged at level "info". |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 7717 | |
| 7718 | However, backend log declaration define how and where servers status changes |
| 7719 | will be logged. Level "notice" will be used to indicate a server going up, |
| 7720 | "warning" will be used for termination signals and definitive service |
| 7721 | termination, and "alert" will be used for when a server goes down. |
| 7722 | |
| 7723 | Note : According to RFC3164, messages are truncated to 1024 bytes before |
| 7724 | being emitted. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7725 | |
| 7726 | Example : |
| 7727 | log global |
Willy Tarreau | c1b0645 | 2018-11-12 11:57:56 +0100 | [diff] [blame] | 7728 | log stdout format short daemon # send log to systemd |
| 7729 | log stdout format raw daemon # send everything to stdout |
| 7730 | log stderr format raw daemon notice # send important events to stderr |
Willy Tarreau | f7edefa | 2009-05-10 17:20:05 +0200 | [diff] [blame] | 7731 | log 127.0.0.1:514 local0 notice # only send important events |
Emeric Brun | 94aab06 | 2021-04-02 10:41:36 +0200 | [diff] [blame] | 7732 | log tcp@127.0.0.1:514 local0 notice notice # same but limit output |
| 7733 | # level and send in tcp |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 7734 | log "${LOCAL_SYSLOG}:514" local0 notice # send to local server |
Willy Tarreau | dad36a3 | 2013-03-11 01:20:04 +0100 | [diff] [blame] | 7735 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7736 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 7737 | log-format <string> |
Willy Tarreau | fb4e7ea | 2015-01-07 14:55:17 +0100 | [diff] [blame] | 7738 | Specifies the log format string to use for traffic logs |
| 7739 | May be used in sections: defaults | frontend | listen | backend |
| 7740 | yes | yes | yes | no |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 7741 | |
Willy Tarreau | fb4e7ea | 2015-01-07 14:55:17 +0100 | [diff] [blame] | 7742 | This directive specifies the log format string that will be used for all logs |
| 7743 | resulting from traffic passing through the frontend using this line. If the |
| 7744 | directive is used in a defaults section, all subsequent frontends will use |
| 7745 | the same log format. Please see section 8.2.4 which covers the log format |
| 7746 | string in depth. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 7747 | |
Guillaume de Lafond | 29f4560 | 2017-03-31 19:52:15 +0200 | [diff] [blame] | 7748 | "log-format" directive overrides previous "option tcplog", "log-format" and |
| 7749 | "option httplog" directives. |
| 7750 | |
Dragan Dosen | 7ad3154 | 2015-09-28 17:16:47 +0200 | [diff] [blame] | 7751 | log-format-sd <string> |
| 7752 | Specifies the RFC5424 structured-data log format string |
| 7753 | May be used in sections: defaults | frontend | listen | backend |
| 7754 | yes | yes | yes | no |
| 7755 | |
| 7756 | This directive specifies the RFC5424 structured-data log format string that |
| 7757 | will be used for all logs resulting from traffic passing through the frontend |
| 7758 | using this line. If the directive is used in a defaults section, all |
| 7759 | subsequent frontends will use the same log format. Please see section 8.2.4 |
| 7760 | which covers the log format string in depth. |
| 7761 | |
| 7762 | See https://tools.ietf.org/html/rfc5424#section-6.3 for more information |
| 7763 | about the RFC5424 structured-data part. |
| 7764 | |
| 7765 | Note : This log format string will be used only for loggers that have set |
| 7766 | log format to "rfc5424". |
| 7767 | |
| 7768 | Example : |
| 7769 | log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"] |
| 7770 | |
| 7771 | |
Willy Tarreau | 094af4e | 2015-01-07 15:03:42 +0100 | [diff] [blame] | 7772 | log-tag <string> |
| 7773 | Specifies the log tag to use for all outgoing logs |
| 7774 | May be used in sections: defaults | frontend | listen | backend |
| 7775 | yes | yes | yes | yes |
| 7776 | |
| 7777 | Sets the tag field in the syslog header to this string. It defaults to the |
| 7778 | log-tag set in the global section, otherwise the program name as launched |
| 7779 | from the command line, which usually is "haproxy". Sometimes it can be useful |
| 7780 | to differentiate between multiple processes running on the same host, or to |
| 7781 | differentiate customer instances running in the same process. In the backend, |
| 7782 | logs about servers up/down will use this tag. As a hint, it can be convenient |
| 7783 | to set a log-tag related to a hosted customer in a defaults section then put |
| 7784 | all the frontends and backends for that customer, then start another customer |
| 7785 | in a new defaults section. See also the global "log-tag" directive. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7786 | |
Willy Tarreau | c35362a | 2014-04-25 13:58:37 +0200 | [diff] [blame] | 7787 | max-keep-alive-queue <value> |
| 7788 | Set the maximum server queue size for maintaining keep-alive connections |
| 7789 | May be used in sections: defaults | frontend | listen | backend |
| 7790 | yes | no | yes | yes |
| 7791 | |
| 7792 | HTTP keep-alive tries to reuse the same server connection whenever possible, |
| 7793 | but sometimes it can be counter-productive, for example if a server has a lot |
| 7794 | of connections while other ones are idle. This is especially true for static |
| 7795 | servers. |
| 7796 | |
| 7797 | The purpose of this setting is to set a threshold on the number of queued |
| 7798 | connections at which haproxy stops trying to reuse the same server and prefers |
| 7799 | to find another one. The default value, -1, means there is no limit. A value |
| 7800 | of zero means that keep-alive requests will never be queued. For very close |
| 7801 | servers which can be reached with a low latency and which are not sensible to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7802 | breaking keep-alive, a low value is recommended (e.g. local static server can |
Willy Tarreau | c35362a | 2014-04-25 13:58:37 +0200 | [diff] [blame] | 7803 | use a value of 10 or less). For remote servers suffering from a high latency, |
| 7804 | higher values might be needed to cover for the latency and/or the cost of |
| 7805 | picking a different server. |
| 7806 | |
| 7807 | Note that this has no impact on responses which are maintained to the same |
| 7808 | server consecutively to a 401 response. They will still go to the same server |
| 7809 | even if they have to be queued. |
| 7810 | |
| 7811 | See also : "option http-server-close", "option prefer-last-server", server |
| 7812 | "maxconn" and cookie persistence. |
| 7813 | |
Olivier Houchard | a4d4fdf | 2018-12-14 19:27:06 +0100 | [diff] [blame] | 7814 | max-session-srv-conns <nb> |
| 7815 | Set the maximum number of outgoing connections we can keep idling for a given |
| 7816 | client session. The default is 5 (it precisely equals MAX_SRV_LIST which is |
| 7817 | defined at build time). |
Willy Tarreau | c35362a | 2014-04-25 13:58:37 +0200 | [diff] [blame] | 7818 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7819 | maxconn <conns> |
| 7820 | Fix the maximum number of concurrent connections on a frontend |
| 7821 | May be used in sections : defaults | frontend | listen | backend |
| 7822 | yes | yes | yes | no |
| 7823 | Arguments : |
| 7824 | <conns> is the maximum number of concurrent connections the frontend will |
| 7825 | accept to serve. Excess connections will be queued by the system |
| 7826 | in the socket's listen queue and will be served once a connection |
| 7827 | closes. |
| 7828 | |
| 7829 | If the system supports it, it can be useful on big sites to raise this limit |
| 7830 | very high so that haproxy manages connection queues, instead of leaving the |
| 7831 | clients with unanswered connection attempts. This value should not exceed the |
| 7832 | global maxconn. Also, keep in mind that a connection contains two buffers |
Baptiste Assmann | 79fb45d | 2016-03-06 23:34:31 +0100 | [diff] [blame] | 7833 | of tune.bufsize (16kB by default) each, as well as some other data resulting |
| 7834 | in about 33 kB of RAM being consumed per established connection. That means |
| 7835 | that a medium system equipped with 1GB of RAM can withstand around |
| 7836 | 20000-25000 concurrent connections if properly tuned. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7837 | |
| 7838 | Also, when <conns> is set to large values, it is possible that the servers |
| 7839 | are not sized to accept such loads, and for this reason it is generally wise |
| 7840 | to assign them some reasonable connection limits. |
| 7841 | |
Willy Tarreau | c8d5b95 | 2019-02-27 17:25:52 +0100 | [diff] [blame] | 7842 | When this value is set to zero, which is the default, the global "maxconn" |
| 7843 | value is used. |
Vincent Bernat | 6341be5 | 2012-06-27 17:18:30 +0200 | [diff] [blame] | 7844 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7845 | See also : "server", global section's "maxconn", "fullconn" |
| 7846 | |
| 7847 | |
Willy Tarreau | 77e0dae | 2020-10-14 15:44:27 +0200 | [diff] [blame] | 7848 | mode { tcp|http } |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7849 | Set the running mode or protocol of the instance |
| 7850 | May be used in sections : defaults | frontend | listen | backend |
| 7851 | yes | yes | yes | yes |
| 7852 | Arguments : |
| 7853 | tcp The instance will work in pure TCP mode. A full-duplex connection |
| 7854 | will be established between clients and servers, and no layer 7 |
| 7855 | examination will be performed. This is the default mode. It |
| 7856 | should be used for SSL, SSH, SMTP, ... |
| 7857 | |
| 7858 | http The instance will work in HTTP mode. The client request will be |
| 7859 | analyzed in depth before connecting to any server. Any request |
| 7860 | which is not RFC-compliant will be rejected. Layer 7 filtering, |
| 7861 | processing and switching will be possible. This is the mode which |
| 7862 | brings HAProxy most of its value. |
| 7863 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7864 | When doing content switching, it is mandatory that the frontend and the |
| 7865 | backend are in the same mode (generally HTTP), otherwise the configuration |
| 7866 | will be refused. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7867 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 7868 | Example : |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7869 | defaults http_instances |
| 7870 | mode http |
| 7871 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7872 | |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 7873 | monitor fail { if | unless } <condition> |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7874 | Add a condition to report a failure to a monitor HTTP request. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7875 | May be used in sections : defaults | frontend | listen | backend |
| 7876 | no | yes | yes | no |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7877 | Arguments : |
| 7878 | if <cond> the monitor request will fail if the condition is satisfied, |
| 7879 | and will succeed otherwise. The condition should describe a |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 7880 | combined test which must induce a failure if all conditions |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7881 | are met, for instance a low number of servers both in a |
| 7882 | backend and its backup. |
| 7883 | |
| 7884 | unless <cond> the monitor request will succeed only if the condition is |
| 7885 | satisfied, and will fail otherwise. Such a condition may be |
| 7886 | based on a test on the presence of a minimum number of active |
| 7887 | servers in a list of backends. |
| 7888 | |
| 7889 | This statement adds a condition which can force the response to a monitor |
| 7890 | request to report a failure. By default, when an external component queries |
| 7891 | the URI dedicated to monitoring, a 200 response is returned. When one of the |
| 7892 | conditions above is met, haproxy will return 503 instead of 200. This is |
| 7893 | very useful to report a site failure to an external component which may base |
| 7894 | routing advertisements between multiple sites on the availability reported by |
| 7895 | 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] | 7896 | criterion. Note that "monitor fail" only works in HTTP mode. Both status |
| 7897 | messages may be tweaked using "errorfile" or "errorloc" if needed. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7898 | |
| 7899 | Example: |
| 7900 | frontend www |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7901 | mode http |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7902 | acl site_dead nbsrv(dynamic) lt 2 |
| 7903 | acl site_dead nbsrv(static) lt 2 |
| 7904 | monitor-uri /site_alive |
| 7905 | monitor fail if site_dead |
| 7906 | |
Willy Tarreau | 9e9919d | 2020-10-14 15:55:23 +0200 | [diff] [blame] | 7907 | See also : "monitor-uri", "errorfile", "errorloc" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7908 | |
| 7909 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7910 | monitor-uri <uri> |
| 7911 | Intercept a URI used by external components' monitor requests |
| 7912 | May be used in sections : defaults | frontend | listen | backend |
| 7913 | yes | yes | yes | no |
| 7914 | Arguments : |
| 7915 | <uri> is the exact URI which we want to intercept to return HAProxy's |
| 7916 | health status instead of forwarding the request. |
| 7917 | |
| 7918 | When an HTTP request referencing <uri> will be received on a frontend, |
| 7919 | HAProxy will not forward it nor log it, but instead will return either |
| 7920 | "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure |
| 7921 | conditions defined with "monitor fail". This is normally enough for any |
| 7922 | front-end HTTP probe to detect that the service is UP and running without |
| 7923 | forwarding the request to a backend server. Note that the HTTP method, the |
| 7924 | version and all headers are ignored, but the request must at least be valid |
| 7925 | at the HTTP level. This keyword may only be used with an HTTP-mode frontend. |
| 7926 | |
Willy Tarreau | 721d8e0 | 2017-12-01 18:25:08 +0100 | [diff] [blame] | 7927 | Monitor requests are processed very early, just after the request is parsed |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 7928 | and even before any "http-request". The only rulesets applied before are the |
| 7929 | tcp-request ones. They cannot be logged either, and it is the intended |
| 7930 | purpose. They are only used to report HAProxy's health to an upper component, |
| 7931 | nothing more. However, it is possible to add any number of conditions using |
| 7932 | "monitor fail" and ACLs so that the result can be adjusted to whatever check |
| 7933 | can be imagined (most often the number of available servers in a backend). |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7934 | |
Christopher Faulet | 6072beb | 2020-02-18 15:34:58 +0100 | [diff] [blame] | 7935 | Note: if <uri> starts by a slash ('/'), the matching is performed against the |
| 7936 | request's path instead of the request's uri. It is a workaround to let |
| 7937 | the HTTP/2 requests match the monitor-uri. Indeed, in HTTP/2, clients |
| 7938 | are encouraged to send absolute URIs only. |
| 7939 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7940 | Example : |
| 7941 | # Use /haproxy_test to report haproxy's status |
| 7942 | frontend www |
| 7943 | mode http |
| 7944 | monitor-uri /haproxy_test |
| 7945 | |
Willy Tarreau | 9e9919d | 2020-10-14 15:55:23 +0200 | [diff] [blame] | 7946 | See also : "monitor fail" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 7947 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 7948 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 7949 | option abortonclose |
| 7950 | no option abortonclose |
| 7951 | Enable or disable early dropping of aborted requests pending in queues. |
| 7952 | May be used in sections : defaults | frontend | listen | backend |
| 7953 | yes | no | yes | yes |
| 7954 | Arguments : none |
| 7955 | |
| 7956 | In presence of very high loads, the servers will take some time to respond. |
| 7957 | The per-instance connection queue will inflate, and the response time will |
| 7958 | increase respective to the size of the queue times the average per-session |
| 7959 | 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] | 7960 | 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] | 7961 | the queue, and slowing down other users, and the servers as well, because the |
| 7962 | request will eventually be served, then aborted at the first error |
| 7963 | encountered while delivering the response. |
| 7964 | |
| 7965 | As there is no way to distinguish between a full STOP and a simple output |
| 7966 | close on the client side, HTTP agents should be conservative and consider |
| 7967 | that the client might only have closed its output channel while waiting for |
| 7968 | the response. However, this introduces risks of congestion when lots of users |
| 7969 | do the same, and is completely useless nowadays because probably no client at |
| 7970 | all will close the session while waiting for the response. Some HTTP agents |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7971 | support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 7972 | hardware-based load balancers). So the probability for a closed input channel |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 7973 | 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] | 7974 | of being the single component to break rare but valid traffic is extremely |
| 7975 | low, which adds to the temptation to be able to abort a session early while |
| 7976 | still not served and not pollute the servers. |
| 7977 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 7978 | In HAProxy, the user can choose the desired behavior using the option |
| 7979 | "abortonclose". By default (without the option) the behavior is HTTP |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 7980 | compliant and aborted requests will be served. But when the option is |
| 7981 | specified, a session with an incoming channel closed will be aborted while |
| 7982 | it is still possible, either pending in the queue for a connection slot, or |
| 7983 | during the connection establishment if the server has not yet acknowledged |
| 7984 | the connection request. This considerably reduces the queue size and the load |
| 7985 | 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] | 7986 | reduces the response time for other users. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 7987 | |
| 7988 | If this option has been enabled in a "defaults" section, it can be disabled |
| 7989 | in a specific instance by prepending the "no" keyword before it. |
| 7990 | |
| 7991 | See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters |
| 7992 | |
| 7993 | |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 7994 | option accept-invalid-http-request |
| 7995 | no option accept-invalid-http-request |
| 7996 | Enable or disable relaxing of HTTP request parsing |
| 7997 | May be used in sections : defaults | frontend | listen | backend |
| 7998 | yes | yes | yes | no |
| 7999 | Arguments : none |
| 8000 | |
Willy Tarreau | 91852eb | 2015-05-01 13:26:00 +0200 | [diff] [blame] | 8001 | By default, HAProxy complies with RFC7230 in terms of message parsing. This |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 8002 | means that invalid characters in header names are not permitted and cause an |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8003 | error to be returned to the client. This is the desired behavior as such |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 8004 | forbidden characters are essentially used to build attacks exploiting server |
| 8005 | weaknesses, and bypass security filtering. Sometimes, a buggy browser or |
| 8006 | server will emit invalid header names for whatever reason (configuration, |
| 8007 | implementation) and the issue will not be immediately fixed. In such a case, |
| 8008 | 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] | 8009 | even if that does not make sense, by specifying this option. Similarly, the |
| 8010 | list of characters allowed to appear in a URI is well defined by RFC3986, and |
| 8011 | chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96 |
| 8012 | ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8013 | not allowed at all. HAProxy always blocks a number of them (0..32, 127). The |
Willy Tarreau | 91852eb | 2015-05-01 13:26:00 +0200 | [diff] [blame] | 8014 | remaining ones are blocked by default unless this option is enabled. This |
Willy Tarreau | 1331766 | 2015-05-01 13:47:08 +0200 | [diff] [blame] | 8015 | option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests |
| 8016 | to pass through (no version specified) and multiple digits for both the major |
| 8017 | and the minor version. |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 8018 | |
| 8019 | This option should never be enabled by default as it hides application bugs |
| 8020 | and open security breaches. It should only be deployed after a problem has |
| 8021 | been confirmed. |
| 8022 | |
| 8023 | When this option is enabled, erroneous header names will still be accepted in |
| 8024 | 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] | 8025 | analysis using the "show errors" request on the UNIX stats socket. Similarly, |
| 8026 | 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] | 8027 | also helps confirming that the issue has been solved. |
| 8028 | |
| 8029 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8030 | in a specific instance by prepending the "no" keyword before it. |
| 8031 | |
| 8032 | See also : "option accept-invalid-http-response" and "show errors" on the |
| 8033 | stats socket. |
| 8034 | |
| 8035 | |
| 8036 | option accept-invalid-http-response |
| 8037 | no option accept-invalid-http-response |
| 8038 | Enable or disable relaxing of HTTP response parsing |
| 8039 | May be used in sections : defaults | frontend | listen | backend |
| 8040 | yes | no | yes | yes |
| 8041 | Arguments : none |
| 8042 | |
Willy Tarreau | 91852eb | 2015-05-01 13:26:00 +0200 | [diff] [blame] | 8043 | By default, HAProxy complies with RFC7230 in terms of message parsing. This |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 8044 | means that invalid characters in header names are not permitted and cause an |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8045 | error to be returned to the client. This is the desired behavior as such |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 8046 | forbidden characters are essentially used to build attacks exploiting server |
| 8047 | weaknesses, and bypass security filtering. Sometimes, a buggy browser or |
| 8048 | server will emit invalid header names for whatever reason (configuration, |
| 8049 | implementation) and the issue will not be immediately fixed. In such a case, |
| 8050 | it is possible to relax HAProxy's header name parser to accept any character |
Willy Tarreau | 91852eb | 2015-05-01 13:26:00 +0200 | [diff] [blame] | 8051 | even if that does not make sense, by specifying this option. This option also |
| 8052 | relaxes the test on the HTTP version format, it allows multiple digits for |
| 8053 | both the major and the minor version. |
Willy Tarreau | 4076a15 | 2009-04-02 15:18:36 +0200 | [diff] [blame] | 8054 | |
| 8055 | This option should never be enabled by default as it hides application bugs |
| 8056 | and open security breaches. It should only be deployed after a problem has |
| 8057 | been confirmed. |
| 8058 | |
| 8059 | When this option is enabled, erroneous header names will still be accepted in |
| 8060 | responses, but the complete response will be captured in order to permit |
| 8061 | later analysis using the "show errors" request on the UNIX stats socket. |
| 8062 | Doing this also helps confirming that the issue has been solved. |
| 8063 | |
| 8064 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8065 | in a specific instance by prepending the "no" keyword before it. |
| 8066 | |
| 8067 | See also : "option accept-invalid-http-request" and "show errors" on the |
| 8068 | stats socket. |
| 8069 | |
| 8070 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8071 | option allbackups |
| 8072 | no option allbackups |
| 8073 | Use either all backup servers at a time or only the first one |
| 8074 | May be used in sections : defaults | frontend | listen | backend |
| 8075 | yes | no | yes | yes |
| 8076 | Arguments : none |
| 8077 | |
| 8078 | By default, the first operational backup server gets all traffic when normal |
| 8079 | servers are all down. Sometimes, it may be preferred to use multiple backups |
| 8080 | at once, because one will not be enough. When "option allbackups" is enabled, |
| 8081 | the load balancing will be performed among all backup servers when all normal |
| 8082 | ones are unavailable. The same load balancing algorithm will be used and the |
| 8083 | servers' weights will be respected. Thus, there will not be any priority |
| 8084 | order between the backup servers anymore. |
| 8085 | |
| 8086 | This option is mostly used with static server farms dedicated to return a |
| 8087 | "sorry" page when an application is completely offline. |
| 8088 | |
| 8089 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8090 | in a specific instance by prepending the "no" keyword before it. |
| 8091 | |
| 8092 | |
| 8093 | option checkcache |
| 8094 | no option checkcache |
Godbach | 7056a35 | 2013-12-11 20:01:07 +0800 | [diff] [blame] | 8095 | Analyze all server responses and block responses with cacheable cookies |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8096 | May be used in sections : defaults | frontend | listen | backend |
| 8097 | yes | no | yes | yes |
| 8098 | Arguments : none |
| 8099 | |
| 8100 | Some high-level frameworks set application cookies everywhere and do not |
| 8101 | 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] | 8102 | 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] | 8103 | high risk of session crossing or stealing between users traversing the same |
| 8104 | 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] | 8105 | some sensitive session information go in the wild. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8106 | |
| 8107 | The option "checkcache" enables deep inspection of all server responses for |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 8108 | strict compliance with HTTP specification in terms of cacheability. It |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 8109 | carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8110 | response to check if there's a risk of caching a cookie on a client-side |
| 8111 | 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] | 8112 | to the client are : |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8113 | - all those without "Set-Cookie" header; |
Willy Tarreau | c55ddce | 2017-12-21 11:41:38 +0100 | [diff] [blame] | 8114 | - all those with a return code other than 200, 203, 204, 206, 300, 301, |
| 8115 | 404, 405, 410, 414, 501, provided that the server has not set a |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8116 | "Cache-control: public" header field; |
Willy Tarreau | 24ea0bc | 2017-12-21 11:32:55 +0100 | [diff] [blame] | 8117 | - all those that result from a request using a method other than GET, HEAD, |
| 8118 | OPTIONS, TRACE, provided that the server has not set a 'Cache-Control: |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8119 | public' header field; |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8120 | - those with a 'Pragma: no-cache' header |
| 8121 | - those with a 'Cache-control: private' header |
| 8122 | - those with a 'Cache-control: no-store' header |
| 8123 | - those with a 'Cache-control: max-age=0' header |
| 8124 | - those with a 'Cache-control: s-maxage=0' header |
| 8125 | - those with a 'Cache-control: no-cache' header |
| 8126 | - those with a 'Cache-control: no-cache="set-cookie"' header |
| 8127 | - those with a 'Cache-control: no-cache="set-cookie,' header |
| 8128 | (allowing other fields after set-cookie) |
| 8129 | |
| 8130 | If a response doesn't respect these requirements, then it will be blocked |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 8131 | just as if it was from an "http-response deny" rule, with an "HTTP 502 bad |
| 8132 | gateway". The session state shows "PH--" meaning that the proxy blocked the |
| 8133 | response during headers processing. Additionally, an alert will be sent in |
| 8134 | the logs so that admins are informed that there's something to be fixed. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8135 | |
| 8136 | Due to the high impact on the application, the application should be tested |
| 8137 | 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] | 8138 | good practice to always activate it during tests, even if it is not used in |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8139 | production, as it will report potentially dangerous application behaviors. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8140 | |
| 8141 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8142 | in a specific instance by prepending the "no" keyword before it. |
| 8143 | |
| 8144 | |
| 8145 | option clitcpka |
| 8146 | no option clitcpka |
| 8147 | Enable or disable the sending of TCP keepalive packets on the client side |
| 8148 | May be used in sections : defaults | frontend | listen | backend |
| 8149 | yes | yes | yes | no |
| 8150 | Arguments : none |
| 8151 | |
| 8152 | When there is a firewall or any session-aware component between a client and |
| 8153 | a server, and when the protocol involves very long sessions with long idle |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8154 | periods (e.g. remote desktops), there is a risk that one of the intermediate |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8155 | components decides to expire a session which has remained idle for too long. |
| 8156 | |
| 8157 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 8158 | to the other end of the connection, leaving it active. The delay between |
| 8159 | keep-alive probes is controlled by the system only and depends both on the |
| 8160 | operating system and its tuning parameters. |
| 8161 | |
| 8162 | It is important to understand that keep-alive packets are neither emitted nor |
| 8163 | received at the application level. It is only the network stacks which sees |
| 8164 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 8165 | to maintain its connection alive, those keep-alive packets will not be |
| 8166 | forwarded to the other side of the proxy. |
| 8167 | |
| 8168 | Please note that this has nothing to do with HTTP keep-alive. |
| 8169 | |
| 8170 | Using option "clitcpka" enables the emission of TCP keep-alive probes on the |
| 8171 | client side of a connection, which should help when session expirations are |
| 8172 | noticed between HAProxy and a client. |
| 8173 | |
| 8174 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8175 | in a specific instance by prepending the "no" keyword before it. |
| 8176 | |
| 8177 | See also : "option srvtcpka", "option tcpka" |
| 8178 | |
| 8179 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 8180 | option contstats |
| 8181 | Enable continuous traffic statistics updates |
| 8182 | May be used in sections : defaults | frontend | listen | backend |
| 8183 | yes | yes | yes | no |
| 8184 | Arguments : none |
| 8185 | |
| 8186 | By default, counters used for statistics calculation are incremented |
| 8187 | only when a session finishes. It works quite well when serving small |
| 8188 | objects, but with big ones (for example large images or archives) or |
| 8189 | with A/V streaming, a graph generated from haproxy counters looks like |
Willy Tarreau | def0d22 | 2016-11-08 22:03:00 +0100 | [diff] [blame] | 8190 | a hedgehog. With this option enabled counters get incremented frequently |
| 8191 | along the session, typically every 5 seconds, which is often enough to |
| 8192 | produce clean graphs. Recounting touches a hotpath directly so it is not |
| 8193 | not enabled by default, as it can cause a lot of wakeups for very large |
| 8194 | session counts and cause a small performance drop. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 8195 | |
Christopher Faulet | 89aed32 | 2020-06-02 17:33:56 +0200 | [diff] [blame] | 8196 | option disable-h2-upgrade |
| 8197 | no option disable-h2-upgrade |
| 8198 | Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client |
| 8199 | connection. |
| 8200 | May be used in sections : defaults | frontend | listen | backend |
| 8201 | yes | yes | yes | no |
| 8202 | Arguments : none |
| 8203 | |
| 8204 | By default, HAProxy is able to implicitly upgrade an HTTP/1.x client |
| 8205 | connection to an HTTP/2 connection if the first request it receives from a |
| 8206 | given HTTP connection matches the HTTP/2 connection preface (i.e. the string |
| 8207 | "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"). This way, it is possible to support |
Christopher Faulet | 982e17d | 2021-03-26 14:44:18 +0100 | [diff] [blame] | 8208 | HTTP/1.x and HTTP/2 clients on a non-SSL connections. This option must be |
| 8209 | used to disable the implicit upgrade. Note this implicit upgrade is only |
| 8210 | supported for HTTP proxies, thus this option too. Note also it is possible to |
| 8211 | force the HTTP/2 on clear connections by specifying "proto h2" on the bind |
| 8212 | line. Finally, this option is applied on all bind lines. To disable implicit |
| 8213 | HTTP/2 upgrades for a specific bind line, it is possible to use "proto h1". |
Christopher Faulet | 89aed32 | 2020-06-02 17:33:56 +0200 | [diff] [blame] | 8214 | |
| 8215 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8216 | in a specific instance by prepending the "no" keyword before it. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 8217 | |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 8218 | option dontlog-normal |
| 8219 | no option dontlog-normal |
| 8220 | Enable or disable logging of normal, successful connections |
| 8221 | May be used in sections : defaults | frontend | listen | backend |
| 8222 | yes | yes | yes | no |
| 8223 | Arguments : none |
| 8224 | |
| 8225 | There are large sites dealing with several thousand connections per second |
| 8226 | and for which logging is a major pain. Some of them are even forced to turn |
| 8227 | logs off and cannot debug production issues. Setting this option ensures that |
| 8228 | normal connections, those which experience no error, no timeout, no retry nor |
| 8229 | redispatch, will not be logged. This leaves disk space for anomalies. In HTTP |
| 8230 | mode, the response status code is checked and return codes 5xx will still be |
| 8231 | logged. |
| 8232 | |
| 8233 | It is strongly discouraged to use this option as most of the time, the key to |
| 8234 | complex issues is in the normal logs which will not be logged here. If you |
| 8235 | need to separate logs, see the "log-separate-errors" option instead. |
| 8236 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8237 | See also : "log", "dontlognull", "log-separate-errors" and section 8 about |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 8238 | logging. |
| 8239 | |
| 8240 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8241 | option dontlognull |
| 8242 | no option dontlognull |
| 8243 | Enable or disable logging of null connections |
| 8244 | May be used in sections : defaults | frontend | listen | backend |
| 8245 | yes | yes | yes | no |
| 8246 | Arguments : none |
| 8247 | |
| 8248 | In certain environments, there are components which will regularly connect to |
| 8249 | various systems to ensure that they are still alive. It can be the case from |
| 8250 | another load balancer as well as from monitoring systems. By default, even a |
| 8251 | simple port probe or scan will produce a log. If those connections pollute |
| 8252 | the logs too much, it is possible to enable option "dontlognull" to indicate |
| 8253 | that a connection on which no data has been transferred will not be logged, |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 8254 | which typically corresponds to those probes. Note that errors will still be |
| 8255 | returned to the client and accounted for in the stats. If this is not what is |
| 8256 | desired, option http-ignore-probes can be used instead. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8257 | |
| 8258 | It is generally recommended not to use this option in uncontrolled |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8259 | environments (e.g. internet), otherwise scans and other malicious activities |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8260 | would not be logged. |
| 8261 | |
| 8262 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8263 | in a specific instance by prepending the "no" keyword before it. |
| 8264 | |
Willy Tarreau | 9e9919d | 2020-10-14 15:55:23 +0200 | [diff] [blame] | 8265 | See also : "log", "http-ignore-probes", "monitor-uri", and |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 8266 | section 8 about logging. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8267 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 8268 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 8269 | option forwardfor [ except <network> ] [ header <name> ] [ if-none ] |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8270 | Enable insertion of the X-Forwarded-For header to requests sent to servers |
| 8271 | May be used in sections : defaults | frontend | listen | backend |
| 8272 | yes | yes | yes | yes |
| 8273 | Arguments : |
| 8274 | <network> is an optional argument used to disable this option for sources |
| 8275 | matching <network> |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 8276 | <name> an optional argument to specify a different "X-Forwarded-For" |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 8277 | header name. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8278 | |
| 8279 | Since HAProxy works in reverse-proxy mode, the servers see its IP address as |
| 8280 | their client address. This is sometimes annoying when the client's IP address |
| 8281 | is expected in server logs. To solve this problem, the well-known HTTP header |
| 8282 | "X-Forwarded-For" may be added by HAProxy to all requests sent to the server. |
| 8283 | This header contains a value representing the client's IP address. Since this |
| 8284 | header is always appended at the end of the existing header list, the server |
| 8285 | 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] | 8286 | the server's manual to find how to enable use of this standard header. Note |
| 8287 | that only the last occurrence of the header must be used, since it is really |
| 8288 | possible that the client has already brought one. |
| 8289 | |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 8290 | 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] | 8291 | the default "X-Forwarded-For". This can be useful where you might already |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8292 | have a "X-Forwarded-For" header from a different application (e.g. stunnel), |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 8293 | and you need preserve it. Also if your backend server doesn't use the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8294 | "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 8295 | require "X-Cluster-Client-IP"). |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8296 | |
| 8297 | Sometimes, a same HAProxy instance may be shared between a direct client |
| 8298 | access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| 8299 | used to decrypt HTTPS traffic). It is possible to disable the addition of the |
| 8300 | header for a known source address or network by adding the "except" keyword |
| 8301 | followed by the network address. In this case, any source IP matching the |
| 8302 | network will not cause an addition of this header. Most common uses are with |
Christopher Faulet | 5d1def6 | 2021-02-26 09:19:15 +0100 | [diff] [blame] | 8303 | private networks or 127.0.0.1. IPv4 and IPv6 are both supported. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8304 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 8305 | Alternatively, the keyword "if-none" states that the header will only be |
| 8306 | added if it is not present. This should only be used in perfectly trusted |
| 8307 | environment, as this might cause a security issue if headers reaching haproxy |
| 8308 | are under the control of the end-user. |
| 8309 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8310 | 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] | 8311 | least one of them uses it, the header will be added. Note that the backend's |
| 8312 | setting of the header subargument takes precedence over the frontend's if |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 8313 | both are defined. In the case of the "if-none" argument, if at least one of |
| 8314 | the frontend or the backend does not specify it, it wants the addition to be |
| 8315 | mandatory, so it wins. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8316 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 8317 | Example : |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8318 | # Public HTTP address also used by stunnel on the same machine |
| 8319 | frontend www |
| 8320 | mode http |
| 8321 | option forwardfor except 127.0.0.1 # stunnel already adds the header |
| 8322 | |
Ross West | af72a1d | 2008-08-03 10:51:45 +0200 | [diff] [blame] | 8323 | # Those servers want the IP Address in X-Client |
| 8324 | backend www |
| 8325 | mode http |
| 8326 | option forwardfor header X-Client |
| 8327 | |
Willy Tarreau | 87cf514 | 2011-08-19 22:57:24 +0200 | [diff] [blame] | 8328 | See also : "option httpclose", "option http-server-close", |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8329 | "option http-keep-alive" |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8330 | |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8331 | |
Christopher Faulet | 98fbe95 | 2019-07-22 16:18:24 +0200 | [diff] [blame] | 8332 | option h1-case-adjust-bogus-client |
| 8333 | no option h1-case-adjust-bogus-client |
| 8334 | Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients |
| 8335 | May be used in sections : defaults | frontend | listen | backend |
| 8336 | yes | yes | yes | no |
| 8337 | Arguments : none |
| 8338 | |
| 8339 | There is no standard case for header names because, as stated in RFC7230, |
| 8340 | they are case-insensitive. So applications must handle them in a case- |
| 8341 | insensitive manner. But some bogus applications violate the standards and |
| 8342 | erroneously rely on the cases most commonly used by browsers. This problem |
| 8343 | becomes critical with HTTP/2 because all header names must be exchanged in |
| 8344 | lower case, and HAProxy follows the same convention. All header names are |
| 8345 | sent in lower case to clients and servers, regardless of the HTTP version. |
| 8346 | |
| 8347 | When HAProxy receives an HTTP/1 response, its header names are converted to |
| 8348 | lower case and manipulated and sent this way to the clients. If a client is |
| 8349 | known to violate the HTTP standards and to fail to process a response coming |
| 8350 | from HAProxy, it is possible to transform the lower case header names to a |
| 8351 | different format when the response is formatted and sent to the client, by |
| 8352 | enabling this option and specifying the list of headers to be reformatted |
| 8353 | using the global directives "h1-case-adjust" or "h1-case-adjust-file". This |
| 8354 | must only be a temporary workaround for the time it takes the client to be |
| 8355 | fixed, because clients which require such workarounds might be vulnerable to |
| 8356 | content smuggling attacks and must absolutely be fixed. |
| 8357 | |
| 8358 | Please note that this option will not affect standards-compliant clients. |
| 8359 | |
| 8360 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8361 | in a specific instance by prepending the "no" keyword before it. |
| 8362 | |
| 8363 | See also: "option h1-case-adjust-bogus-server", "h1-case-adjust", |
| 8364 | "h1-case-adjust-file". |
| 8365 | |
| 8366 | |
| 8367 | option h1-case-adjust-bogus-server |
| 8368 | no option h1-case-adjust-bogus-server |
| 8369 | Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers |
| 8370 | May be used in sections : defaults | frontend | listen | backend |
| 8371 | yes | no | yes | yes |
| 8372 | Arguments : none |
| 8373 | |
| 8374 | There is no standard case for header names because, as stated in RFC7230, |
| 8375 | they are case-insensitive. So applications must handle them in a case- |
| 8376 | insensitive manner. But some bogus applications violate the standards and |
| 8377 | erroneously rely on the cases most commonly used by browsers. This problem |
| 8378 | becomes critical with HTTP/2 because all header names must be exchanged in |
| 8379 | lower case, and HAProxy follows the same convention. All header names are |
| 8380 | sent in lower case to clients and servers, regardless of the HTTP version. |
| 8381 | |
| 8382 | When HAProxy receives an HTTP/1 request, its header names are converted to |
| 8383 | lower case and manipulated and sent this way to the servers. If a server is |
| 8384 | known to violate the HTTP standards and to fail to process a request coming |
| 8385 | from HAProxy, it is possible to transform the lower case header names to a |
| 8386 | different format when the request is formatted and sent to the server, by |
| 8387 | enabling this option and specifying the list of headers to be reformatted |
| 8388 | using the global directives "h1-case-adjust" or "h1-case-adjust-file". This |
| 8389 | must only be a temporary workaround for the time it takes the server to be |
| 8390 | fixed, because servers which require such workarounds might be vulnerable to |
| 8391 | content smuggling attacks and must absolutely be fixed. |
| 8392 | |
| 8393 | Please note that this option will not affect standards-compliant servers. |
| 8394 | |
| 8395 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8396 | in a specific instance by prepending the "no" keyword before it. |
| 8397 | |
| 8398 | See also: "option h1-case-adjust-bogus-client", "h1-case-adjust", |
| 8399 | "h1-case-adjust-file". |
| 8400 | |
| 8401 | |
Willy Tarreau | 9fbe18e | 2015-05-01 22:42:08 +0200 | [diff] [blame] | 8402 | option http-buffer-request |
| 8403 | no option http-buffer-request |
| 8404 | Enable or disable waiting for whole HTTP request body before proceeding |
| 8405 | May be used in sections : defaults | frontend | listen | backend |
| 8406 | yes | yes | yes | yes |
| 8407 | Arguments : none |
| 8408 | |
| 8409 | It is sometimes desirable to wait for the body of an HTTP request before |
| 8410 | taking a decision. This is what is being done by "balance url_param" for |
| 8411 | example. The first use case is to buffer requests from slow clients before |
| 8412 | connecting to the server. Another use case consists in taking the routing |
| 8413 | decision based on the request body's contents. This option placed in a |
| 8414 | frontend or backend forces the HTTP processing to wait until either the whole |
Christopher Faulet | 6db8a2e | 2019-11-19 16:27:25 +0100 | [diff] [blame] | 8415 | body is received or the request buffer is full. It can have undesired side |
| 8416 | effects with some applications abusing HTTP by expecting unbuffered |
| 8417 | transmissions between the frontend and the backend, so this should definitely |
| 8418 | not be used by default. |
Willy Tarreau | 9fbe18e | 2015-05-01 22:42:08 +0200 | [diff] [blame] | 8419 | |
Christopher Faulet | 021a8e4 | 2021-03-29 10:46:38 +0200 | [diff] [blame] | 8420 | See also : "option http-no-delay", "timeout http-request", |
| 8421 | "http-request wait-for-body" |
Willy Tarreau | 9fbe18e | 2015-05-01 22:42:08 +0200 | [diff] [blame] | 8422 | |
| 8423 | |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 8424 | option http-ignore-probes |
| 8425 | no option http-ignore-probes |
| 8426 | Enable or disable logging of null connections and request timeouts |
| 8427 | May be used in sections : defaults | frontend | listen | backend |
| 8428 | yes | yes | yes | no |
| 8429 | Arguments : none |
| 8430 | |
| 8431 | Recently some browsers started to implement a "pre-connect" feature |
| 8432 | consisting in speculatively connecting to some recently visited web sites |
| 8433 | just in case the user would like to visit them. This results in many |
| 8434 | connections being established to web sites, which end up in 408 Request |
| 8435 | Timeout if the timeout strikes first, or 400 Bad Request when the browser |
| 8436 | decides to close them first. These ones pollute the log and feed the error |
| 8437 | counters. There was already "option dontlognull" but it's insufficient in |
| 8438 | this case. Instead, this option does the following things : |
| 8439 | - prevent any 400/408 message from being sent to the client if nothing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8440 | was received over a connection before it was closed; |
| 8441 | - prevent any log from being emitted in this situation; |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 8442 | - prevent any error counter from being incremented |
| 8443 | |
| 8444 | That way the empty connection is silently ignored. Note that it is better |
| 8445 | not to use this unless it is clear that it is needed, because it will hide |
| 8446 | real problems. The most common reason for not receiving a request and seeing |
| 8447 | a 408 is due to an MTU inconsistency between the client and an intermediary |
| 8448 | element such as a VPN, which blocks too large packets. These issues are |
| 8449 | generally seen with POST requests as well as GET with large cookies. The logs |
| 8450 | are often the only way to detect them. |
| 8451 | |
| 8452 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8453 | in a specific instance by prepending the "no" keyword before it. |
| 8454 | |
| 8455 | See also : "log", "dontlognull", "errorfile", and section 8 about logging. |
| 8456 | |
| 8457 | |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8458 | option http-keep-alive |
| 8459 | no option http-keep-alive |
| 8460 | Enable or disable HTTP keep-alive from client to server |
| 8461 | May be used in sections : defaults | frontend | listen | backend |
| 8462 | yes | yes | yes | yes |
| 8463 | Arguments : none |
| 8464 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 8465 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 8466 | connections: for each connection it processes each request and response, and |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8467 | leaves the connection idle on both sides between the end of a response and |
| 8468 | the start of a new request. This mode may be changed by several options such |
Christopher Faulet | 159e667 | 2019-07-16 15:09:52 +0200 | [diff] [blame] | 8469 | as "option http-server-close" or "option httpclose". This option allows to |
| 8470 | set back the keep-alive mode, which can be useful when another mode was used |
| 8471 | in a defaults section. |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 8472 | |
| 8473 | Setting "option http-keep-alive" enables HTTP keep-alive mode on the client- |
| 8474 | 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] | 8475 | network) and the fastest session reuse on the server side at the expense |
| 8476 | of maintaining idle connections to the servers. In general, it is possible |
| 8477 | with this option to achieve approximately twice the request rate that the |
| 8478 | "http-server-close" option achieves on small objects. There are mainly two |
| 8479 | situations where this option may be useful : |
| 8480 | |
| 8481 | - when the server is non-HTTP compliant and authenticates the connection |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8482 | instead of requests (e.g. NTLM authentication) |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8483 | |
| 8484 | - when the cost of establishing the connection to the server is significant |
| 8485 | compared to the cost of retrieving the associated object from the server. |
| 8486 | |
| 8487 | This last case can happen when the server is a fast static server of cache. |
| 8488 | In this case, the server will need to be properly tuned to support high enough |
| 8489 | connection counts because connections will last until the client sends another |
| 8490 | request. |
| 8491 | |
| 8492 | If the client request has to go to another backend or another server due to |
| 8493 | content switching or the load balancing algorithm, the idle connection will |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 8494 | immediately be closed and a new one re-opened. Option "prefer-last-server" is |
| 8495 | available to try optimize server selection so that if the server currently |
| 8496 | attached to an idle connection is usable, it will be used. |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8497 | |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8498 | At the moment, logs will not indicate whether requests came from the same |
| 8499 | session or not. The accept date reported in the logs corresponds to the end |
| 8500 | of the previous request, and the request time corresponds to the time spent |
| 8501 | waiting for a new request. The keep-alive request time is still bound to the |
| 8502 | timeout defined by "timeout http-keep-alive" or "timeout http-request" if |
| 8503 | not set. |
| 8504 | |
Christopher Faulet | 159e667 | 2019-07-16 15:09:52 +0200 | [diff] [blame] | 8505 | This option disables and replaces any previous "option httpclose" or "option |
| 8506 | http-server-close". When backend and frontend options differ, all of these 4 |
| 8507 | options have precedence over "option http-keep-alive". |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8508 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8509 | See also : "option httpclose",, "option http-server-close", |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 8510 | "option prefer-last-server", "option http-pretend-keepalive", |
Frédéric Lécaille | 93d3316 | 2019-03-06 09:35:59 +0100 | [diff] [blame] | 8511 | and "1.1. The HTTP transaction model". |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8512 | |
| 8513 | |
Willy Tarreau | 96e3121 | 2011-05-30 18:10:30 +0200 | [diff] [blame] | 8514 | option http-no-delay |
| 8515 | no option http-no-delay |
| 8516 | Instruct the system to favor low interactive delays over performance in HTTP |
| 8517 | May be used in sections : defaults | frontend | listen | backend |
| 8518 | yes | yes | yes | yes |
| 8519 | Arguments : none |
| 8520 | |
| 8521 | In HTTP, each payload is unidirectional and has no notion of interactivity. |
| 8522 | Any agent is expected to queue data somewhat for a reasonably low delay. |
| 8523 | There are some very rare server-to-server applications that abuse the HTTP |
| 8524 | protocol and expect the payload phase to be highly interactive, with many |
| 8525 | interleaved data chunks in both directions within a single request. This is |
| 8526 | absolutely not supported by the HTTP specification and will not work across |
| 8527 | most proxies or servers. When such applications attempt to do this through |
| 8528 | haproxy, it works but they will experience high delays due to the network |
| 8529 | optimizations which favor performance by instructing the system to wait for |
| 8530 | enough data to be available in order to only send full packets. Typical |
| 8531 | delays are around 200 ms per round trip. Note that this only happens with |
| 8532 | abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not |
| 8533 | affected. |
| 8534 | |
| 8535 | When "option http-no-delay" is present in either the frontend or the backend |
| 8536 | used by a connection, all such optimizations will be disabled in order to |
| 8537 | make the exchanges as fast as possible. Of course this offers no guarantee on |
| 8538 | the functionality, as it may break at any other place. But if it works via |
| 8539 | HAProxy, it will work as fast as possible. This option should never be used |
| 8540 | by default, and should never be used at all unless such a buggy application |
| 8541 | is discovered. The impact of using this option is an increase of bandwidth |
| 8542 | usage and CPU usage, which may significantly lower performance in high |
| 8543 | latency environments. |
| 8544 | |
Willy Tarreau | 9fbe18e | 2015-05-01 22:42:08 +0200 | [diff] [blame] | 8545 | See also : "option http-buffer-request" |
| 8546 | |
Willy Tarreau | 96e3121 | 2011-05-30 18:10:30 +0200 | [diff] [blame] | 8547 | |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8548 | option http-pretend-keepalive |
| 8549 | no option http-pretend-keepalive |
| 8550 | Define whether haproxy will announce keepalive to the server or not |
| 8551 | May be used in sections : defaults | frontend | listen | backend |
Christopher Faulet | 98db976 | 2018-09-21 10:25:19 +0200 | [diff] [blame] | 8552 | yes | no | yes | yes |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8553 | Arguments : none |
| 8554 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8555 | When running with "option http-server-close" or "option httpclose", haproxy |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8556 | adds a "Connection: close" header to the request forwarded to the server. |
| 8557 | Unfortunately, when some servers see this header, they automatically refrain |
| 8558 | from using the chunked encoding for responses of unknown length, while this |
| 8559 | is totally unrelated. The immediate effect is that this prevents haproxy from |
| 8560 | maintaining the client connection alive. A second effect is that a client or |
| 8561 | a cache could receive an incomplete response without being aware of it, and |
| 8562 | consider the response complete. |
| 8563 | |
| 8564 | By setting "option http-pretend-keepalive", haproxy will make the server |
| 8565 | believe it will keep the connection alive. The server will then not fall back |
| 8566 | to the abnormal undesired above. When haproxy gets the whole response, it |
| 8567 | will close the connection with the server just as it would do with the |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8568 | "option httpclose". That way the client gets a normal response and the |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8569 | connection is correctly closed on the server side. |
| 8570 | |
| 8571 | It is recommended not to enable this option by default, because most servers |
| 8572 | will more efficiently close the connection themselves after the last packet, |
| 8573 | and release its buffers slightly earlier. Also, the added packet on the |
| 8574 | network could slightly reduce the overall peak performance. However it is |
| 8575 | worth noting that when this option is enabled, haproxy will have slightly |
| 8576 | less work to do. So if haproxy is the bottleneck on the whole architecture, |
| 8577 | enabling this option might save a few CPU cycles. |
| 8578 | |
Christopher Faulet | 98db976 | 2018-09-21 10:25:19 +0200 | [diff] [blame] | 8579 | This option may be set in backend and listen sections. Using it in a frontend |
| 8580 | section will be ignored and a warning will be reported during startup. It is |
| 8581 | a backend related option, so there is no real reason to set it on a |
| 8582 | frontend. This option may be combined with "option httpclose", which will |
| 8583 | cause keepalive to be announced to the server and close to be announced to |
| 8584 | the client. This practice is discouraged though. |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8585 | |
| 8586 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8587 | in a specific instance by prepending the "no" keyword before it. |
| 8588 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8589 | See also : "option httpclose", "option http-server-close", and |
Willy Tarreau | 16bfb02 | 2010-01-16 19:48:41 +0100 | [diff] [blame] | 8590 | "option http-keep-alive" |
Willy Tarreau | 8a8e1d9 | 2010-04-05 16:15:16 +0200 | [diff] [blame] | 8591 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8592 | |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 8593 | option http-server-close |
| 8594 | no option http-server-close |
| 8595 | Enable or disable HTTP connection closing on the server side |
| 8596 | May be used in sections : defaults | frontend | listen | backend |
| 8597 | yes | yes | yes | yes |
| 8598 | Arguments : none |
| 8599 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 8600 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 8601 | connections: for each connection it processes each request and response, and |
| 8602 | leaves the connection idle on both sides between the end of a response and |
| 8603 | the start of a new request. This mode may be changed by several options such |
Christopher Faulet | 159e667 | 2019-07-16 15:09:52 +0200 | [diff] [blame] | 8604 | as "option http-server-close" or "option httpclose". Setting "option |
| 8605 | http-server-close" enables HTTP connection-close mode on the server side |
| 8606 | while keeping the ability to support HTTP keep-alive and pipelining on the |
| 8607 | client side. This provides the lowest latency on the client side (slow |
| 8608 | network) and the fastest session reuse on the server side to save server |
| 8609 | resources, similarly to "option httpclose". It also permits non-keepalive |
| 8610 | capable servers to be served in keep-alive mode to the clients if they |
| 8611 | conform to the requirements of RFC7230. Please note that some servers do not |
| 8612 | always conform to those requirements when they see "Connection: close" in the |
| 8613 | request. The effect will be that keep-alive will never be used. A workaround |
| 8614 | consists in enabling "option http-pretend-keepalive". |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 8615 | |
| 8616 | At the moment, logs will not indicate whether requests came from the same |
| 8617 | session or not. The accept date reported in the logs corresponds to the end |
| 8618 | of the previous request, and the request time corresponds to the time spent |
| 8619 | 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] | 8620 | timeout defined by "timeout http-keep-alive" or "timeout http-request" if |
| 8621 | not set. |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 8622 | |
| 8623 | This option may be set both in a frontend and in a backend. It is enabled if |
| 8624 | at least one of the frontend or backend holding a connection has it enabled. |
Christopher Faulet | 159e667 | 2019-07-16 15:09:52 +0200 | [diff] [blame] | 8625 | It disables and replaces any previous "option httpclose" or "option |
| 8626 | http-keep-alive". Please check section 4 ("Proxies") to see how this option |
| 8627 | combines with others when frontend and backend options differ. |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 8628 | |
| 8629 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8630 | in a specific instance by prepending the "no" keyword before it. |
| 8631 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8632 | See also : "option httpclose", "option http-pretend-keepalive", |
| 8633 | "option http-keep-alive", and "1.1. The HTTP transaction model". |
Willy Tarreau | b608feb | 2010-01-02 22:47:18 +0100 | [diff] [blame] | 8634 | |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 8635 | option http-use-proxy-header |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 8636 | no option http-use-proxy-header |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 8637 | Make use of non-standard Proxy-Connection header instead of Connection |
| 8638 | May be used in sections : defaults | frontend | listen | backend |
| 8639 | yes | yes | yes | no |
| 8640 | Arguments : none |
| 8641 | |
Lukas Tribus | 2395368 | 2017-04-28 13:24:30 +0000 | [diff] [blame] | 8642 | While RFC7230 explicitly states that HTTP/1.1 agents must use the |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 8643 | Connection header to indicate their wish of persistent or non-persistent |
| 8644 | connections, both browsers and proxies ignore this header for proxied |
| 8645 | connections and make use of the undocumented, non-standard Proxy-Connection |
| 8646 | header instead. The issue begins when trying to put a load balancer between |
| 8647 | browsers and such proxies, because there will be a difference between what |
| 8648 | haproxy understands and what the client and the proxy agree on. |
| 8649 | |
| 8650 | By setting this option in a frontend, haproxy can automatically switch to use |
| 8651 | that non-standard header if it sees proxied requests. A proxied request is |
Lukas Tribus | f01a9cd | 2016-02-03 18:09:37 +0100 | [diff] [blame] | 8652 | defined here as one where the URI begins with neither a '/' nor a '*'. This |
| 8653 | is incompatible with the HTTP tunnel mode. Note that this option can only be |
| 8654 | specified in a frontend and will affect the request along its whole life. |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 8655 | |
Willy Tarreau | 844a7e7 | 2010-01-31 21:46:18 +0100 | [diff] [blame] | 8656 | Also, when this option is set, a request which requires authentication will |
| 8657 | automatically switch to use proxy authentication headers if it is itself a |
| 8658 | proxied request. That makes it possible to check or enforce authentication in |
| 8659 | front of an existing proxy. |
| 8660 | |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 8661 | This option should normally never be used, except in front of a proxy. |
| 8662 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8663 | See also : "option httpclose", and "option http-server-close". |
Willy Tarreau | 88d349d | 2010-01-25 12:15:43 +0100 | [diff] [blame] | 8664 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8665 | option httpchk |
| 8666 | option httpchk <uri> |
| 8667 | option httpchk <method> <uri> |
| 8668 | option httpchk <method> <uri> <version> |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 8669 | Enables HTTP protocol to check on the servers health |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8670 | May be used in sections : defaults | frontend | listen | backend |
| 8671 | yes | no | yes | yes |
| 8672 | Arguments : |
| 8673 | <method> is the optional HTTP method used with the requests. When not set, |
| 8674 | the "OPTIONS" method is used, as it generally requires low server |
| 8675 | processing and is easy to filter out from the logs. Any method |
| 8676 | may be used, though it is not recommended to invent non-standard |
| 8677 | ones. |
| 8678 | |
| 8679 | <uri> is the URI referenced in the HTTP requests. It defaults to " / " |
| 8680 | which is accessible by default on almost any server, but may be |
| 8681 | changed to any other URI. Query strings are permitted. |
| 8682 | |
| 8683 | <version> is the optional HTTP version string. It defaults to "HTTP/1.0" |
| 8684 | but some servers might behave incorrectly in HTTP 1.0, so turning |
| 8685 | it to HTTP/1.1 may sometimes help. Note that the Host field is |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 8686 | mandatory in HTTP/1.1, use "http-check send" directive to add it. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8687 | |
| 8688 | By default, server health checks only consist in trying to establish a TCP |
| 8689 | connection. When "option httpchk" is specified, a complete HTTP request is |
| 8690 | sent once the TCP connection is established, and responses 2xx and 3xx are |
| 8691 | considered valid, while all other ones indicate a server failure, including |
| 8692 | the lack of any response. |
| 8693 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 8694 | Combined with "http-check" directives, it is possible to customize the |
| 8695 | request sent during the HTTP health checks or the matching rules on the |
| 8696 | response. It is also possible to configure a send/expect sequence, just like |
| 8697 | with the directive "tcp-check" for TCP health checks. |
| 8698 | |
| 8699 | The server configuration is used by default to open connections to perform |
| 8700 | HTTP health checks. By it is also possible to overwrite server parameters |
| 8701 | using "http-check connect" rules. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8702 | |
Christopher Faulet | e5870d8 | 2020-04-15 11:32:03 +0200 | [diff] [blame] | 8703 | "httpchk" option does not necessarily require an HTTP backend, it also works |
| 8704 | with plain TCP backends. This is particularly useful to check simple scripts |
Christopher Faulet | 14cd316 | 2020-04-16 14:50:06 +0200 | [diff] [blame] | 8705 | bound to some dedicated ports using the inetd daemon. However, it will always |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 8706 | internally relies on an HTX multiplexer. Thus, it means the request |
Christopher Faulet | 14cd316 | 2020-04-16 14:50:06 +0200 | [diff] [blame] | 8707 | formatting and the response parsing will be strict. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8708 | |
Christopher Faulet | 8acb128 | 2020-04-09 08:44:06 +0200 | [diff] [blame] | 8709 | Note : For a while, there was no way to add headers or body in the request |
| 8710 | used for HTTP health checks. So a workaround was to hide it at the end |
| 8711 | of the version string with a "\r\n" after the version. It is now |
| 8712 | deprecated. The directive "http-check send" must be used instead. |
| 8713 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8714 | Examples : |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 8715 | # Relay HTTPS traffic to Apache instance and check service availability |
| 8716 | # using HTTP request "OPTIONS * HTTP/1.1" on port 80. |
| 8717 | backend https_relay |
| 8718 | mode tcp |
| 8719 | option httpchk OPTIONS * HTTP/1.1 |
| 8720 | http-check send hdr Host www |
| 8721 | server apache1 192.168.1.1:443 check port 80 |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8722 | |
Simon Horman | afc47ee | 2013-11-25 10:46:35 +0900 | [diff] [blame] | 8723 | See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check", |
| 8724 | "option pgsql-check", "http-check" and the "check", "port" and |
| 8725 | "inter" server options. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 8726 | |
| 8727 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8728 | option httpclose |
| 8729 | no option httpclose |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8730 | Enable or disable HTTP connection closing |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8731 | May be used in sections : defaults | frontend | listen | backend |
| 8732 | yes | yes | yes | yes |
| 8733 | Arguments : none |
| 8734 | |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 8735 | By default HAProxy operates in keep-alive mode with regards to persistent |
| 8736 | connections: for each connection it processes each request and response, and |
| 8737 | leaves the connection idle on both sides between the end of a response and |
| 8738 | the start of a new request. This mode may be changed by several options such |
Christopher Faulet | 159e667 | 2019-07-16 15:09:52 +0200 | [diff] [blame] | 8739 | as "option http-server-close" or "option httpclose". |
Willy Tarreau | 70dffda | 2014-01-30 03:07:23 +0100 | [diff] [blame] | 8740 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8741 | If "option httpclose" is set, HAProxy will close connections with the server |
| 8742 | and the client as soon as the request and the response are received. It will |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 8743 | also check if a "Connection: close" header is already set in each direction, |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8744 | and will add one if missing. Any "Connection" header different from "close" |
| 8745 | will also be removed. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8746 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8747 | This option may also be combined with "option http-pretend-keepalive", which |
| 8748 | will disable sending of the "Connection: close" header, but will still cause |
| 8749 | the connection to be closed once the whole response is received. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8750 | |
| 8751 | This option may be set both in a frontend and in a backend. It is enabled if |
| 8752 | at least one of the frontend or backend holding a connection has it enabled. |
Christopher Faulet | 159e667 | 2019-07-16 15:09:52 +0200 | [diff] [blame] | 8753 | It disables and replaces any previous "option http-server-close" or "option |
| 8754 | http-keep-alive". Please check section 4 ("Proxies") to see how this option |
| 8755 | combines with others when frontend and backend options differ. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8756 | |
| 8757 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8758 | in a specific instance by prepending the "no" keyword before it. |
| 8759 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 8760 | See also : "option http-server-close" and "1.1. The HTTP transaction model". |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8761 | |
| 8762 | |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 8763 | option httplog [ clf ] |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8764 | Enable logging of HTTP request, session state and timers |
| 8765 | May be used in sections : defaults | frontend | listen | backend |
Tim Duesterhus | 9ad9f35 | 2018-02-05 20:52:27 +0100 | [diff] [blame] | 8766 | yes | yes | yes | no |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 8767 | Arguments : |
| 8768 | clf if the "clf" argument is added, then the output format will be |
| 8769 | the CLF format instead of HAProxy's default HTTP format. You can |
| 8770 | use this when you need to feed HAProxy's logs through a specific |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8771 | log analyzer which only support the CLF format and which is not |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 8772 | extensible. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8773 | |
| 8774 | By default, the log output format is very poor, as it only contains the |
| 8775 | source and destination addresses, and the instance name. By specifying |
| 8776 | "option httplog", each log line turns into a much richer format including, |
| 8777 | but not limited to, the HTTP request, the connection timers, the session |
| 8778 | status, the connections numbers, the captured headers and cookies, the |
| 8779 | frontend, backend and server name, and of course the source address and |
| 8780 | ports. |
| 8781 | |
PiBa-NL | bd556bf | 2014-12-11 21:31:54 +0100 | [diff] [blame] | 8782 | Specifying only "option httplog" will automatically clear the 'clf' mode |
| 8783 | if it was set by default. |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 8784 | |
Guillaume de Lafond | 29f4560 | 2017-03-31 19:52:15 +0200 | [diff] [blame] | 8785 | "option httplog" overrides any previous "log-format" directive. |
| 8786 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8787 | See also : section 8 about logging. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8788 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 8789 | |
| 8790 | option http_proxy |
| 8791 | no option http_proxy |
| 8792 | Enable or disable plain HTTP proxy mode |
| 8793 | May be used in sections : defaults | frontend | listen | backend |
| 8794 | yes | yes | yes | yes |
| 8795 | Arguments : none |
| 8796 | |
| 8797 | It sometimes happens that people need a pure HTTP proxy which understands |
| 8798 | basic proxy requests without caching nor any fancy feature. In this case, |
| 8799 | it may be worth setting up an HAProxy instance with the "option http_proxy" |
| 8800 | set. In this mode, no server is declared, and the connection is forwarded to |
| 8801 | the IP address and port found in the URL after the "http://" scheme. |
| 8802 | |
| 8803 | No host address resolution is performed, so this only works when pure IP |
| 8804 | addresses are passed. Since this option's usage perimeter is rather limited, |
Lukas Tribus | f01a9cd | 2016-02-03 18:09:37 +0100 | [diff] [blame] | 8805 | it will probably be used only by experts who know they need exactly it. This |
| 8806 | is incompatible with the HTTP tunnel mode. |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 8807 | |
| 8808 | If this option has been enabled in a "defaults" section, it can be disabled |
| 8809 | in a specific instance by prepending the "no" keyword before it. |
| 8810 | |
| 8811 | Example : |
| 8812 | # this backend understands HTTP proxy requests and forwards them directly. |
| 8813 | backend direct_forward |
| 8814 | option httpclose |
| 8815 | option http_proxy |
| 8816 | |
| 8817 | See also : "option httpclose" |
| 8818 | |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 8819 | |
Jamie Gloudon | 801a0a3 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 8820 | option independent-streams |
| 8821 | no option independent-streams |
| 8822 | Enable or disable independent timeout processing for both directions |
Willy Tarreau | f27b5ea | 2009-10-03 22:01:18 +0200 | [diff] [blame] | 8823 | May be used in sections : defaults | frontend | listen | backend |
| 8824 | yes | yes | yes | yes |
| 8825 | Arguments : none |
| 8826 | |
| 8827 | By default, when data is sent over a socket, both the write timeout and the |
| 8828 | read timeout for that socket are refreshed, because we consider that there is |
| 8829 | activity on that socket, and we have no other means of guessing if we should |
| 8830 | receive data or not. |
| 8831 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8832 | While this default behavior is desirable for almost all applications, there |
Willy Tarreau | f27b5ea | 2009-10-03 22:01:18 +0200 | [diff] [blame] | 8833 | exists a situation where it is desirable to disable it, and only refresh the |
| 8834 | read timeout if there are incoming data. This happens on sessions with large |
| 8835 | timeouts and low amounts of exchanged data such as telnet session. If the |
| 8836 | server suddenly disappears, the output data accumulates in the system's |
| 8837 | socket buffers, both timeouts are correctly refreshed, and there is no way |
| 8838 | to know the server does not receive them, so we don't timeout. However, when |
| 8839 | the underlying protocol always echoes sent data, it would be enough by itself |
| 8840 | to detect the issue using the read timeout. Note that this problem does not |
| 8841 | happen with more verbose protocols because data won't accumulate long in the |
| 8842 | socket buffers. |
| 8843 | |
| 8844 | When this option is set on the frontend, it will disable read timeout updates |
| 8845 | on data sent to the client. There probably is little use of this case. When |
| 8846 | the option is set on the backend, it will disable read timeout updates on |
| 8847 | data sent to the server. Doing so will typically break large HTTP posts from |
| 8848 | slow lines, so use it with caution. |
| 8849 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 8850 | See also : "timeout client", "timeout server" and "timeout tunnel" |
Willy Tarreau | f27b5ea | 2009-10-03 22:01:18 +0200 | [diff] [blame] | 8851 | |
| 8852 | |
Gabor Lekeny | b4c81e4 | 2010-09-29 18:17:05 +0200 | [diff] [blame] | 8853 | option ldap-check |
| 8854 | Use LDAPv3 health checks for server testing |
| 8855 | May be used in sections : defaults | frontend | listen | backend |
| 8856 | yes | no | yes | yes |
| 8857 | Arguments : none |
| 8858 | |
| 8859 | It is possible to test that the server correctly talks LDAPv3 instead of just |
| 8860 | testing that it accepts the TCP connection. When this option is set, an |
| 8861 | LDAPv3 anonymous simple bind message is sent to the server, and the response |
| 8862 | is analyzed to find an LDAPv3 bind response message. |
| 8863 | |
| 8864 | The server is considered valid only when the LDAP response contains success |
| 8865 | resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9). |
| 8866 | |
| 8867 | Logging of bind requests is server dependent see your documentation how to |
| 8868 | configure it. |
| 8869 | |
| 8870 | Example : |
| 8871 | option ldap-check |
| 8872 | |
| 8873 | See also : "option httpchk" |
| 8874 | |
| 8875 | |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 8876 | option external-check |
| 8877 | Use external processes for server health checks |
| 8878 | May be used in sections : defaults | frontend | listen | backend |
| 8879 | yes | no | yes | yes |
| 8880 | |
| 8881 | It is possible to test the health of a server using an external command. |
| 8882 | This is achieved by running the executable set using "external-check |
| 8883 | command". |
| 8884 | |
| 8885 | Requires the "external-check" global to be set. |
| 8886 | |
| 8887 | See also : "external-check", "external-check command", "external-check path" |
| 8888 | |
| 8889 | |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 8890 | option log-health-checks |
| 8891 | no option log-health-checks |
Willy Tarreau | bef1b32 | 2014-05-13 21:01:39 +0200 | [diff] [blame] | 8892 | Enable or disable logging of health checks status updates |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 8893 | May be used in sections : defaults | frontend | listen | backend |
| 8894 | yes | no | yes | yes |
| 8895 | Arguments : none |
| 8896 | |
Willy Tarreau | bef1b32 | 2014-05-13 21:01:39 +0200 | [diff] [blame] | 8897 | By default, failed health check are logged if server is UP and successful |
| 8898 | health checks are logged if server is DOWN, so the amount of additional |
| 8899 | information is limited. |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 8900 | |
Willy Tarreau | bef1b32 | 2014-05-13 21:01:39 +0200 | [diff] [blame] | 8901 | When this option is enabled, any change of the health check status or to |
| 8902 | the server's health will be logged, so that it becomes possible to know |
| 8903 | that a server was failing occasional checks before crashing, or exactly when |
| 8904 | it failed to respond a valid HTTP status, then when the port started to |
| 8905 | reject connections, then when the server stopped responding at all. |
| 8906 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8907 | Note that status changes not caused by health checks (e.g. enable/disable on |
Willy Tarreau | bef1b32 | 2014-05-13 21:01:39 +0200 | [diff] [blame] | 8908 | the CLI) are intentionally not logged by this option. |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 8909 | |
Willy Tarreau | bef1b32 | 2014-05-13 21:01:39 +0200 | [diff] [blame] | 8910 | See also: "option httpchk", "option ldap-check", "option mysql-check", |
| 8911 | "option pgsql-check", "option redis-check", "option smtpchk", |
| 8912 | "option tcp-check", "log" and section 8 about logging. |
Willy Tarreau | 211ad24 | 2009-10-03 21:45:07 +0200 | [diff] [blame] | 8913 | |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 8914 | |
| 8915 | option log-separate-errors |
| 8916 | no option log-separate-errors |
| 8917 | Change log level for non-completely successful connections |
| 8918 | May be used in sections : defaults | frontend | listen | backend |
| 8919 | yes | yes | yes | no |
| 8920 | Arguments : none |
| 8921 | |
| 8922 | Sometimes looking for errors in logs is not easy. This option makes haproxy |
| 8923 | raise the level of logs containing potentially interesting information such |
| 8924 | as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The |
| 8925 | level changes from "info" to "err". This makes it possible to log them |
| 8926 | separately to a different file with most syslog daemons. Be careful not to |
| 8927 | remove them from the original file, otherwise you would lose ordering which |
| 8928 | provides very important information. |
| 8929 | |
| 8930 | Using this option, large sites dealing with several thousand connections per |
| 8931 | second may log normal traffic to a rotating buffer and only archive smaller |
| 8932 | error logs. |
| 8933 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8934 | See also : "log", "dontlognull", "dontlog-normal" and section 8 about |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 8935 | logging. |
| 8936 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8937 | |
| 8938 | option logasap |
| 8939 | no option logasap |
Jerome Magnin | 95fb57b | 2020-04-23 19:01:17 +0200 | [diff] [blame] | 8940 | Enable or disable early logging. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8941 | May be used in sections : defaults | frontend | listen | backend |
| 8942 | yes | yes | yes | no |
| 8943 | Arguments : none |
| 8944 | |
Jerome Magnin | 95fb57b | 2020-04-23 19:01:17 +0200 | [diff] [blame] | 8945 | By default, logs are emitted when all the log format variables and sample |
| 8946 | fetches used in the definition of the log-format string return a value, or |
| 8947 | when the session is terminated. This allows the built in log-format strings |
| 8948 | to account for the transfer time, or the number of bytes in log messages. |
| 8949 | |
| 8950 | When handling long lived connections such as large file transfers or RDP, |
| 8951 | it may take a while for the request or connection to appear in the logs. |
| 8952 | Using "option logasap", the log message is created as soon as the server |
| 8953 | connection is established in mode tcp, or as soon as the server sends the |
| 8954 | complete headers in mode http. Missing information in the logs will be the |
Ilya Shipitsin | 4329a9a | 2020-05-05 21:17:10 +0500 | [diff] [blame] | 8955 | total number of bytes which will only indicate the amount of data transferred |
Jerome Magnin | 95fb57b | 2020-04-23 19:01:17 +0200 | [diff] [blame] | 8956 | before the message was created and the total time which will not take the |
| 8957 | remainder of the connection life or transfer time into account. For the case |
| 8958 | of HTTP, it is good practice to capture the Content-Length response header |
| 8959 | so that the logs at least indicate how many bytes are expected to be |
Ilya Shipitsin | 4329a9a | 2020-05-05 21:17:10 +0500 | [diff] [blame] | 8960 | transferred. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8961 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 8962 | Examples : |
| 8963 | listen http_proxy 0.0.0.0:80 |
| 8964 | mode http |
| 8965 | option httplog |
| 8966 | option logasap |
| 8967 | log 192.168.2.200 local3 |
| 8968 | |
| 8969 | >>> Feb 6 12:14:14 localhost \ |
| 8970 | haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ |
| 8971 | static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \ |
| 8972 | "GET /image.iso HTTP/1.0" |
| 8973 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 8974 | See also : "option httplog", "capture response header", and section 8 about |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 8975 | logging. |
| 8976 | |
| 8977 | |
Christopher Faulet | 62f79fe | 2020-05-18 18:13:03 +0200 | [diff] [blame] | 8978 | option mysql-check [ user <username> [ { post-41 | pre-41 } ] ] |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 8979 | Use MySQL health checks for server testing |
Hervé COMMOWICK | 698ae00 | 2010-01-12 09:25:13 +0100 | [diff] [blame] | 8980 | May be used in sections : defaults | frontend | listen | backend |
| 8981 | yes | no | yes | yes |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 8982 | Arguments : |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 8983 | <username> This is the username which will be used when connecting to MySQL |
| 8984 | server. |
Christopher Faulet | 62f79fe | 2020-05-18 18:13:03 +0200 | [diff] [blame] | 8985 | post-41 Send post v4.1 client compatible checks (the default) |
| 8986 | pre-41 Send pre v4.1 client compatible checks |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 8987 | |
| 8988 | If you specify a username, the check consists of sending two MySQL packet, |
| 8989 | one Client Authentication packet, and one QUIT packet, to correctly close |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 8990 | MySQL session. We then parse the MySQL Handshake Initialization packet and/or |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 8991 | Error packet. It is a basic but useful test which does not produce error nor |
| 8992 | aborted connect on the server. However, it requires adding an authorization |
| 8993 | in the MySQL table, like this : |
| 8994 | |
| 8995 | USE mysql; |
| 8996 | INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>'); |
| 8997 | FLUSH PRIVILEGES; |
| 8998 | |
| 8999 | If you don't specify a username (it is deprecated and not recommended), the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9000 | check only consists in parsing the Mysql Handshake Initialization packet or |
Hervé COMMOWICK | 8776f1b | 2010-10-18 15:58:36 +0200 | [diff] [blame] | 9001 | Error packet, we don't send anything in this mode. It was reported that it |
| 9002 | can generate lockout if check is too frequent and/or if there is not enough |
| 9003 | traffic. In fact, you need in this case to check MySQL "max_connect_errors" |
| 9004 | value as if a connection is established successfully within fewer than MySQL |
| 9005 | "max_connect_errors" attempts after a previous connection was interrupted, |
| 9006 | the error count for the host is cleared to zero. If HAProxy's server get |
| 9007 | blocked, the "FLUSH HOSTS" statement is the only way to unblock it. |
| 9008 | |
| 9009 | Remember that this does not check database presence nor database consistency. |
| 9010 | 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] | 9011 | |
Hervé COMMOWICK | 212f778 | 2011-06-10 14:05:59 +0200 | [diff] [blame] | 9012 | 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] | 9013 | |
| 9014 | Most often, an incoming MySQL server needs to see the client's IP address for |
| 9015 | various purposes, including IP privilege matching and connection logging. |
| 9016 | When possible, it is often wise to masquerade the client's IP address when |
| 9017 | connecting to the server using the "usesrc" argument of the "source" keyword, |
Willy Tarreau | 29fbe51 | 2015-08-20 19:35:14 +0200 | [diff] [blame] | 9018 | which requires the transparent proxy feature to be compiled in, and the MySQL |
| 9019 | server to route the client via the machine hosting haproxy. |
Hervé COMMOWICK | 698ae00 | 2010-01-12 09:25:13 +0100 | [diff] [blame] | 9020 | |
| 9021 | See also: "option httpchk" |
| 9022 | |
| 9023 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9024 | option nolinger |
| 9025 | no option nolinger |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 9026 | Enable or disable immediate session resource cleaning after close |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9027 | May be used in sections: defaults | frontend | listen | backend |
| 9028 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 9029 | Arguments : none |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9030 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9031 | When clients or servers abort connections in a dirty way (e.g. they are |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9032 | physically disconnected), the session timeouts triggers and the session is |
| 9033 | closed. But it will remain in FIN_WAIT1 state for some time in the system, |
| 9034 | using some resources and possibly limiting the ability to establish newer |
| 9035 | connections. |
| 9036 | |
| 9037 | When this happens, it is possible to activate "option nolinger" which forces |
| 9038 | the system to immediately remove any socket's pending data on close. Thus, |
Willy Tarreau | 4a32103 | 2020-10-16 04:55:19 +0200 | [diff] [blame] | 9039 | a TCP RST is emitted, any pending data are truncated, and the session is |
| 9040 | instantly purged from the system's tables. The generally visible effect for |
| 9041 | a client is that responses are truncated if the close happens with a last |
| 9042 | block of data (e.g. on a redirect or error response). On the server side, |
| 9043 | it may help release the source ports immediately when forwarding a client |
| 9044 | aborts in tunnels. In both cases, TCP resets are emitted and given that |
| 9045 | the session is instantly destroyed, there will be no retransmit. On a lossy |
| 9046 | network this can increase problems, especially when there is a firewall on |
| 9047 | the lossy side, because the firewall might see and process the reset (hence |
| 9048 | purge its session) and block any further traffic for this session,, including |
| 9049 | retransmits from the other side. So if the other side doesn't receive it, |
| 9050 | it will never receive any RST again, and the firewall might log many blocked |
| 9051 | packets. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9052 | |
Willy Tarreau | 4a32103 | 2020-10-16 04:55:19 +0200 | [diff] [blame] | 9053 | For all these reasons, it is strongly recommended NOT to use this option, |
| 9054 | unless absolutely needed as a last resort. In most situations, using the |
| 9055 | "client-fin" or "server-fin" timeouts achieves similar results with a more |
| 9056 | reliable behavior. On Linux it's also possible to use the "tcp-ut" bind or |
| 9057 | server setting. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9058 | |
| 9059 | This option may be used both on frontends and backends, depending on the side |
| 9060 | where it is required. Use it on the frontend for clients, and on the backend |
Willy Tarreau | 4a32103 | 2020-10-16 04:55:19 +0200 | [diff] [blame] | 9061 | for servers. While this option is technically supported in "defaults" |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 9062 | sections, it must really not be used there as it risks to accidentally |
Willy Tarreau | 4a32103 | 2020-10-16 04:55:19 +0200 | [diff] [blame] | 9063 | propagate to sections that must no use it and to cause problems there. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9064 | |
| 9065 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9066 | in a specific instance by prepending the "no" keyword before it. |
| 9067 | |
Willy Tarreau | 4a32103 | 2020-10-16 04:55:19 +0200 | [diff] [blame] | 9068 | See also: "timeout client-fin", "timeout server-fin", "tcp-ut" bind or server |
| 9069 | keywords. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9070 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9071 | option originalto [ except <network> ] [ header <name> ] |
| 9072 | Enable insertion of the X-Original-To header to requests sent to servers |
| 9073 | May be used in sections : defaults | frontend | listen | backend |
| 9074 | yes | yes | yes | yes |
| 9075 | Arguments : |
| 9076 | <network> is an optional argument used to disable this option for sources |
| 9077 | matching <network> |
| 9078 | <name> an optional argument to specify a different "X-Original-To" |
| 9079 | header name. |
| 9080 | |
| 9081 | Since HAProxy can work in transparent mode, every request from a client can |
| 9082 | be redirected to the proxy and HAProxy itself can proxy every request to a |
| 9083 | complex SQUID environment and the destination host from SO_ORIGINAL_DST will |
| 9084 | be lost. This is annoying when you want access rules based on destination ip |
| 9085 | addresses. To solve this problem, a new HTTP header "X-Original-To" may be |
| 9086 | added by HAProxy to all requests sent to the server. This header contains a |
| 9087 | value representing the original destination IP address. Since this must be |
| 9088 | configured to always use the last occurrence of this header only. Note that |
| 9089 | only the last occurrence of the header must be used, since it is really |
| 9090 | possible that the client has already brought one. |
| 9091 | |
| 9092 | The keyword "header" may be used to supply a different header name to replace |
| 9093 | the default "X-Original-To". This can be useful where you might already |
| 9094 | have a "X-Original-To" header from a different application, and you need |
| 9095 | preserve it. Also if your backend server doesn't use the "X-Original-To" |
| 9096 | header and requires different one. |
| 9097 | |
| 9098 | Sometimes, a same HAProxy instance may be shared between a direct client |
| 9099 | access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| 9100 | used to decrypt HTTPS traffic). It is possible to disable the addition of the |
Amaury Denoyelle | f8b4292 | 2021-03-04 18:41:14 +0100 | [diff] [blame] | 9101 | header for a known destination address or network by adding the "except" |
| 9102 | keyword followed by the network address. In this case, any destination IP |
| 9103 | matching the network will not cause an addition of this header. Most common |
| 9104 | uses are with private networks or 127.0.0.1. IPv4 and IPv6 are both |
| 9105 | supported. |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9106 | |
| 9107 | This option may be specified either in the frontend or in the backend. If at |
| 9108 | least one of them uses it, the header will be added. Note that the backend's |
| 9109 | setting of the header subargument takes precedence over the frontend's if |
| 9110 | both are defined. |
| 9111 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9112 | Examples : |
| 9113 | # Original Destination address |
| 9114 | frontend www |
| 9115 | mode http |
| 9116 | option originalto except 127.0.0.1 |
| 9117 | |
| 9118 | # Those servers want the IP Address in X-Client-Dst |
| 9119 | backend www |
| 9120 | mode http |
| 9121 | option originalto header X-Client-Dst |
| 9122 | |
Christopher Faulet | 315b39c | 2018-09-21 16:26:19 +0200 | [diff] [blame] | 9123 | See also : "option httpclose", "option http-server-close". |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 9124 | |
| 9125 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9126 | option persist |
| 9127 | no option persist |
| 9128 | Enable or disable forced persistence on down servers |
| 9129 | May be used in sections: defaults | frontend | listen | backend |
| 9130 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 9131 | Arguments : none |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9132 | |
| 9133 | When an HTTP request reaches a backend with a cookie which references a dead |
| 9134 | server, by default it is redispatched to another server. It is possible to |
| 9135 | force the request to be sent to the dead server first using "option persist" |
| 9136 | if absolutely needed. A common use case is when servers are under extreme |
| 9137 | load and spend their time flapping. In this case, the users would still be |
| 9138 | directed to the server they opened the session on, in the hope they would be |
| 9139 | correctly served. It is recommended to use "option redispatch" in conjunction |
| 9140 | with this option so that in the event it would not be possible to connect to |
| 9141 | the server at all (server definitely dead), the client would finally be |
| 9142 | redirected to another valid server. |
| 9143 | |
| 9144 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9145 | in a specific instance by prepending the "no" keyword before it. |
| 9146 | |
Willy Tarreau | 4de9149 | 2010-01-22 19:10:05 +0100 | [diff] [blame] | 9147 | See also : "option redispatch", "retries", "force-persist" |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9148 | |
| 9149 | |
Willy Tarreau | 0c12282 | 2013-12-15 18:49:01 +0100 | [diff] [blame] | 9150 | option pgsql-check [ user <username> ] |
| 9151 | Use PostgreSQL health checks for server testing |
| 9152 | May be used in sections : defaults | frontend | listen | backend |
| 9153 | yes | no | yes | yes |
| 9154 | Arguments : |
| 9155 | <username> This is the username which will be used when connecting to |
| 9156 | PostgreSQL server. |
| 9157 | |
| 9158 | The check sends a PostgreSQL StartupMessage and waits for either |
| 9159 | Authentication request or ErrorResponse message. It is a basic but useful |
| 9160 | test which does not produce error nor aborted connect on the server. |
| 9161 | This check is identical with the "mysql-check". |
| 9162 | |
| 9163 | See also: "option httpchk" |
| 9164 | |
| 9165 | |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 9166 | option prefer-last-server |
| 9167 | no option prefer-last-server |
| 9168 | Allow multiple load balanced requests to remain on the same server |
| 9169 | May be used in sections: defaults | frontend | listen | backend |
| 9170 | yes | no | yes | yes |
| 9171 | Arguments : none |
| 9172 | |
| 9173 | When the load balancing algorithm in use is not deterministic, and a previous |
| 9174 | request was sent to a server to which haproxy still holds a connection, it is |
| 9175 | sometimes desirable that subsequent requests on a same session go to the same |
| 9176 | server as much as possible. Note that this is different from persistence, as |
| 9177 | we only indicate a preference which haproxy tries to apply without any form |
| 9178 | of warranty. The real use is for keep-alive connections sent to servers. When |
| 9179 | this option is used, haproxy will try to reuse the same connection that is |
| 9180 | attached to the server instead of rebalancing to another server, causing a |
| 9181 | 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] | 9182 | not make much sense to use this in combination with hashing algorithms. Note, |
| 9183 | haproxy already automatically tries to stick to a server which sends a 401 or |
Lukas Tribus | 80512b1 | 2018-10-27 20:07:40 +0200 | [diff] [blame] | 9184 | to a proxy which sends a 407 (authentication required), when the load |
| 9185 | balancing algorithm is not deterministic. This is mandatory for use with the |
| 9186 | broken NTLM authentication challenge, and significantly helps in |
Willy Tarreau | 068621e | 2013-12-23 15:11:25 +0100 | [diff] [blame] | 9187 | troubleshooting some faulty applications. Option prefer-last-server might be |
| 9188 | desirable in these environments as well, to avoid redistributing the traffic |
| 9189 | after every other response. |
Willy Tarreau | 9420b12 | 2013-12-15 18:58:25 +0100 | [diff] [blame] | 9190 | |
| 9191 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9192 | in a specific instance by prepending the "no" keyword before it. |
| 9193 | |
| 9194 | See also: "option http-keep-alive" |
| 9195 | |
| 9196 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9197 | option redispatch |
Joseph Lynch | 726ab71 | 2015-05-11 23:25:34 -0700 | [diff] [blame] | 9198 | option redispatch <interval> |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9199 | no option redispatch |
| 9200 | Enable or disable session redistribution in case of connection failure |
| 9201 | May be used in sections: defaults | frontend | listen | backend |
| 9202 | yes | no | yes | yes |
Joseph Lynch | 726ab71 | 2015-05-11 23:25:34 -0700 | [diff] [blame] | 9203 | Arguments : |
| 9204 | <interval> The optional integer value that controls how often redispatches |
| 9205 | occur when retrying connections. Positive value P indicates a |
| 9206 | redispatch is desired on every Pth retry, and negative value |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9207 | N indicate a redispatch is desired on the Nth retry prior to the |
Joseph Lynch | 726ab71 | 2015-05-11 23:25:34 -0700 | [diff] [blame] | 9208 | last retry. For example, the default of -1 preserves the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9209 | historical behavior of redispatching on the last retry, a |
Joseph Lynch | 726ab71 | 2015-05-11 23:25:34 -0700 | [diff] [blame] | 9210 | positive value of 1 would indicate a redispatch on every retry, |
| 9211 | and a positive value of 3 would indicate a redispatch on every |
| 9212 | third retry. You can disable redispatches with a value of 0. |
| 9213 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9214 | |
| 9215 | In HTTP mode, if a server designated by a cookie is down, clients may |
| 9216 | definitely stick to it because they cannot flush the cookie, so they will not |
| 9217 | be able to access the service anymore. |
| 9218 | |
Willy Tarreau | 59884a6 | 2019-01-02 14:48:31 +0100 | [diff] [blame] | 9219 | Specifying "option redispatch" will allow the proxy to break cookie or |
| 9220 | consistent hash based persistence and redistribute them to a working server. |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9221 | |
Olivier Carrère | 6e6f59b | 2020-04-15 11:30:18 +0200 | [diff] [blame] | 9222 | Active servers are selected from a subset of the list of available |
| 9223 | servers. Active servers that are not down or in maintenance (i.e., whose |
| 9224 | health is not checked or that have been checked as "up"), are selected in the |
| 9225 | following order: |
| 9226 | |
| 9227 | 1. Any active, non-backup server, if any, or, |
| 9228 | |
| 9229 | 2. If the "allbackups" option is not set, the first backup server in the |
| 9230 | list, or |
| 9231 | |
| 9232 | 3. If the "allbackups" option is set, any backup server. |
| 9233 | |
| 9234 | When a retry occurs, HAProxy tries to select another server than the last |
| 9235 | one. The new server is selected from the current list of servers. |
| 9236 | |
| 9237 | Sometimes, if the list is updated between retries (e.g., if numerous retries |
| 9238 | occur and last longer than the time needed to check that a server is down, |
| 9239 | remove it from the list and fall back on the list of backup servers), |
| 9240 | connections may be redirected to a backup server, though. |
| 9241 | |
Joseph Lynch | 726ab71 | 2015-05-11 23:25:34 -0700 | [diff] [blame] | 9242 | It also allows to retry connections to another server in case of multiple |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9243 | connection failures. Of course, it requires having "retries" set to a nonzero |
| 9244 | value. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 9245 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9246 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9247 | in a specific instance by prepending the "no" keyword before it. |
| 9248 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 9249 | See also : "retries", "force-persist" |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9250 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9251 | |
Hervé COMMOWICK | ec032d6 | 2011-08-05 16:23:48 +0200 | [diff] [blame] | 9252 | option redis-check |
| 9253 | Use redis health checks for server testing |
| 9254 | May be used in sections : defaults | frontend | listen | backend |
| 9255 | yes | no | yes | yes |
| 9256 | Arguments : none |
| 9257 | |
| 9258 | It is possible to test that the server correctly talks REDIS protocol instead |
| 9259 | of just testing that it accepts the TCP connection. When this option is set, |
| 9260 | a PING redis command is sent to the server, and the response is analyzed to |
| 9261 | find the "+PONG" response message. |
| 9262 | |
| 9263 | Example : |
| 9264 | option redis-check |
| 9265 | |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 9266 | See also : "option httpchk", "option tcp-check", "tcp-check expect" |
Hervé COMMOWICK | ec032d6 | 2011-08-05 16:23:48 +0200 | [diff] [blame] | 9267 | |
| 9268 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9269 | option smtpchk |
| 9270 | option smtpchk <hello> <domain> |
| 9271 | Use SMTP health checks for server testing |
| 9272 | May be used in sections : defaults | frontend | listen | backend |
| 9273 | yes | no | yes | yes |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 9274 | Arguments : |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9275 | <hello> is an optional argument. It is the "hello" command to use. It can |
Lukas Tribus | 2793578 | 2018-10-01 02:00:16 +0200 | [diff] [blame] | 9276 | be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9277 | values will be turned into the default command ("HELO"). |
| 9278 | |
| 9279 | <domain> is the domain name to present to the server. It may only be |
| 9280 | specified (and is mandatory) if the hello command has been |
| 9281 | specified. By default, "localhost" is used. |
| 9282 | |
| 9283 | When "option smtpchk" is set, the health checks will consist in TCP |
| 9284 | connections followed by an SMTP command. By default, this command is |
| 9285 | "HELO localhost". The server's return code is analyzed and only return codes |
| 9286 | starting with a "2" will be considered as valid. All other responses, |
| 9287 | including a lack of response will constitute an error and will indicate a |
| 9288 | dead server. |
| 9289 | |
| 9290 | This test is meant to be used with SMTP servers or relays. Depending on the |
| 9291 | request, it is possible that some servers do not log each connection attempt, |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9292 | so you may want to experiment to improve the behavior. Using telnet on port |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9293 | 25 is often easier than adjusting the configuration. |
| 9294 | |
| 9295 | Most often, an incoming SMTP server needs to see the client's IP address for |
| 9296 | various purposes, including spam filtering, anti-spoofing and logging. When |
| 9297 | possible, it is often wise to masquerade the client's IP address when |
| 9298 | connecting to the server using the "usesrc" argument of the "source" keyword, |
Willy Tarreau | 29fbe51 | 2015-08-20 19:35:14 +0200 | [diff] [blame] | 9299 | which requires the transparent proxy feature to be compiled in. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9300 | |
| 9301 | Example : |
| 9302 | option smtpchk HELO mydomain.org |
| 9303 | |
| 9304 | See also : "option httpchk", "source" |
| 9305 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 9306 | |
Krzysztof Piotr Oledzki | aeebf9b | 2009-10-04 15:43:17 +0200 | [diff] [blame] | 9307 | option socket-stats |
| 9308 | no option socket-stats |
| 9309 | |
| 9310 | Enable or disable collecting & providing separate statistics for each socket. |
| 9311 | May be used in sections : defaults | frontend | listen | backend |
| 9312 | yes | yes | yes | no |
| 9313 | |
| 9314 | Arguments : none |
| 9315 | |
| 9316 | |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 9317 | option splice-auto |
| 9318 | no option splice-auto |
| 9319 | Enable or disable automatic kernel acceleration on sockets in both directions |
| 9320 | May be used in sections : defaults | frontend | listen | backend |
| 9321 | yes | yes | yes | yes |
| 9322 | Arguments : none |
| 9323 | |
| 9324 | When this option is enabled either on a frontend or on a backend, haproxy |
| 9325 | will automatically evaluate the opportunity to use kernel tcp splicing to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9326 | forward data between the client and the server, in either direction. HAProxy |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 9327 | uses heuristics to estimate if kernel splicing might improve performance or |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 9328 | not. Both directions are handled independently. Note that the heuristics used |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 9329 | are not much aggressive in order to limit excessive use of splicing. This |
| 9330 | option requires splicing to be enabled at compile time, and may be globally |
| 9331 | disabled with the global option "nosplice". Since splice uses pipes, using it |
| 9332 | requires that there are enough spare pipes. |
| 9333 | |
| 9334 | Important note: kernel-based TCP splicing is a Linux-specific feature which |
| 9335 | first appeared in kernel 2.6.25. It offers kernel-based acceleration to |
| 9336 | transfer data between sockets without copying these data to user-space, thus |
| 9337 | providing noticeable performance gains and CPU cycles savings. Since many |
| 9338 | early implementations are buggy, corrupt data and/or are inefficient, this |
| 9339 | feature is not enabled by default, and it should be used with extreme care. |
| 9340 | While it is not possible to detect the correctness of an implementation, |
| 9341 | 2.6.29 is the first version offering a properly working implementation. In |
| 9342 | case of doubt, splicing may be globally disabled using the global "nosplice" |
| 9343 | keyword. |
| 9344 | |
| 9345 | Example : |
| 9346 | option splice-auto |
| 9347 | |
| 9348 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9349 | in a specific instance by prepending the "no" keyword before it. |
| 9350 | |
| 9351 | See also : "option splice-request", "option splice-response", and global |
| 9352 | options "nosplice" and "maxpipes" |
| 9353 | |
| 9354 | |
| 9355 | option splice-request |
| 9356 | no option splice-request |
| 9357 | Enable or disable automatic kernel acceleration on sockets for requests |
| 9358 | May be used in sections : defaults | frontend | listen | backend |
| 9359 | yes | yes | yes | yes |
| 9360 | Arguments : none |
| 9361 | |
| 9362 | 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] | 9363 | will use kernel tcp splicing whenever possible to forward data going from |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 9364 | the client to the server. It might still use the recv/send scheme if there |
| 9365 | are no spare pipes left. This option requires splicing to be enabled at |
| 9366 | compile time, and may be globally disabled with the global option "nosplice". |
| 9367 | Since splice uses pipes, using it requires that there are enough spare pipes. |
| 9368 | |
| 9369 | Important note: see "option splice-auto" for usage limitations. |
| 9370 | |
| 9371 | Example : |
| 9372 | option splice-request |
| 9373 | |
| 9374 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9375 | in a specific instance by prepending the "no" keyword before it. |
| 9376 | |
| 9377 | See also : "option splice-auto", "option splice-response", and global options |
| 9378 | "nosplice" and "maxpipes" |
| 9379 | |
| 9380 | |
| 9381 | option splice-response |
| 9382 | no option splice-response |
| 9383 | Enable or disable automatic kernel acceleration on sockets for responses |
| 9384 | May be used in sections : defaults | frontend | listen | backend |
| 9385 | yes | yes | yes | yes |
| 9386 | Arguments : none |
| 9387 | |
| 9388 | 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] | 9389 | will use kernel tcp splicing whenever possible to forward data going from |
Willy Tarreau | ff4f82d | 2009-02-06 11:28:13 +0100 | [diff] [blame] | 9390 | the server to the client. It might still use the recv/send scheme if there |
| 9391 | are no spare pipes left. This option requires splicing to be enabled at |
| 9392 | compile time, and may be globally disabled with the global option "nosplice". |
| 9393 | Since splice uses pipes, using it requires that there are enough spare pipes. |
| 9394 | |
| 9395 | Important note: see "option splice-auto" for usage limitations. |
| 9396 | |
| 9397 | Example : |
| 9398 | option splice-response |
| 9399 | |
| 9400 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9401 | in a specific instance by prepending the "no" keyword before it. |
| 9402 | |
| 9403 | See also : "option splice-auto", "option splice-request", and global options |
| 9404 | "nosplice" and "maxpipes" |
| 9405 | |
| 9406 | |
Christopher Faulet | ba7bc16 | 2016-11-07 21:07:38 +0100 | [diff] [blame] | 9407 | option spop-check |
| 9408 | Use SPOP health checks for server testing |
| 9409 | May be used in sections : defaults | frontend | listen | backend |
| 9410 | no | no | no | yes |
| 9411 | Arguments : none |
| 9412 | |
| 9413 | It is possible to test that the server correctly talks SPOP protocol instead |
| 9414 | of just testing that it accepts the TCP connection. When this option is set, |
| 9415 | a HELLO handshake is performed between HAProxy and the server, and the |
| 9416 | response is analyzed to check no error is reported. |
| 9417 | |
| 9418 | Example : |
| 9419 | option spop-check |
| 9420 | |
| 9421 | See also : "option httpchk" |
| 9422 | |
| 9423 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 9424 | option srvtcpka |
| 9425 | no option srvtcpka |
| 9426 | Enable or disable the sending of TCP keepalive packets on the server side |
| 9427 | May be used in sections : defaults | frontend | listen | backend |
| 9428 | yes | no | yes | yes |
| 9429 | Arguments : none |
| 9430 | |
| 9431 | When there is a firewall or any session-aware component between a client and |
| 9432 | a server, and when the protocol involves very long sessions with long idle |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9433 | periods (e.g. remote desktops), there is a risk that one of the intermediate |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 9434 | components decides to expire a session which has remained idle for too long. |
| 9435 | |
| 9436 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 9437 | to the other end of the connection, leaving it active. The delay between |
| 9438 | keep-alive probes is controlled by the system only and depends both on the |
| 9439 | operating system and its tuning parameters. |
| 9440 | |
| 9441 | It is important to understand that keep-alive packets are neither emitted nor |
| 9442 | received at the application level. It is only the network stacks which sees |
| 9443 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 9444 | to maintain its connection alive, those keep-alive packets will not be |
| 9445 | forwarded to the other side of the proxy. |
| 9446 | |
| 9447 | Please note that this has nothing to do with HTTP keep-alive. |
| 9448 | |
| 9449 | Using option "srvtcpka" enables the emission of TCP keep-alive probes on the |
| 9450 | server side of a connection, which should help when session expirations are |
| 9451 | noticed between HAProxy and a server. |
| 9452 | |
| 9453 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9454 | in a specific instance by prepending the "no" keyword before it. |
| 9455 | |
| 9456 | See also : "option clitcpka", "option tcpka" |
| 9457 | |
| 9458 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9459 | option ssl-hello-chk |
| 9460 | Use SSLv3 client hello health checks for server testing |
| 9461 | May be used in sections : defaults | frontend | listen | backend |
| 9462 | yes | no | yes | yes |
| 9463 | Arguments : none |
| 9464 | |
| 9465 | When some SSL-based protocols are relayed in TCP mode through HAProxy, it is |
| 9466 | possible to test that the server correctly talks SSL instead of just testing |
| 9467 | that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure |
| 9468 | SSLv3 client hello messages are sent once the connection is established to |
| 9469 | the server, and the response is analyzed to find an SSL server hello message. |
| 9470 | The server is considered valid only when the response contains this server |
| 9471 | hello message. |
| 9472 | |
| 9473 | All servers tested till there correctly reply to SSLv3 client hello messages, |
| 9474 | and most servers tested do not even log the requests containing only hello |
| 9475 | messages, which is appreciable. |
| 9476 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 9477 | Note that this check works even when SSL support was not built into haproxy |
| 9478 | because it forges the SSL message. When SSL support is available, it is best |
| 9479 | to use native SSL health checks instead of this one. |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9480 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 9481 | See also: "option httpchk", "check-ssl" |
| 9482 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 9483 | |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9484 | option tcp-check |
| 9485 | Perform health checks using tcp-check send/expect sequences |
| 9486 | May be used in sections: defaults | frontend | listen | backend |
| 9487 | yes | no | yes | yes |
| 9488 | |
| 9489 | This health check method is intended to be combined with "tcp-check" command |
| 9490 | lists in order to support send/expect types of health check sequences. |
| 9491 | |
| 9492 | TCP checks currently support 4 modes of operations : |
| 9493 | - no "tcp-check" directive : the health check only consists in a connection |
| 9494 | attempt, which remains the default mode. |
| 9495 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9496 | - "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] | 9497 | used to send a string along with a connection opening. With some |
| 9498 | protocols, it helps sending a "QUIT" message for example that prevents |
| 9499 | the server from logging a connection error for each health check. The |
| 9500 | check result will still be based on the ability to open the connection |
| 9501 | only. |
| 9502 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9503 | - "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] | 9504 | The connection is opened and haproxy waits for the server to present some |
| 9505 | contents which must validate some rules. The check result will be based |
| 9506 | on the matching between the contents and the rules. This is suited for |
| 9507 | POP, IMAP, SMTP, FTP, SSH, TELNET. |
| 9508 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9509 | - both "tcp-check send" and "tcp-check expect" are mentioned : this is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9510 | used to test a hello-type protocol. HAProxy sends a message, the server |
| 9511 | responds and its response is analyzed. the check result will be based on |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9512 | the matching between the response contents and the rules. This is often |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9513 | suited for protocols which require a binding or a request/response model. |
| 9514 | LDAP, MySQL, Redis and SSL are example of such protocols, though they |
| 9515 | already all have their dedicated checks with a deeper understanding of |
| 9516 | the respective protocols. |
| 9517 | In this mode, many questions may be sent and many answers may be |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9518 | analyzed. |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9519 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 9520 | A fifth mode can be used to insert comments in different steps of the script. |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9521 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 9522 | For each tcp-check rule you create, you can add a "comment" directive, |
| 9523 | followed by a string. This string will be reported in the log and stderr in |
| 9524 | debug mode. It is useful to make user-friendly error reporting. The |
| 9525 | "comment" is of course optional. |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9526 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 9527 | During the execution of a health check, a variable scope is made available to |
| 9528 | store data samples, using the "tcp-check set-var" operation. Freeing those |
| 9529 | variable is possible using "tcp-check unset-var". |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 9530 | |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9531 | |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9532 | Examples : |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9533 | # perform a POP check (analyze only server's banner) |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9534 | option tcp-check |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9535 | tcp-check expect string +OK\ POP3\ ready comment POP\ protocol |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9536 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9537 | # perform an IMAP check (analyze only server's banner) |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9538 | option tcp-check |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9539 | tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9540 | |
| 9541 | # look for the redis master server after ensuring it speaks well |
| 9542 | # redis protocol, then it exits properly. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9543 | # (send a command then analyze the response 3 times) |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9544 | option tcp-check |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9545 | tcp-check comment PING\ phase |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9546 | tcp-check send PING\r\n |
Baptiste Assmann | a332299 | 2015-08-04 10:12:18 +0200 | [diff] [blame] | 9547 | tcp-check expect string +PONG |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9548 | tcp-check comment role\ check |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9549 | tcp-check send info\ replication\r\n |
| 9550 | tcp-check expect string role:master |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9551 | tcp-check comment QUIT\ phase |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9552 | tcp-check send QUIT\r\n |
| 9553 | tcp-check expect string +OK |
| 9554 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9555 | forge a HTTP request, then analyze the response |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9556 | (send many headers before analyzing) |
| 9557 | option tcp-check |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9558 | tcp-check comment forge\ and\ send\ HTTP\ request |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9559 | tcp-check send HEAD\ /\ HTTP/1.1\r\n |
| 9560 | tcp-check send Host:\ www.mydomain.com\r\n |
| 9561 | tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n |
| 9562 | tcp-check send \r\n |
Baptiste Assmann | d60a9e5 | 2015-04-25 16:27:23 +0200 | [diff] [blame] | 9563 | tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9564 | |
| 9565 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 9566 | See also : "tcp-check connect", "tcp-check expect" and "tcp-check send". |
Willy Tarreau | ed17985 | 2013-12-16 01:07:00 +0100 | [diff] [blame] | 9567 | |
| 9568 | |
Willy Tarreau | 9ea05a7 | 2009-06-14 12:07:01 +0200 | [diff] [blame] | 9569 | option tcp-smart-accept |
| 9570 | no option tcp-smart-accept |
| 9571 | Enable or disable the saving of one ACK packet during the accept sequence |
| 9572 | May be used in sections : defaults | frontend | listen | backend |
| 9573 | yes | yes | yes | no |
| 9574 | Arguments : none |
| 9575 | |
| 9576 | When an HTTP connection request comes in, the system acknowledges it on |
| 9577 | behalf of HAProxy, then the client immediately sends its request, and the |
| 9578 | system acknowledges it too while it is notifying HAProxy about the new |
| 9579 | connection. HAProxy then reads the request and responds. This means that we |
| 9580 | have one TCP ACK sent by the system for nothing, because the request could |
| 9581 | very well be acknowledged by HAProxy when it sends its response. |
| 9582 | |
| 9583 | For this reason, in HTTP mode, HAProxy automatically asks the system to avoid |
| 9584 | sending this useless ACK on platforms which support it (currently at least |
| 9585 | Linux). It must not cause any problem, because the system will send it anyway |
| 9586 | after 40 ms if the response takes more time than expected to come. |
| 9587 | |
| 9588 | During complex network debugging sessions, it may be desirable to disable |
| 9589 | this optimization because delayed ACKs can make troubleshooting more complex |
| 9590 | when trying to identify where packets are delayed. It is then possible to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9591 | fall back to normal behavior by specifying "no option tcp-smart-accept". |
Willy Tarreau | 9ea05a7 | 2009-06-14 12:07:01 +0200 | [diff] [blame] | 9592 | |
| 9593 | It is also possible to force it for non-HTTP proxies by simply specifying |
| 9594 | "option tcp-smart-accept". For instance, it can make sense with some services |
| 9595 | such as SMTP where the server speaks first. |
| 9596 | |
| 9597 | It is recommended to avoid forcing this option in a defaults section. In case |
| 9598 | of doubt, consider setting it back to automatic values by prepending the |
| 9599 | "default" keyword before it, or disabling it using the "no" keyword. |
| 9600 | |
Willy Tarreau | d88edf2 | 2009-06-14 15:48:17 +0200 | [diff] [blame] | 9601 | See also : "option tcp-smart-connect" |
| 9602 | |
| 9603 | |
| 9604 | option tcp-smart-connect |
| 9605 | no option tcp-smart-connect |
| 9606 | Enable or disable the saving of one ACK packet during the connect sequence |
| 9607 | May be used in sections : defaults | frontend | listen | backend |
| 9608 | yes | no | yes | yes |
| 9609 | Arguments : none |
| 9610 | |
| 9611 | On certain systems (at least Linux), HAProxy can ask the kernel not to |
| 9612 | immediately send an empty ACK upon a connection request, but to directly |
| 9613 | send the buffer request instead. This saves one packet on the network and |
| 9614 | thus boosts performance. It can also be useful for some servers, because they |
| 9615 | immediately get the request along with the incoming connection. |
| 9616 | |
| 9617 | This feature is enabled when "option tcp-smart-connect" is set in a backend. |
| 9618 | It is not enabled by default because it makes network troubleshooting more |
| 9619 | complex. |
| 9620 | |
| 9621 | It only makes sense to enable it with protocols where the client speaks first |
| 9622 | such as HTTP. In other situations, if there is no data to send in place of |
| 9623 | the ACK, a normal ACK is sent. |
| 9624 | |
| 9625 | If this option has been enabled in a "defaults" section, it can be disabled |
| 9626 | in a specific instance by prepending the "no" keyword before it. |
| 9627 | |
| 9628 | See also : "option tcp-smart-accept" |
| 9629 | |
Willy Tarreau | 9ea05a7 | 2009-06-14 12:07:01 +0200 | [diff] [blame] | 9630 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 9631 | option tcpka |
| 9632 | Enable or disable the sending of TCP keepalive packets on both sides |
| 9633 | May be used in sections : defaults | frontend | listen | backend |
| 9634 | yes | yes | yes | yes |
| 9635 | Arguments : none |
| 9636 | |
| 9637 | When there is a firewall or any session-aware component between a client and |
| 9638 | a server, and when the protocol involves very long sessions with long idle |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9639 | periods (e.g. remote desktops), there is a risk that one of the intermediate |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 9640 | components decides to expire a session which has remained idle for too long. |
| 9641 | |
| 9642 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 9643 | to the other end of the connection, leaving it active. The delay between |
| 9644 | keep-alive probes is controlled by the system only and depends both on the |
| 9645 | operating system and its tuning parameters. |
| 9646 | |
| 9647 | It is important to understand that keep-alive packets are neither emitted nor |
| 9648 | received at the application level. It is only the network stacks which sees |
| 9649 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 9650 | to maintain its connection alive, those keep-alive packets will not be |
| 9651 | forwarded to the other side of the proxy. |
| 9652 | |
| 9653 | Please note that this has nothing to do with HTTP keep-alive. |
| 9654 | |
| 9655 | Using option "tcpka" enables the emission of TCP keep-alive probes on both |
| 9656 | the client and server sides of a connection. Note that this is meaningful |
| 9657 | only in "defaults" or "listen" sections. If this option is used in a |
| 9658 | frontend, only the client side will get keep-alives, and if this option is |
| 9659 | used in a backend, only the server side will get keep-alives. For this |
| 9660 | reason, it is strongly recommended to explicitly use "option clitcpka" and |
| 9661 | "option srvtcpka" when the configuration is split between frontends and |
| 9662 | backends. |
| 9663 | |
| 9664 | See also : "option clitcpka", "option srvtcpka" |
| 9665 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 9666 | |
| 9667 | option tcplog |
| 9668 | Enable advanced logging of TCP connections with session state and timers |
| 9669 | May be used in sections : defaults | frontend | listen | backend |
Tim Duesterhus | 9ad9f35 | 2018-02-05 20:52:27 +0100 | [diff] [blame] | 9670 | yes | yes | yes | no |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 9671 | Arguments : none |
| 9672 | |
| 9673 | By default, the log output format is very poor, as it only contains the |
| 9674 | source and destination addresses, and the instance name. By specifying |
| 9675 | "option tcplog", each log line turns into a much richer format including, but |
| 9676 | not limited to, the connection timers, the session status, the connections |
| 9677 | numbers, the frontend, backend and server name, and of course the source |
| 9678 | address and ports. This option is useful for pure TCP proxies in order to |
| 9679 | find which of the client or server disconnects or times out. For normal HTTP |
| 9680 | proxies, it's better to use "option httplog" which is even more complete. |
| 9681 | |
Guillaume de Lafond | 29f4560 | 2017-03-31 19:52:15 +0200 | [diff] [blame] | 9682 | "option tcplog" overrides any previous "log-format" directive. |
| 9683 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9684 | See also : "option httplog", and section 8 about logging. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 9685 | |
| 9686 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 9687 | option transparent |
| 9688 | no option transparent |
| 9689 | Enable client-side transparent proxying |
| 9690 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 4b1f859 | 2008-12-23 23:13:55 +0100 | [diff] [blame] | 9691 | yes | no | yes | yes |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 9692 | Arguments : none |
| 9693 | |
| 9694 | This option was introduced in order to provide layer 7 persistence to layer 3 |
| 9695 | load balancers. The idea is to use the OS's ability to redirect an incoming |
| 9696 | connection for a remote address to a local process (here HAProxy), and let |
| 9697 | this process know what address was initially requested. When this option is |
| 9698 | used, sessions without cookies will be forwarded to the original destination |
| 9699 | IP address of the incoming request (which should match that of another |
| 9700 | equipment), while requests with cookies will still be forwarded to the |
| 9701 | appropriate server. |
| 9702 | |
| 9703 | Note that contrary to a common belief, this option does NOT make HAProxy |
| 9704 | present the client's IP to the server when establishing the connection. |
| 9705 | |
Willy Tarreau | a114605 | 2011-03-01 09:51:54 +0100 | [diff] [blame] | 9706 | See also: the "usesrc" argument of the "source" keyword, and the |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 9707 | "transparent" option of the "bind" keyword. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 9708 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 9709 | |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 9710 | external-check command <command> |
| 9711 | Executable to run when performing an external-check |
| 9712 | May be used in sections : defaults | frontend | listen | backend |
| 9713 | yes | no | yes | yes |
| 9714 | |
| 9715 | Arguments : |
| 9716 | <command> is the external command to run |
| 9717 | |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 9718 | The arguments passed to the to the command are: |
| 9719 | |
Cyril Bonté | 777be86 | 2014-12-02 21:21:35 +0100 | [diff] [blame] | 9720 | <proxy_address> <proxy_port> <server_address> <server_port> |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 9721 | |
Cyril Bonté | 777be86 | 2014-12-02 21:21:35 +0100 | [diff] [blame] | 9722 | The <proxy_address> and <proxy_port> are derived from the first listener |
| 9723 | that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket |
| 9724 | listener the proxy_address will be the path of the socket and the |
| 9725 | <proxy_port> will be the string "NOT_USED". In a backend section, it's not |
| 9726 | possible to determine a listener, and both <proxy_address> and <proxy_port> |
| 9727 | will have the string value "NOT_USED". |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 9728 | |
Cyril Bonté | 72cda2a | 2014-12-27 22:28:39 +0100 | [diff] [blame] | 9729 | Some values are also provided through environment variables. |
| 9730 | |
| 9731 | Environment variables : |
| 9732 | HAPROXY_PROXY_ADDR The first bind address if available (or empty if not |
| 9733 | applicable, for example in a "backend" section). |
| 9734 | |
| 9735 | HAPROXY_PROXY_ID The backend id. |
| 9736 | |
| 9737 | HAPROXY_PROXY_NAME The backend name. |
| 9738 | |
| 9739 | HAPROXY_PROXY_PORT The first bind port if available (or empty if not |
| 9740 | applicable, for example in a "backend" section or |
| 9741 | for a UNIX socket). |
| 9742 | |
| 9743 | HAPROXY_SERVER_ADDR The server address. |
| 9744 | |
| 9745 | HAPROXY_SERVER_CURCONN The current number of connections on the server. |
| 9746 | |
| 9747 | HAPROXY_SERVER_ID The server id. |
| 9748 | |
| 9749 | HAPROXY_SERVER_MAXCONN The server max connections. |
| 9750 | |
| 9751 | HAPROXY_SERVER_NAME The server name. |
| 9752 | |
| 9753 | HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX |
| 9754 | socket). |
| 9755 | |
| 9756 | PATH The PATH environment variable used when executing |
| 9757 | the command may be set using "external-check path". |
| 9758 | |
William Lallemand | 4d03e43 | 2019-06-14 15:35:37 +0200 | [diff] [blame] | 9759 | See also "2.3. Environment variables" for other variables. |
| 9760 | |
Simon Horman | 98637e5 | 2014-06-20 12:30:16 +0900 | [diff] [blame] | 9761 | If the command executed and exits with a zero status then the check is |
| 9762 | considered to have passed, otherwise the check is considered to have |
| 9763 | failed. |
| 9764 | |
| 9765 | Example : |
| 9766 | external-check command /bin/true |
| 9767 | |
| 9768 | See also : "external-check", "option external-check", "external-check path" |
| 9769 | |
| 9770 | |
| 9771 | external-check path <path> |
| 9772 | The value of the PATH environment variable used when running an external-check |
| 9773 | May be used in sections : defaults | frontend | listen | backend |
| 9774 | yes | no | yes | yes |
| 9775 | |
| 9776 | Arguments : |
| 9777 | <path> is the path used when executing external command to run |
| 9778 | |
| 9779 | The default path is "". |
| 9780 | |
| 9781 | Example : |
| 9782 | external-check path "/usr/bin:/bin" |
| 9783 | |
| 9784 | See also : "external-check", "option external-check", |
| 9785 | "external-check command" |
| 9786 | |
| 9787 | |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9788 | persist rdp-cookie |
Hervé COMMOWICK | a3eb39c | 2011-08-05 18:48:51 +0200 | [diff] [blame] | 9789 | persist rdp-cookie(<name>) |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9790 | Enable RDP cookie-based persistence |
| 9791 | May be used in sections : defaults | frontend | listen | backend |
| 9792 | yes | no | yes | yes |
| 9793 | Arguments : |
| 9794 | <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] | 9795 | default cookie name "msts" will be used. There currently is no |
| 9796 | valid reason to change this name. |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9797 | |
| 9798 | This statement enables persistence based on an RDP cookie. The RDP cookie |
| 9799 | contains all information required to find the server in the list of known |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9800 | servers. So when this option is set in the backend, the request is analyzed |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9801 | and if an RDP cookie is found, it is decoded. If it matches a known server |
| 9802 | which is still UP (or if "option persist" is set), then the connection is |
| 9803 | forwarded to this server. |
| 9804 | |
| 9805 | Note that this only makes sense in a TCP backend, but for this to work, the |
| 9806 | frontend must have waited long enough to ensure that an RDP cookie is present |
| 9807 | 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] | 9808 | 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] | 9809 | a single "listen" section. |
| 9810 | |
Willy Tarreau | 61e28f2 | 2010-05-16 22:31:05 +0200 | [diff] [blame] | 9811 | Also, it is important to understand that the terminal server will emit this |
| 9812 | RDP cookie only if it is configured for "token redirection mode", which means |
| 9813 | that the "IP address redirection" option is disabled. |
| 9814 | |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9815 | Example : |
| 9816 | listen tse-farm |
| 9817 | bind :3389 |
| 9818 | # wait up to 5s for an RDP cookie in the request |
| 9819 | tcp-request inspect-delay 5s |
| 9820 | tcp-request content accept if RDP_COOKIE |
| 9821 | # apply RDP cookie persistence |
| 9822 | persist rdp-cookie |
| 9823 | # if server is unknown, let's balance on the same cookie. |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 9824 | # alternatively, "balance leastconn" may be useful too. |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9825 | balance rdp-cookie |
| 9826 | server srv1 1.1.1.1:3389 |
| 9827 | server srv2 1.1.1.2:3389 |
| 9828 | |
Simon Horman | ab814e0 | 2011-06-24 14:50:20 +0900 | [diff] [blame] | 9829 | See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and |
| 9830 | the rdp_cookie pattern fetch function. |
Emeric Brun | 647caf1 | 2009-06-30 17:57:00 +0200 | [diff] [blame] | 9831 | |
| 9832 | |
Willy Tarreau | 3a7d207 | 2009-03-05 23:48:25 +0100 | [diff] [blame] | 9833 | rate-limit sessions <rate> |
| 9834 | Set a limit on the number of new sessions accepted per second on a frontend |
| 9835 | May be used in sections : defaults | frontend | listen | backend |
| 9836 | yes | yes | yes | no |
| 9837 | Arguments : |
| 9838 | <rate> The <rate> parameter is an integer designating the maximum number |
| 9839 | of new sessions per second to accept on the frontend. |
| 9840 | |
| 9841 | When the frontend reaches the specified number of new sessions per second, it |
| 9842 | stops accepting new connections until the rate drops below the limit again. |
| 9843 | During this time, the pending sessions will be kept in the socket's backlog |
| 9844 | (in system buffers) and haproxy will not even be aware that sessions are |
| 9845 | pending. When applying very low limit on a highly loaded service, it may make |
| 9846 | sense to increase the socket's backlog using the "backlog" keyword. |
| 9847 | |
| 9848 | This feature is particularly efficient at blocking connection-based attacks |
| 9849 | or service abuse on fragile servers. Since the session rate is measured every |
| 9850 | millisecond, it is extremely accurate. Also, the limit applies immediately, |
| 9851 | no delay is needed at all to detect the threshold. |
| 9852 | |
| 9853 | Example : limit the connection rate on SMTP to 10 per second max |
| 9854 | listen smtp |
| 9855 | mode tcp |
| 9856 | bind :25 |
| 9857 | rate-limit sessions 10 |
Panagiotis Panagiotopoulos | 7282d8e | 2016-02-11 16:37:15 +0200 | [diff] [blame] | 9858 | server smtp1 127.0.0.1:1025 |
Willy Tarreau | 3a7d207 | 2009-03-05 23:48:25 +0100 | [diff] [blame] | 9859 | |
Willy Tarreau | a17c2d9 | 2011-07-25 08:16:20 +0200 | [diff] [blame] | 9860 | Note : when the maximum rate is reached, the frontend's status is not changed |
| 9861 | but its sockets appear as "WAITING" in the statistics if the |
| 9862 | "socket-stats" option is enabled. |
Willy Tarreau | 3a7d207 | 2009-03-05 23:48:25 +0100 | [diff] [blame] | 9863 | |
| 9864 | See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion. |
| 9865 | |
| 9866 | |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9867 | redirect location <loc> [code <code>] <option> [{if | unless} <condition>] |
| 9868 | redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>] |
| 9869 | redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>] |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 9870 | Return an HTTP redirection if/unless a condition is matched |
| 9871 | May be used in sections : defaults | frontend | listen | backend |
| 9872 | no | yes | yes | yes |
| 9873 | |
| 9874 | 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] | 9875 | response. If no condition is specified, the redirect applies unconditionally. |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 9876 | |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9877 | Arguments : |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9878 | <loc> With "redirect location", the exact value in <loc> is placed into |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 9879 | the HTTP "Location" header. When used in an "http-request" rule, |
| 9880 | <loc> value follows the log-format rules and can include some |
| 9881 | dynamic values (see Custom Log Format in section 8.2.4). |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9882 | |
| 9883 | <pfx> With "redirect prefix", the "Location" header is built from the |
| 9884 | concatenation of <pfx> and the complete URI path, including the |
| 9885 | query string, unless the "drop-query" option is specified (see |
| 9886 | below). As a special case, if <pfx> equals exactly "/", then |
| 9887 | nothing is inserted before the original URI. It allows one to |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 9888 | redirect to the same URL (for instance, to insert a cookie). When |
| 9889 | used in an "http-request" rule, <pfx> value follows the log-format |
| 9890 | rules and can include some dynamic values (see Custom Log Format |
| 9891 | in section 8.2.4). |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9892 | |
| 9893 | <sch> With "redirect scheme", then the "Location" header is built by |
| 9894 | concatenating <sch> with "://" then the first occurrence of the |
| 9895 | "Host" header, and then the URI path, including the query string |
| 9896 | unless the "drop-query" option is specified (see below). If no |
| 9897 | path is found or if the path is "*", then "/" is used instead. If |
| 9898 | no "Host" header is found, then an empty host component will be |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 9899 | returned, which most recent browsers interpret as redirecting to |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9900 | the same host. This directive is mostly used to redirect HTTP to |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 9901 | HTTPS. When used in an "http-request" rule, <sch> value follows |
| 9902 | the log-format rules and can include some dynamic values (see |
| 9903 | Custom Log Format in section 8.2.4). |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9904 | |
| 9905 | <code> The code is optional. It indicates which type of HTTP redirection |
Willy Tarreau | b67fdc4 | 2013-03-29 19:28:11 +0100 | [diff] [blame] | 9906 | is desired. Only codes 301, 302, 303, 307 and 308 are supported, |
| 9907 | with 302 used by default if no code is specified. 301 means |
| 9908 | "Moved permanently", and a browser may cache the Location. 302 |
Baptiste Assmann | ea849c0 | 2015-08-03 11:42:50 +0200 | [diff] [blame] | 9909 | means "Moved temporarily" and means that the browser should not |
Willy Tarreau | b67fdc4 | 2013-03-29 19:28:11 +0100 | [diff] [blame] | 9910 | cache the redirection. 303 is equivalent to 302 except that the |
| 9911 | browser will fetch the location with a GET method. 307 is just |
| 9912 | like 302 but makes it clear that the same method must be reused. |
| 9913 | Likewise, 308 replaces 301 if the same method must be used. |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9914 | |
| 9915 | <option> There are several options which can be specified to adjust the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 9916 | expected behavior of a redirection : |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9917 | |
| 9918 | - "drop-query" |
| 9919 | When this keyword is used in a prefix-based redirection, then the |
| 9920 | location will be set without any possible query-string, which is useful |
| 9921 | for directing users to a non-secure page for instance. It has no effect |
| 9922 | with a location-type redirect. |
| 9923 | |
Willy Tarreau | 81e3b4f | 2010-01-10 00:42:19 +0100 | [diff] [blame] | 9924 | - "append-slash" |
| 9925 | This keyword may be used in conjunction with "drop-query" to redirect |
| 9926 | users who use a URL not ending with a '/' to the same one with the '/'. |
| 9927 | It can be useful to ensure that search engines will only see one URL. |
| 9928 | For this, a return code 301 is preferred. |
| 9929 | |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9930 | - "set-cookie NAME[=value]" |
| 9931 | A "Set-Cookie" header will be added with NAME (and optionally "=value") |
| 9932 | to the response. This is sometimes used to indicate that a user has |
| 9933 | been seen, for instance to protect against some types of DoS. No other |
| 9934 | cookie option is added, so the cookie will be a session cookie. Note |
| 9935 | that for a browser, a sole cookie name without an equal sign is |
| 9936 | different from a cookie with an equal sign. |
| 9937 | |
| 9938 | - "clear-cookie NAME[=]" |
| 9939 | A "Set-Cookie" header will be added with NAME (and optionally "="), but |
| 9940 | with the "Max-Age" attribute set to zero. This will tell the browser to |
| 9941 | delete this cookie. It is useful for instance on logout pages. It is |
| 9942 | important to note that clearing the cookie "NAME" will not remove a |
| 9943 | cookie set with "NAME=value". You have to clear the cookie "NAME=" for |
| 9944 | that, because the browser makes the difference. |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 9945 | |
| 9946 | Example: move the login URL only to HTTPS. |
| 9947 | acl clear dst_port 80 |
| 9948 | acl secure dst_port 8080 |
| 9949 | acl login_page url_beg /login |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9950 | acl logout url_beg /logout |
Willy Tarreau | 79da469 | 2008-11-19 20:03:04 +0100 | [diff] [blame] | 9951 | acl uid_given url_reg /login?userid=[^&]+ |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9952 | acl cookie_set hdr_sub(cookie) SEEN=1 |
| 9953 | |
| 9954 | redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set |
Willy Tarreau | 79da469 | 2008-11-19 20:03:04 +0100 | [diff] [blame] | 9955 | redirect prefix https://mysite.com if login_page !secure |
| 9956 | redirect prefix http://mysite.com drop-query if login_page !uid_given |
| 9957 | redirect location http://mysite.com/ if !login_page secure |
Willy Tarreau | 0140f25 | 2008-11-19 21:07:09 +0100 | [diff] [blame] | 9958 | redirect location / clear-cookie USERID= if logout |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 9959 | |
Willy Tarreau | 81e3b4f | 2010-01-10 00:42:19 +0100 | [diff] [blame] | 9960 | Example: send redirects for request for articles without a '/'. |
| 9961 | acl missing_slash path_reg ^/article/[^/]*$ |
| 9962 | redirect code 301 prefix / drop-query append-slash if missing_slash |
| 9963 | |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9964 | 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] | 9965 | redirect scheme https if !{ ssl_fc } |
Willy Tarreau | 2e1dca8 | 2012-09-12 08:43:15 +0200 | [diff] [blame] | 9966 | |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 9967 | Example: append 'www.' prefix in front of all hosts not having it |
Coen Rosdorff | 596659b | 2016-04-11 11:33:49 +0200 | [diff] [blame] | 9968 | http-request redirect code 301 location \ |
| 9969 | http://www.%[hdr(host)]%[capture.req.uri] \ |
| 9970 | unless { hdr_beg(host) -i www } |
Thierry FOURNIER | d18cd0f | 2013-11-29 12:15:45 +0100 | [diff] [blame] | 9971 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 9972 | See section 7 about ACL usage. |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 9973 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 9974 | |
Willy Tarreau | e5c5ce9 | 2008-06-20 17:27:19 +0200 | [diff] [blame] | 9975 | retries <value> |
| 9976 | Set the number of retries to perform on a server after a connection failure |
| 9977 | May be used in sections: defaults | frontend | listen | backend |
| 9978 | yes | no | yes | yes |
| 9979 | Arguments : |
| 9980 | <value> is the number of times a connection attempt should be retried on |
| 9981 | a server when a connection either is refused or times out. The |
| 9982 | default value is 3. |
| 9983 | |
| 9984 | It is important to understand that this value applies to the number of |
| 9985 | connection attempts, not full requests. When a connection has effectively |
| 9986 | been established to a server, there will be no more retry. |
| 9987 | |
| 9988 | In order to avoid immediate reconnections to a server which is restarting, |
Joseph Lynch | 726ab71 | 2015-05-11 23:25:34 -0700 | [diff] [blame] | 9989 | a turn-around timer of min("timeout connect", one second) is applied before |
| 9990 | a retry occurs. |
Willy Tarreau | e5c5ce9 | 2008-06-20 17:27:19 +0200 | [diff] [blame] | 9991 | |
| 9992 | When "option redispatch" is set, the last retry may be performed on another |
| 9993 | server even if a cookie references a different server. |
| 9994 | |
| 9995 | See also : "option redispatch" |
| 9996 | |
| 9997 | |
Olivier Houchard | a254a37 | 2019-04-05 15:30:12 +0200 | [diff] [blame] | 9998 | retry-on [list of keywords] |
Jerome Magnin | 5ce3c14 | 2020-05-13 20:09:57 +0200 | [diff] [blame] | 9999 | Specify when to attempt to automatically retry a failed request. |
| 10000 | This setting is only valid when "mode" is set to http and is silently ignored |
| 10001 | otherwise. |
Olivier Houchard | a254a37 | 2019-04-05 15:30:12 +0200 | [diff] [blame] | 10002 | May be used in sections: defaults | frontend | listen | backend |
| 10003 | yes | no | yes | yes |
| 10004 | Arguments : |
| 10005 | <keywords> is a list of keywords or HTTP status codes, each representing a |
| 10006 | type of failure event on which an attempt to retry the request |
| 10007 | is desired. Please read the notes at the bottom before changing |
| 10008 | this setting. The following keywords are supported : |
| 10009 | |
| 10010 | none never retry |
| 10011 | |
| 10012 | conn-failure retry when the connection or the SSL handshake failed |
| 10013 | and the request could not be sent. This is the default. |
| 10014 | |
| 10015 | empty-response retry when the server connection was closed after part |
| 10016 | of the request was sent, and nothing was received from |
| 10017 | the server. This type of failure may be caused by the |
| 10018 | request timeout on the server side, poor network |
| 10019 | condition, or a server crash or restart while |
| 10020 | processing the request. |
| 10021 | |
Olivier Houchard | e3249a9 | 2019-05-03 23:01:47 +0200 | [diff] [blame] | 10022 | junk-response retry when the server returned something not looking |
| 10023 | like a complete HTTP response. This includes partial |
| 10024 | responses headers as well as non-HTTP contents. It |
| 10025 | usually is a bad idea to retry on such events, which |
| 10026 | may be caused a configuration issue (wrong server port) |
| 10027 | or by the request being harmful to the server (buffer |
| 10028 | overflow attack for example). |
| 10029 | |
Olivier Houchard | a254a37 | 2019-04-05 15:30:12 +0200 | [diff] [blame] | 10030 | response-timeout the server timeout stroke while waiting for the server |
| 10031 | to respond to the request. This may be caused by poor |
| 10032 | network condition, the reuse of an idle connection |
| 10033 | which has expired on the path, or by the request being |
| 10034 | extremely expensive to process. It generally is a bad |
| 10035 | idea to retry on such events on servers dealing with |
| 10036 | heavy database processing (full scans, etc) as it may |
| 10037 | amplify denial of service attacks. |
| 10038 | |
Olivier Houchard | 865d839 | 2019-05-03 22:46:27 +0200 | [diff] [blame] | 10039 | 0rtt-rejected retry requests which were sent over early data and were |
| 10040 | rejected by the server. These requests are generally |
| 10041 | considered to be safe to retry. |
| 10042 | |
Julien Pivotto | 2de240a | 2020-11-12 11:14:05 +0100 | [diff] [blame] | 10043 | <status> any HTTP status code among "401" (Unauthorized), "403" |
| 10044 | (Forbidden), "404" (Not Found), "408" (Request Timeout), |
| 10045 | "425" (Too Early), "500" (Server Error), "501" (Not |
| 10046 | Implemented), "502" (Bad Gateway), "503" (Service |
| 10047 | Unavailable), "504" (Gateway Timeout). |
Olivier Houchard | a254a37 | 2019-04-05 15:30:12 +0200 | [diff] [blame] | 10048 | |
Olivier Houchard | ddf0e03 | 2019-05-10 18:05:40 +0200 | [diff] [blame] | 10049 | all-retryable-errors |
| 10050 | retry request for any error that are considered |
| 10051 | retryable. This currently activates "conn-failure", |
| 10052 | "empty-response", "junk-response", "response-timeout", |
| 10053 | "0rtt-rejected", "500", "502", "503", and "504". |
| 10054 | |
Olivier Houchard | a254a37 | 2019-04-05 15:30:12 +0200 | [diff] [blame] | 10055 | Using this directive replaces any previous settings with the new ones; it is |
| 10056 | not cumulative. |
| 10057 | |
| 10058 | Please note that using anything other than "none" and "conn-failure" requires |
| 10059 | to allocate a buffer and copy the whole request into it, so it has memory and |
| 10060 | performance impacts. Requests not fitting in a single buffer will never be |
| 10061 | retried (see the global tune.bufsize setting). |
| 10062 | |
| 10063 | You have to make sure the application has a replay protection mechanism built |
| 10064 | in such as a unique transaction IDs passed in requests, or that replaying the |
| 10065 | same request has no consequence, or it is very dangerous to use any retry-on |
| 10066 | value beside "conn-failure" and "none". Static file servers and caches are |
| 10067 | generally considered safe against any type of retry. Using a status code can |
| 10068 | be useful to quickly leave a server showing an abnormal behavior (out of |
| 10069 | memory, file system issues, etc), but in this case it may be a good idea to |
| 10070 | immediately redispatch the connection to another server (please see "option |
| 10071 | redispatch" for this). Last, it is important to understand that most causes |
| 10072 | of failures are the requests themselves and that retrying a request causing a |
| 10073 | server to misbehave will often make the situation even worse for this server, |
| 10074 | or for the whole service in case of redispatch. |
| 10075 | |
| 10076 | Unless you know exactly how the application deals with replayed requests, you |
| 10077 | should not use this directive. |
| 10078 | |
| 10079 | The default is "conn-failure". |
| 10080 | |
| 10081 | See also: "retries", "option redispatch", "tune.bufsize" |
| 10082 | |
David du Colombier | 486df47 | 2011-03-17 10:40:26 +0100 | [diff] [blame] | 10083 | server <name> <address>[:[port]] [param*] |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10084 | Declare a server in a backend |
| 10085 | May be used in sections : defaults | frontend | listen | backend |
| 10086 | no | no | yes | yes |
| 10087 | Arguments : |
| 10088 | <name> is the internal name assigned to this server. This name will |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10089 | appear in logs and alerts. If "http-send-name-header" is |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 10090 | 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] | 10091 | |
David du Colombier | 486df47 | 2011-03-17 10:40:26 +0100 | [diff] [blame] | 10092 | <address> is the IPv4 or IPv6 address of the server. Alternatively, a |
| 10093 | resolvable hostname is supported, but this name will be resolved |
| 10094 | during start-up. Address "0.0.0.0" or "*" has a special meaning. |
| 10095 | It indicates that the connection will be forwarded to the same IP |
Willy Tarreau | d669a4f | 2010-07-13 14:49:50 +0200 | [diff] [blame] | 10096 | address as the one from the client connection. This is useful in |
| 10097 | transparent proxy architectures where the client's connection is |
| 10098 | intercepted and haproxy must forward to the original destination |
| 10099 | address. This is more or less what the "transparent" keyword does |
| 10100 | except that with a server it's possible to limit concurrency and |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 10101 | to report statistics. Optionally, an address family prefix may be |
| 10102 | used before the address to force the family regardless of the |
| 10103 | address format, which can be useful to specify a path to a unix |
| 10104 | socket with no slash ('/'). Currently supported prefixes are : |
| 10105 | - 'ipv4@' -> address is always IPv4 |
| 10106 | - 'ipv6@' -> address is always IPv6 |
| 10107 | - 'unix@' -> address is a path to a local unix socket |
Willy Tarreau | ccfccef | 2014-05-10 01:49:15 +0200 | [diff] [blame] | 10108 | - 'abns@' -> address is in abstract namespace (Linux only) |
William Lallemand | 2fe7dd0 | 2018-09-11 16:51:29 +0200 | [diff] [blame] | 10109 | - 'sockpair@' -> address is the FD of a connected unix |
| 10110 | socket or of a socketpair. During a connection, the |
| 10111 | backend creates a pair of connected sockets, and passes |
| 10112 | one of them over the FD. The bind part will use the |
| 10113 | received socket as the client FD. Should be used |
| 10114 | carefully. |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 10115 | You may want to reference some environment variables in the |
| 10116 | address parameter, see section 2.3 about environment |
Willy Tarreau | 6a031d1 | 2016-11-07 19:42:35 +0100 | [diff] [blame] | 10117 | variables. The "init-addr" setting can be used to modify the way |
| 10118 | IP addresses should be resolved upon startup. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10119 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 10120 | <port> is an optional port specification. If set, all connections will |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10121 | be sent to this port. If unset, the same port the client |
| 10122 | connected to will be used. The port may also be prefixed by a "+" |
| 10123 | or a "-". In this case, the server's port will be determined by |
| 10124 | adding this value to the client's port. |
| 10125 | |
| 10126 | <param*> is a list of parameters for this server. The "server" keywords |
| 10127 | accepts an important number of options and has a complete section |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 10128 | dedicated to it. Please refer to section 5 for more details. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10129 | |
| 10130 | Examples : |
| 10131 | server first 10.1.1.1:1080 cookie first check inter 1000 |
| 10132 | server second 10.1.1.2:1080 cookie second check inter 1000 |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 10133 | server transp ipv4@ |
William Lallemand | b2f0745 | 2015-05-12 14:27:13 +0200 | [diff] [blame] | 10134 | server backup "${SRV_BACKUP}:1080" backup |
| 10135 | server www1_dc1 "${LAN_DC1}.101:80" |
| 10136 | server www1_dc2 "${LAN_DC2}.101:80" |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10137 | |
Willy Tarreau | 55dcaf6 | 2015-09-27 15:03:15 +0200 | [diff] [blame] | 10138 | Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole |
| 10139 | sun_path length is used for the address length. Some other programs |
| 10140 | such as socat use the string length only by default. Pass the option |
| 10141 | ",unix-tightsocklen=0" to any abstract socket definition in socat to |
| 10142 | make it compatible with HAProxy's. |
| 10143 | |
Mark Lamourine | c2247f0 | 2012-01-04 13:02:01 -0500 | [diff] [blame] | 10144 | See also: "default-server", "http-send-name-header" and section 5 about |
| 10145 | server options |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10146 | |
Christopher Faulet | 583b6de | 2021-02-12 09:27:10 +0100 | [diff] [blame] | 10147 | server-state-file-name [ { use-backend-name | <file> } ] |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 10148 | Set the server state file to read, load and apply to servers available in |
Christopher Faulet | 583b6de | 2021-02-12 09:27:10 +0100 | [diff] [blame] | 10149 | this backend. |
| 10150 | May be used in sections: defaults | frontend | listen | backend |
| 10151 | no | no | yes | yes |
| 10152 | |
| 10153 | It only applies when the directive "load-server-state-from-file" is set to |
| 10154 | "local". When <file> is not provided, if "use-backend-name" is used or if |
| 10155 | this directive is not set, then backend name is used. If <file> starts with a |
| 10156 | slash '/', then it is considered as an absolute path. Otherwise, <file> is |
| 10157 | concatenated to the global directive "server-state-base". |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 10158 | |
| 10159 | Example: the minimal configuration below would make HAProxy look for the |
| 10160 | state server file '/etc/haproxy/states/bk': |
| 10161 | |
| 10162 | global |
| 10163 | server-state-file-base /etc/haproxy/states |
| 10164 | |
Willy Tarreau | c9c6cdb | 2020-03-05 16:03:58 +0100 | [diff] [blame] | 10165 | backend bk |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 10166 | load-server-state-from-file |
| 10167 | |
Christopher Faulet | 583b6de | 2021-02-12 09:27:10 +0100 | [diff] [blame] | 10168 | See also: "server-state-base", "load-server-state-from-file", and |
Baptiste Assmann | 01c6cc3 | 2015-08-23 11:45:29 +0200 | [diff] [blame] | 10169 | "show servers state" |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10170 | |
Frédéric Lécaille | cb4502e | 2017-04-20 13:36:25 +0200 | [diff] [blame] | 10171 | server-template <prefix> <num | range> <fqdn>[:<port>] [params*] |
| 10172 | Set a template to initialize servers with shared parameters. |
| 10173 | The names of these servers are built from <prefix> and <num | range> parameters. |
| 10174 | May be used in sections : defaults | frontend | listen | backend |
| 10175 | no | no | yes | yes |
| 10176 | |
| 10177 | Arguments: |
| 10178 | <prefix> A prefix for the server names to be built. |
| 10179 | |
| 10180 | <num | range> |
| 10181 | If <num> is provided, this template initializes <num> servers |
| 10182 | with 1 up to <num> as server name suffixes. A range of numbers |
| 10183 | <num_low>-<num_high> may also be used to use <num_low> up to |
| 10184 | <num_high> as server name suffixes. |
| 10185 | |
| 10186 | <fqdn> A FQDN for all the servers this template initializes. |
| 10187 | |
| 10188 | <port> Same meaning as "server" <port> argument (see "server" keyword). |
| 10189 | |
| 10190 | <params*> |
| 10191 | Remaining server parameters among all those supported by "server" |
| 10192 | keyword. |
| 10193 | |
| 10194 | Examples: |
| 10195 | # Initializes 3 servers with srv1, srv2 and srv3 as names, |
| 10196 | # google.com as FQDN, and health-check enabled. |
| 10197 | server-template srv 1-3 google.com:80 check |
| 10198 | |
| 10199 | # or |
| 10200 | server-template srv 3 google.com:80 check |
| 10201 | |
| 10202 | # would be equivalent to: |
| 10203 | server srv1 google.com:80 check |
| 10204 | server srv2 google.com:80 check |
| 10205 | server srv3 google.com:80 check |
| 10206 | |
| 10207 | |
| 10208 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10209 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 10210 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ] |
Willy Tarreau | d53f96b | 2009-02-04 18:46:54 +0100 | [diff] [blame] | 10211 | source <addr>[:<port>] [interface <name>] |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10212 | Set the source address for outgoing connections |
| 10213 | May be used in sections : defaults | frontend | listen | backend |
| 10214 | yes | no | yes | yes |
| 10215 | Arguments : |
| 10216 | <addr> is the IPv4 address HAProxy will bind to before connecting to a |
| 10217 | server. This address is also used as a source for health checks. |
Willy Tarreau | 2470928 | 2013-03-10 21:32:12 +0100 | [diff] [blame] | 10218 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10219 | 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] | 10220 | the most appropriate address to reach its destination. Optionally |
| 10221 | an address family prefix may be used before the address to force |
| 10222 | the family regardless of the address format, which can be useful |
| 10223 | to specify a path to a unix socket with no slash ('/'). Currently |
| 10224 | supported prefixes are : |
| 10225 | - 'ipv4@' -> address is always IPv4 |
| 10226 | - 'ipv6@' -> address is always IPv6 |
| 10227 | - 'unix@' -> address is a path to a local unix socket |
Willy Tarreau | ccfccef | 2014-05-10 01:49:15 +0200 | [diff] [blame] | 10228 | - 'abns@' -> address is in abstract namespace (Linux only) |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 10229 | You may want to reference some environment variables in the |
| 10230 | address parameter, see section 2.3 about environment variables. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10231 | |
| 10232 | <port> is an optional port. It is normally not needed but may be useful |
| 10233 | in some very specific contexts. The default value of zero means |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 10234 | the system will select a free port. Note that port ranges are not |
| 10235 | supported in the backend. If you want to force port ranges, you |
| 10236 | have to specify them on each "server" line. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10237 | |
| 10238 | <addr2> is the IP address to present to the server when connections are |
| 10239 | forwarded in full transparent proxy mode. This is currently only |
| 10240 | supported on some patched Linux kernels. When this address is |
| 10241 | specified, clients connecting to the server will be presented |
| 10242 | with this address, while health checks will still use the address |
| 10243 | <addr>. |
| 10244 | |
| 10245 | <port2> is the optional port to present to the server when connections |
| 10246 | are forwarded in full transparent proxy mode (see <addr2> above). |
| 10247 | The default value of zero means the system will select a free |
| 10248 | port. |
| 10249 | |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 10250 | <hdr> is the name of a HTTP header in which to fetch the IP to bind to. |
| 10251 | This is the name of a comma-separated header list which can |
| 10252 | contain multiple IP addresses. By default, the last occurrence is |
| 10253 | used. This is designed to work with the X-Forwarded-For header |
Baptiste Assmann | ea3e73b | 2013-02-02 23:47:49 +0100 | [diff] [blame] | 10254 | and to automatically bind to the client's IP address as seen |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 10255 | by previous proxy, typically Stunnel. In order to use another |
| 10256 | occurrence from the last one, please see the <occ> parameter |
| 10257 | below. When the header (or occurrence) is not found, no binding |
| 10258 | is performed so that the proxy's default IP address is used. Also |
| 10259 | keep in mind that the header name is case insensitive, as for any |
| 10260 | HTTP header. |
| 10261 | |
| 10262 | <occ> is the occurrence number of a value to be used in a multi-value |
| 10263 | header. This is to be used in conjunction with "hdr_ip(<hdr>)", |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 10264 | in order to specify which occurrence to use for the source IP |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 10265 | address. Positive values indicate a position from the first |
| 10266 | occurrence, 1 being the first one. Negative values indicate |
| 10267 | positions relative to the last one, -1 being the last one. This |
| 10268 | is helpful for situations where an X-Forwarded-For header is set |
| 10269 | at the entry point of an infrastructure and must be used several |
| 10270 | proxy layers away. When this value is not specified, -1 is |
| 10271 | assumed. Passing a zero here disables the feature. |
| 10272 | |
Willy Tarreau | d53f96b | 2009-02-04 18:46:54 +0100 | [diff] [blame] | 10273 | <name> is an optional interface name to which to bind to for outgoing |
| 10274 | traffic. On systems supporting this features (currently, only |
| 10275 | Linux), this allows one to bind all traffic to the server to |
| 10276 | this interface even if it is not the one the system would select |
| 10277 | based on routing tables. This should be used with extreme care. |
| 10278 | Note that using this option requires root privileges. |
| 10279 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10280 | The "source" keyword is useful in complex environments where a specific |
| 10281 | address only is allowed to connect to the servers. It may be needed when a |
| 10282 | private address must be used through a public gateway for instance, and it is |
| 10283 | known that the system cannot determine the adequate source address by itself. |
| 10284 | |
| 10285 | An extension which is available on certain patched Linux kernels may be used |
| 10286 | through the "usesrc" optional keyword. It makes it possible to connect to the |
| 10287 | servers with an IP address which does not belong to the system itself. This |
| 10288 | is called "full transparent proxy mode". For this to work, the destination |
| 10289 | servers have to route their traffic back to this address through the machine |
| 10290 | running HAProxy, and IP forwarding must generally be enabled on this machine. |
| 10291 | |
| 10292 | In this "full transparent proxy" mode, it is possible to force a specific IP |
| 10293 | address to be presented to the servers. This is not much used in fact. A more |
| 10294 | common use is to tell HAProxy to present the client's IP address. For this, |
| 10295 | there are two methods : |
| 10296 | |
| 10297 | - present the client's IP and port addresses. This is the most transparent |
| 10298 | mode, but it can cause problems when IP connection tracking is enabled on |
| 10299 | the machine, because a same connection may be seen twice with different |
| 10300 | states. However, this solution presents the huge advantage of not |
| 10301 | limiting the system to the 64k outgoing address+port couples, because all |
| 10302 | of the client ranges may be used. |
| 10303 | |
| 10304 | - present only the client's IP address and select a spare port. This |
| 10305 | solution is still quite elegant but slightly less transparent (downstream |
| 10306 | firewalls logs will not match upstream's). It also presents the downside |
| 10307 | of limiting the number of concurrent connections to the usual 64k ports. |
| 10308 | However, since the upstream and downstream ports are different, local IP |
| 10309 | connection tracking on the machine will not be upset by the reuse of the |
| 10310 | same session. |
| 10311 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10312 | This option sets the default source for all servers in the backend. It may |
| 10313 | also be specified in a "defaults" section. Finer source address specification |
| 10314 | 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] | 10315 | section 5 for more information. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10316 | |
Baptiste Assmann | 91bd337 | 2015-07-17 21:59:42 +0200 | [diff] [blame] | 10317 | In order to work, "usesrc" requires root privileges. |
| 10318 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10319 | Examples : |
| 10320 | backend private |
| 10321 | # Connect to the servers using our 192.168.1.200 source address |
| 10322 | source 192.168.1.200 |
| 10323 | |
| 10324 | backend transparent_ssl1 |
| 10325 | # Connect to the SSL farm from the client's source address |
| 10326 | source 192.168.1.200 usesrc clientip |
| 10327 | |
| 10328 | backend transparent_ssl2 |
| 10329 | # Connect to the SSL farm from the client's source address and port |
| 10330 | # not recommended if IP conntrack is present on the local machine. |
| 10331 | source 192.168.1.200 usesrc client |
| 10332 | |
| 10333 | backend transparent_ssl3 |
| 10334 | # Connect to the SSL farm from the client's source address. It |
| 10335 | # is more conntrack-friendly. |
| 10336 | source 192.168.1.200 usesrc clientip |
| 10337 | |
| 10338 | backend transparent_smtp |
| 10339 | # Connect to the SMTP farm from the client's source address/port |
| 10340 | # with Tproxy version 4. |
| 10341 | source 0.0.0.0 usesrc clientip |
| 10342 | |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 10343 | backend transparent_http |
| 10344 | # Connect to the servers using the client's IP as seen by previous |
| 10345 | # proxy. |
| 10346 | source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1) |
| 10347 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 10348 | 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] | 10349 | the Linux kernel on www.balabit.com, the "bind" keyword. |
| 10350 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 10351 | |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 10352 | srvtcpka-cnt <count> |
| 10353 | Sets the maximum number of keepalive probes TCP should send before dropping |
| 10354 | the connection on the server side. |
| 10355 | May be used in sections : defaults | frontend | listen | backend |
| 10356 | yes | no | yes | yes |
| 10357 | Arguments : |
| 10358 | <count> is the maximum number of keepalive probes. |
| 10359 | |
| 10360 | This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword |
| 10361 | is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used. |
Willy Tarreau | 5254321 | 2020-07-09 05:58:51 +0200 | [diff] [blame] | 10362 | The availability of this setting depends on the operating system. It is |
| 10363 | known to work on Linux. |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 10364 | |
| 10365 | See also : "option srvtcpka", "srvtcpka-idle", "srvtcpka-intvl". |
| 10366 | |
| 10367 | |
| 10368 | srvtcpka-idle <timeout> |
| 10369 | Sets the time the connection needs to remain idle before TCP starts sending |
| 10370 | keepalive probes, if enabled the sending of TCP keepalive packets on the |
| 10371 | server side. |
| 10372 | May be used in sections : defaults | frontend | listen | backend |
| 10373 | yes | no | yes | yes |
| 10374 | Arguments : |
| 10375 | <timeout> is the time the connection needs to remain idle before TCP starts |
| 10376 | sending keepalive probes. It is specified in seconds by default, |
| 10377 | but can be in any other unit if the number is suffixed by the |
| 10378 | unit, as explained at the top of this document. |
| 10379 | |
| 10380 | This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword |
| 10381 | is not specified, system-wide TCP parameter (tcp_keepalive_time) is used. |
Willy Tarreau | 5254321 | 2020-07-09 05:58:51 +0200 | [diff] [blame] | 10382 | The availability of this setting depends on the operating system. It is |
| 10383 | known to work on Linux. |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 10384 | |
| 10385 | See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-intvl". |
| 10386 | |
| 10387 | |
| 10388 | srvtcpka-intvl <timeout> |
| 10389 | Sets the time between individual keepalive probes on the server side. |
| 10390 | May be used in sections : defaults | frontend | listen | backend |
| 10391 | yes | no | yes | yes |
| 10392 | Arguments : |
| 10393 | <timeout> is the time between individual keepalive probes. It is specified |
| 10394 | in seconds by default, but can be in any other unit if the number |
| 10395 | is suffixed by the unit, as explained at the top of this |
| 10396 | document. |
| 10397 | |
| 10398 | This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword |
| 10399 | is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used. |
Willy Tarreau | 5254321 | 2020-07-09 05:58:51 +0200 | [diff] [blame] | 10400 | The availability of this setting depends on the operating system. It is |
| 10401 | known to work on Linux. |
MIZUTA Takeshi | b24bc0d | 2020-07-09 11:13:20 +0900 | [diff] [blame] | 10402 | |
| 10403 | See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-idle". |
| 10404 | |
| 10405 | |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 10406 | stats admin { if | unless } <cond> |
| 10407 | Enable statistics admin level if/unless a condition is matched |
| 10408 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10409 | no | yes | yes | yes |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 10410 | |
| 10411 | This statement enables the statistics admin level if/unless a condition is |
| 10412 | matched. |
| 10413 | |
| 10414 | The admin level allows to enable/disable servers from the web interface. By |
| 10415 | default, statistics page is read-only for security reasons. |
| 10416 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10417 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 10418 | unless you know what you do : memory is not shared between the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10419 | processes, which can result in random behaviors. |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10420 | |
Cyril Bonté | 23b39d9 | 2011-02-10 22:54:44 +0100 | [diff] [blame] | 10421 | Currently, the POST request is limited to the buffer size minus the reserved |
| 10422 | buffer space, which means that if the list of servers is too long, the |
| 10423 | request won't be processed. It is recommended to alter few servers at a |
| 10424 | time. |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 10425 | |
| 10426 | Example : |
| 10427 | # statistics admin level only for localhost |
| 10428 | backend stats_localhost |
| 10429 | stats enable |
| 10430 | stats admin if LOCALHOST |
| 10431 | |
| 10432 | Example : |
| 10433 | # statistics admin level always enabled because of the authentication |
| 10434 | backend stats_auth |
| 10435 | stats enable |
| 10436 | stats auth admin:AdMiN123 |
| 10437 | stats admin if TRUE |
| 10438 | |
| 10439 | Example : |
| 10440 | # statistics admin level depends on the authenticated user |
| 10441 | userlist stats-auth |
| 10442 | group admin users admin |
| 10443 | user admin insecure-password AdMiN123 |
| 10444 | group readonly users haproxy |
| 10445 | user haproxy insecure-password haproxy |
| 10446 | |
| 10447 | backend stats_auth |
| 10448 | stats enable |
| 10449 | acl AUTH http_auth(stats-auth) |
| 10450 | acl AUTH_ADMIN http_auth_group(stats-auth) admin |
| 10451 | stats http-request auth unless AUTH |
| 10452 | stats admin if AUTH_ADMIN |
| 10453 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10454 | See also : "stats enable", "stats auth", "stats http-request", "nbproc", |
| 10455 | "bind-process", section 3.4 about userlists and section 7 about |
| 10456 | ACL usage. |
Cyril Bonté | 66c327d | 2010-10-12 00:14:37 +0200 | [diff] [blame] | 10457 | |
| 10458 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10459 | stats auth <user>:<passwd> |
| 10460 | Enable statistics with authentication and grant access to an account |
| 10461 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10462 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10463 | Arguments : |
| 10464 | <user> is a user name to grant access to |
| 10465 | |
| 10466 | <passwd> is the cleartext password associated to this user |
| 10467 | |
| 10468 | This statement enables statistics with default settings, and restricts access |
| 10469 | to declared users only. It may be repeated as many times as necessary to |
| 10470 | allow as many users as desired. When a user tries to access the statistics |
| 10471 | without a valid account, a "401 Forbidden" response will be returned so that |
| 10472 | the browser asks the user to provide a valid user and password. The real |
| 10473 | which will be returned to the browser is configurable using "stats realm". |
| 10474 | |
| 10475 | Since the authentication method is HTTP Basic Authentication, the passwords |
| 10476 | circulate in cleartext on the network. Thus, it was decided that the |
| 10477 | configuration file would also use cleartext passwords to remind the users |
Willy Tarreau | 3c92c5f | 2011-08-28 09:45:47 +0200 | [diff] [blame] | 10478 | 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] | 10479 | |
| 10480 | It is also possible to reduce the scope of the proxies which appear in the |
| 10481 | report using "stats scope". |
| 10482 | |
| 10483 | Though this statement alone is enough to enable statistics reporting, it is |
| 10484 | recommended to set all other settings in order to avoid relying on default |
| 10485 | unobvious parameters. |
| 10486 | |
| 10487 | Example : |
| 10488 | # public access (limited to this backend only) |
| 10489 | backend public_www |
| 10490 | server srv1 192.168.0.1:80 |
| 10491 | stats enable |
| 10492 | stats hide-version |
| 10493 | stats scope . |
| 10494 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10495 | stats realm HAProxy\ Statistics |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10496 | stats auth admin1:AdMiN123 |
| 10497 | stats auth admin2:AdMiN321 |
| 10498 | |
| 10499 | # internal monitoring access (unlimited) |
| 10500 | backend private_monitoring |
| 10501 | stats enable |
| 10502 | stats uri /admin?stats |
| 10503 | stats refresh 5s |
| 10504 | |
| 10505 | See also : "stats enable", "stats realm", "stats scope", "stats uri" |
| 10506 | |
| 10507 | |
| 10508 | stats enable |
| 10509 | Enable statistics reporting with default settings |
| 10510 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10511 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10512 | Arguments : none |
| 10513 | |
| 10514 | This statement enables statistics reporting with default settings defined |
| 10515 | at build time. Unless stated otherwise, these settings are used : |
| 10516 | - stats uri : /haproxy?stats |
| 10517 | - stats realm : "HAProxy Statistics" |
| 10518 | - stats auth : no authentication |
| 10519 | - stats scope : no restriction |
| 10520 | |
| 10521 | Though this statement alone is enough to enable statistics reporting, it is |
| 10522 | recommended to set all other settings in order to avoid relying on default |
| 10523 | unobvious parameters. |
| 10524 | |
| 10525 | Example : |
| 10526 | # public access (limited to this backend only) |
| 10527 | backend public_www |
| 10528 | server srv1 192.168.0.1:80 |
| 10529 | stats enable |
| 10530 | stats hide-version |
| 10531 | stats scope . |
| 10532 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10533 | stats realm HAProxy\ Statistics |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10534 | stats auth admin1:AdMiN123 |
| 10535 | stats auth admin2:AdMiN321 |
| 10536 | |
| 10537 | # internal monitoring access (unlimited) |
| 10538 | backend private_monitoring |
| 10539 | stats enable |
| 10540 | stats uri /admin?stats |
| 10541 | stats refresh 5s |
| 10542 | |
| 10543 | See also : "stats auth", "stats realm", "stats uri" |
| 10544 | |
| 10545 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10546 | stats hide-version |
| 10547 | Enable statistics and hide HAProxy version reporting |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 10548 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10549 | yes | yes | yes | yes |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10550 | Arguments : none |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 10551 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10552 | By default, the stats page reports some useful status information along with |
| 10553 | the statistics. Among them is HAProxy's version. However, it is generally |
| 10554 | considered dangerous to report precise version to anyone, as it can help them |
| 10555 | target known weaknesses with specific attacks. The "stats hide-version" |
| 10556 | statement removes the version from the statistics report. This is recommended |
| 10557 | for public sites or any site with a weak login/password. |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 10558 | |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 10559 | Though this statement alone is enough to enable statistics reporting, it is |
| 10560 | recommended to set all other settings in order to avoid relying on default |
| 10561 | unobvious parameters. |
| 10562 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10563 | Example : |
| 10564 | # public access (limited to this backend only) |
| 10565 | backend public_www |
| 10566 | server srv1 192.168.0.1:80 |
Krzysztof Piotr Oledzki | 48cb2ae | 2009-10-02 22:51:14 +0200 | [diff] [blame] | 10567 | stats enable |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10568 | stats hide-version |
| 10569 | stats scope . |
| 10570 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10571 | stats realm HAProxy\ Statistics |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10572 | stats auth admin1:AdMiN123 |
| 10573 | stats auth admin2:AdMiN321 |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 10574 | |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 10575 | # internal monitoring access (unlimited) |
| 10576 | backend private_monitoring |
| 10577 | stats enable |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10578 | stats uri /admin?stats |
| 10579 | stats refresh 5s |
Krzysztof Piotr Oledzki | 15514c2 | 2010-01-04 16:03:09 +0100 | [diff] [blame] | 10580 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10581 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
Willy Tarreau | 1d45b7c | 2009-08-16 10:29:18 +0200 | [diff] [blame] | 10582 | |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 10583 | |
Cyril Bonté | 2be1b3f | 2010-09-30 23:46:30 +0200 | [diff] [blame] | 10584 | stats http-request { allow | deny | auth [realm <realm>] } |
| 10585 | [ { if | unless } <condition> ] |
| 10586 | Access control for statistics |
| 10587 | |
| 10588 | May be used in sections: defaults | frontend | listen | backend |
| 10589 | no | no | yes | yes |
| 10590 | |
| 10591 | As "http-request", these set of options allow to fine control access to |
| 10592 | statistics. Each option may be followed by if/unless and acl. |
| 10593 | First option with matched condition (or option without condition) is final. |
| 10594 | For "deny" a 403 error will be returned, for "allow" normal processing is |
| 10595 | performed, for "auth" a 401/407 error code is returned so the client |
| 10596 | should be asked to enter a username and password. |
| 10597 | |
| 10598 | There is no fixed limit to the number of http-request statements per |
| 10599 | instance. |
| 10600 | |
| 10601 | See also : "http-request", section 3.4 about userlists and section 7 |
| 10602 | about ACL usage. |
| 10603 | |
| 10604 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10605 | stats realm <realm> |
| 10606 | Enable statistics and set authentication realm |
| 10607 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10608 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10609 | Arguments : |
| 10610 | <realm> is the name of the HTTP Basic Authentication realm reported to |
| 10611 | the browser. The browser uses it to display it in the pop-up |
| 10612 | inviting the user to enter a valid username and password. |
| 10613 | |
| 10614 | The realm is read as a single word, so any spaces in it should be escaped |
| 10615 | using a backslash ('\'). |
| 10616 | |
| 10617 | This statement is useful only in conjunction with "stats auth" since it is |
| 10618 | only related to authentication. |
| 10619 | |
| 10620 | Though this statement alone is enough to enable statistics reporting, it is |
| 10621 | recommended to set all other settings in order to avoid relying on default |
| 10622 | unobvious parameters. |
| 10623 | |
| 10624 | Example : |
| 10625 | # public access (limited to this backend only) |
| 10626 | backend public_www |
| 10627 | server srv1 192.168.0.1:80 |
| 10628 | stats enable |
| 10629 | stats hide-version |
| 10630 | stats scope . |
| 10631 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10632 | stats realm HAProxy\ Statistics |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10633 | stats auth admin1:AdMiN123 |
| 10634 | stats auth admin2:AdMiN321 |
| 10635 | |
| 10636 | # internal monitoring access (unlimited) |
| 10637 | backend private_monitoring |
| 10638 | stats enable |
| 10639 | stats uri /admin?stats |
| 10640 | stats refresh 5s |
| 10641 | |
| 10642 | See also : "stats auth", "stats enable", "stats uri" |
| 10643 | |
| 10644 | |
| 10645 | stats refresh <delay> |
| 10646 | Enable statistics with automatic refresh |
| 10647 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10648 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10649 | Arguments : |
| 10650 | <delay> is the suggested refresh delay, specified in seconds, which will |
| 10651 | be returned to the browser consulting the report page. While the |
| 10652 | browser is free to apply any delay, it will generally respect it |
| 10653 | and refresh the page this every seconds. The refresh interval may |
| 10654 | be specified in any other non-default time unit, by suffixing the |
| 10655 | unit after the value, as explained at the top of this document. |
| 10656 | |
| 10657 | This statement is useful on monitoring displays with a permanent page |
| 10658 | reporting the load balancer's activity. When set, the HTML report page will |
| 10659 | include a link "refresh"/"stop refresh" so that the user can select whether |
Jackie Tapia | 749f74c | 2020-07-22 18:59:40 -0500 | [diff] [blame] | 10660 | they want automatic refresh of the page or not. |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10661 | |
| 10662 | Though this statement alone is enough to enable statistics reporting, it is |
| 10663 | recommended to set all other settings in order to avoid relying on default |
| 10664 | unobvious parameters. |
| 10665 | |
| 10666 | Example : |
| 10667 | # public access (limited to this backend only) |
| 10668 | backend public_www |
| 10669 | server srv1 192.168.0.1:80 |
| 10670 | stats enable |
| 10671 | stats hide-version |
| 10672 | stats scope . |
| 10673 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10674 | stats realm HAProxy\ Statistics |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10675 | stats auth admin1:AdMiN123 |
| 10676 | stats auth admin2:AdMiN321 |
| 10677 | |
| 10678 | # internal monitoring access (unlimited) |
| 10679 | backend private_monitoring |
| 10680 | stats enable |
| 10681 | stats uri /admin?stats |
| 10682 | stats refresh 5s |
| 10683 | |
| 10684 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 10685 | |
| 10686 | |
| 10687 | stats scope { <name> | "." } |
| 10688 | Enable statistics and limit access scope |
| 10689 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10690 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10691 | Arguments : |
| 10692 | <name> is the name of a listen, frontend or backend section to be |
| 10693 | reported. The special name "." (a single dot) designates the |
| 10694 | section in which the statement appears. |
| 10695 | |
| 10696 | When this statement is specified, only the sections enumerated with this |
| 10697 | statement will appear in the report. All other ones will be hidden. This |
| 10698 | statement may appear as many times as needed if multiple sections need to be |
| 10699 | reported. Please note that the name checking is performed as simple string |
| 10700 | comparisons, and that it is never checked that a give section name really |
| 10701 | exists. |
| 10702 | |
| 10703 | Though this statement alone is enough to enable statistics reporting, it is |
| 10704 | recommended to set all other settings in order to avoid relying on default |
| 10705 | unobvious parameters. |
| 10706 | |
| 10707 | Example : |
| 10708 | # public access (limited to this backend only) |
| 10709 | backend public_www |
| 10710 | server srv1 192.168.0.1:80 |
| 10711 | stats enable |
| 10712 | stats hide-version |
| 10713 | stats scope . |
| 10714 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10715 | stats realm HAProxy\ Statistics |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10716 | stats auth admin1:AdMiN123 |
| 10717 | stats auth admin2:AdMiN321 |
| 10718 | |
| 10719 | # internal monitoring access (unlimited) |
| 10720 | backend private_monitoring |
| 10721 | stats enable |
| 10722 | stats uri /admin?stats |
| 10723 | stats refresh 5s |
| 10724 | |
| 10725 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 10726 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10727 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10728 | stats show-desc [ <desc> ] |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10729 | Enable reporting of a description on the statistics page. |
| 10730 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10731 | yes | yes | yes | yes |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10732 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 10733 | <desc> is an optional description to be reported. If unspecified, the |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10734 | description from global section is automatically used instead. |
| 10735 | |
| 10736 | This statement is useful for users that offer shared services to their |
| 10737 | customers, where node or description should be different for each customer. |
| 10738 | |
| 10739 | Though this statement alone is enough to enable statistics reporting, it is |
| 10740 | recommended to set all other settings in order to avoid relying on default |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10741 | unobvious parameters. By default description is not shown. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10742 | |
| 10743 | Example : |
| 10744 | # internal monitoring access (unlimited) |
| 10745 | backend private_monitoring |
| 10746 | stats enable |
| 10747 | stats show-desc Master node for Europe, Asia, Africa |
| 10748 | stats uri /admin?stats |
| 10749 | stats refresh 5s |
| 10750 | |
| 10751 | See also: "show-node", "stats enable", "stats uri" and "description" in |
| 10752 | global section. |
| 10753 | |
| 10754 | |
| 10755 | stats show-legends |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10756 | Enable reporting additional information on the statistics page |
| 10757 | May be used in sections : defaults | frontend | listen | backend |
| 10758 | yes | yes | yes | yes |
| 10759 | Arguments : none |
| 10760 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 10761 | Enable reporting additional information on the statistics page : |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10762 | - cap: capabilities (proxy) |
| 10763 | - mode: one of tcp, http or health (proxy) |
| 10764 | - id: SNMP ID (proxy, socket, server) |
| 10765 | - IP (socket, server) |
| 10766 | - cookie (backend, server) |
| 10767 | |
| 10768 | Though this statement alone is enough to enable statistics reporting, it is |
| 10769 | recommended to set all other settings in order to avoid relying on default |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10770 | unobvious parameters. Default behavior is not to show this information. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10771 | |
| 10772 | See also: "stats enable", "stats uri". |
| 10773 | |
| 10774 | |
Amaury Denoyelle | 0b70a8a | 2020-10-05 11:49:45 +0200 | [diff] [blame] | 10775 | stats show-modules |
| 10776 | Enable display of extra statistics module on the statistics page |
| 10777 | May be used in sections : defaults | frontend | listen | backend |
| 10778 | yes | yes | yes | yes |
| 10779 | Arguments : none |
| 10780 | |
| 10781 | New columns are added at the end of the line containing the extra statistics |
| 10782 | values as a tooltip. |
| 10783 | |
| 10784 | Though this statement alone is enough to enable statistics reporting, it is |
| 10785 | recommended to set all other settings in order to avoid relying on default |
| 10786 | unobvious parameters. Default behavior is not to show this information. |
| 10787 | |
| 10788 | See also: "stats enable", "stats uri". |
| 10789 | |
| 10790 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10791 | stats show-node [ <name> ] |
| 10792 | Enable reporting of a host name on the statistics page. |
| 10793 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10794 | yes | yes | yes | yes |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10795 | Arguments: |
| 10796 | <name> is an optional name to be reported. If unspecified, the |
| 10797 | node name from global section is automatically used instead. |
| 10798 | |
| 10799 | This statement is useful for users that offer shared services to their |
| 10800 | customers, where node or description might be different on a stats page |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10801 | provided for each customer. Default behavior is not to show host name. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10802 | |
| 10803 | Though this statement alone is enough to enable statistics reporting, it is |
| 10804 | recommended to set all other settings in order to avoid relying on default |
| 10805 | unobvious parameters. |
| 10806 | |
| 10807 | Example: |
| 10808 | # internal monitoring access (unlimited) |
| 10809 | backend private_monitoring |
| 10810 | stats enable |
| 10811 | stats show-node Europe-1 |
| 10812 | stats uri /admin?stats |
| 10813 | stats refresh 5s |
| 10814 | |
| 10815 | See also: "show-desc", "stats enable", "stats uri", and "node" in global |
| 10816 | section. |
| 10817 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10818 | |
| 10819 | stats uri <prefix> |
| 10820 | Enable statistics and define the URI prefix to access them |
| 10821 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | ed2119c | 2014-04-24 22:10:39 +0200 | [diff] [blame] | 10822 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10823 | Arguments : |
| 10824 | <prefix> is the prefix of any URI which will be redirected to stats. This |
| 10825 | prefix may contain a question mark ('?') to indicate part of a |
| 10826 | query string. |
| 10827 | |
| 10828 | The statistics URI is intercepted on the relayed traffic, so it appears as a |
| 10829 | page within the normal application. It is strongly advised to ensure that the |
| 10830 | selected URI will never appear in the application, otherwise it will never be |
| 10831 | possible to reach it in the application. |
| 10832 | |
| 10833 | 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] | 10834 | 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] | 10835 | It is generally a good idea to include a question mark in the URI so that |
| 10836 | intermediate proxies refrain from caching the results. Also, since any string |
| 10837 | beginning with the prefix will be accepted as a stats request, the question |
| 10838 | mark helps ensuring that no valid URI will begin with the same words. |
| 10839 | |
| 10840 | It is sometimes very convenient to use "/" as the URI prefix, and put that |
| 10841 | statement in a "listen" instance of its own. That makes it easy to dedicate |
| 10842 | an address or a port to statistics only. |
| 10843 | |
| 10844 | Though this statement alone is enough to enable statistics reporting, it is |
| 10845 | recommended to set all other settings in order to avoid relying on default |
| 10846 | unobvious parameters. |
| 10847 | |
| 10848 | Example : |
| 10849 | # public access (limited to this backend only) |
| 10850 | backend public_www |
| 10851 | server srv1 192.168.0.1:80 |
| 10852 | stats enable |
| 10853 | stats hide-version |
| 10854 | stats scope . |
| 10855 | stats uri /admin?stats |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10856 | stats realm HAProxy\ Statistics |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 10857 | stats auth admin1:AdMiN123 |
| 10858 | stats auth admin2:AdMiN321 |
| 10859 | |
| 10860 | # internal monitoring access (unlimited) |
| 10861 | backend private_monitoring |
| 10862 | stats enable |
| 10863 | stats uri /admin?stats |
| 10864 | stats refresh 5s |
| 10865 | |
| 10866 | See also : "stats auth", "stats enable", "stats realm" |
| 10867 | |
| 10868 | |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10869 | stick match <pattern> [table <table>] [{if | unless} <cond>] |
| 10870 | 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] | 10871 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 10872 | no | no | yes | yes |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10873 | |
| 10874 | Arguments : |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 10875 | <pattern> is a sample expression rule as described in section 7.3. It |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10876 | describes what elements of the incoming request or connection |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10877 | will be analyzed in the hope to find a matching entry in a |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10878 | stickiness table. This rule is mandatory. |
| 10879 | |
| 10880 | <table> is an optional stickiness table name. If unspecified, the same |
| 10881 | backend's table is used. A stickiness table is declared using |
| 10882 | the "stick-table" statement. |
| 10883 | |
| 10884 | <cond> is an optional matching condition. It makes it possible to match |
| 10885 | on a certain criterion only when other conditions are met (or |
| 10886 | not met). For instance, it could be used to match on a source IP |
| 10887 | address except when a request passes through a known proxy, in |
| 10888 | which case we'd match on a header containing that IP address. |
| 10889 | |
| 10890 | Some protocols or applications require complex stickiness rules and cannot |
| 10891 | always simply rely on cookies nor hashing. The "stick match" statement |
| 10892 | describes a rule to extract the stickiness criterion from an incoming request |
| 10893 | or connection. See section 7 for a complete list of possible patterns and |
| 10894 | transformation rules. |
| 10895 | |
| 10896 | The table has to be declared using the "stick-table" statement. It must be of |
| 10897 | a type compatible with the pattern. By default it is the one which is present |
| 10898 | in the same backend. It is possible to share a table with other backends by |
| 10899 | referencing it using the "table" keyword. If another table is referenced, |
| 10900 | the server's ID inside the backends are used. By default, all server IDs |
| 10901 | start at 1 in each backend, so the server ordering is enough. But in case of |
| 10902 | doubt, it is highly recommended to force server IDs using their "id" setting. |
| 10903 | |
| 10904 | It is possible to restrict the conditions where a "stick match" statement |
| 10905 | will apply, using "if" or "unless" followed by a condition. See section 7 for |
| 10906 | ACL based conditions. |
| 10907 | |
| 10908 | There is no limit on the number of "stick match" statements. The first that |
| 10909 | applies and matches will cause the request to be directed to the same server |
| 10910 | as was used for the request which created the entry. That way, multiple |
| 10911 | matches can be used as fallbacks. |
| 10912 | |
| 10913 | The stick rules are checked after the persistence cookies, so they will not |
| 10914 | affect stickiness if a cookie has already been used to select a server. That |
| 10915 | way, it becomes very easy to insert cookies and match on IP addresses in |
| 10916 | order to maintain stickiness between HTTP and HTTPS. |
| 10917 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10918 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 10919 | unless you know what you do : memory is not shared between the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10920 | processes, which can result in random behaviors. |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10921 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10922 | Example : |
| 10923 | # forward SMTP users to the same server they just used for POP in the |
| 10924 | # last 30 minutes |
| 10925 | backend pop |
| 10926 | mode tcp |
| 10927 | balance roundrobin |
| 10928 | stick store-request src |
| 10929 | stick-table type ip size 200k expire 30m |
| 10930 | server s1 192.168.1.1:110 |
| 10931 | server s2 192.168.1.1:110 |
| 10932 | |
| 10933 | backend smtp |
| 10934 | mode tcp |
| 10935 | balance roundrobin |
| 10936 | stick match src table pop |
| 10937 | server s1 192.168.1.1:25 |
| 10938 | server s2 192.168.1.1:25 |
| 10939 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10940 | See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7 |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 10941 | about ACLs and samples fetching. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10942 | |
| 10943 | |
| 10944 | stick on <pattern> [table <table>] [{if | unless} <condition>] |
| 10945 | Define a request pattern to associate a user to a server |
| 10946 | May be used in sections : defaults | frontend | listen | backend |
| 10947 | no | no | yes | yes |
| 10948 | |
| 10949 | Note : This form is exactly equivalent to "stick match" followed by |
| 10950 | "stick store-request", all with the same arguments. Please refer |
| 10951 | to both keywords for details. It is only provided as a convenience |
| 10952 | for writing more maintainable configurations. |
| 10953 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10954 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 10955 | unless you know what you do : memory is not shared between the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10956 | processes, which can result in random behaviors. |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10957 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10958 | Examples : |
| 10959 | # The following form ... |
Willy Tarreau | ec579d8 | 2010-02-26 19:15:04 +0100 | [diff] [blame] | 10960 | stick on src table pop if !localhost |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10961 | |
| 10962 | # ...is strictly equivalent to this one : |
| 10963 | stick match src table pop if !localhost |
| 10964 | stick store-request src table pop if !localhost |
| 10965 | |
| 10966 | |
| 10967 | # Use cookie persistence for HTTP, and stick on source address for HTTPS as |
| 10968 | # well as HTTP without cookie. Share the same table between both accesses. |
| 10969 | backend http |
| 10970 | mode http |
| 10971 | balance roundrobin |
| 10972 | stick on src table https |
| 10973 | cookie SRV insert indirect nocache |
| 10974 | server s1 192.168.1.1:80 cookie s1 |
| 10975 | server s2 192.168.1.1:80 cookie s2 |
| 10976 | |
| 10977 | backend https |
| 10978 | mode tcp |
| 10979 | balance roundrobin |
| 10980 | stick-table type ip size 200k expire 30m |
| 10981 | stick on src |
| 10982 | server s1 192.168.1.1:443 |
| 10983 | server s2 192.168.1.1:443 |
| 10984 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 10985 | See also : "stick match", "stick store-request", "nbproc" and "bind-process". |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10986 | |
| 10987 | |
| 10988 | stick store-request <pattern> [table <table>] [{if | unless} <condition>] |
| 10989 | Define a request pattern used to create an entry in a stickiness table |
| 10990 | May be used in sections : defaults | frontend | listen | backend |
| 10991 | no | no | yes | yes |
| 10992 | |
| 10993 | Arguments : |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 10994 | <pattern> is a sample expression rule as described in section 7.3. It |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10995 | describes what elements of the incoming request or connection |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 10996 | will be analyzed, extracted and stored in the table once a |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 10997 | server is selected. |
| 10998 | |
| 10999 | <table> is an optional stickiness table name. If unspecified, the same |
| 11000 | backend's table is used. A stickiness table is declared using |
| 11001 | the "stick-table" statement. |
| 11002 | |
| 11003 | <cond> is an optional storage condition. It makes it possible to store |
| 11004 | certain criteria only when some conditions are met (or not met). |
| 11005 | For instance, it could be used to store the source IP address |
| 11006 | except when the request passes through a known proxy, in which |
| 11007 | case we'd store a converted form of a header containing that IP |
| 11008 | address. |
| 11009 | |
| 11010 | Some protocols or applications require complex stickiness rules and cannot |
| 11011 | always simply rely on cookies nor hashing. The "stick store-request" statement |
| 11012 | describes a rule to decide what to extract from the request and when to do |
| 11013 | it, in order to store it into a stickiness table for further requests to |
| 11014 | match it using the "stick match" statement. Obviously the extracted part must |
| 11015 | make sense and have a chance to be matched in a further request. Storing a |
| 11016 | client's IP address for instance often makes sense. Storing an ID found in a |
| 11017 | URL parameter also makes sense. Storing a source port will almost never make |
| 11018 | any sense because it will be randomly matched. See section 7 for a complete |
| 11019 | list of possible patterns and transformation rules. |
| 11020 | |
| 11021 | The table has to be declared using the "stick-table" statement. It must be of |
| 11022 | a type compatible with the pattern. By default it is the one which is present |
| 11023 | in the same backend. It is possible to share a table with other backends by |
| 11024 | referencing it using the "table" keyword. If another table is referenced, |
| 11025 | the server's ID inside the backends are used. By default, all server IDs |
| 11026 | start at 1 in each backend, so the server ordering is enough. But in case of |
| 11027 | doubt, it is highly recommended to force server IDs using their "id" setting. |
| 11028 | |
| 11029 | It is possible to restrict the conditions where a "stick store-request" |
| 11030 | statement will apply, using "if" or "unless" followed by a condition. This |
| 11031 | condition will be evaluated while parsing the request, so any criteria can be |
| 11032 | used. See section 7 for ACL based conditions. |
| 11033 | |
| 11034 | There is no limit on the number of "stick store-request" statements, but |
| 11035 | there is a limit of 8 simultaneous stores per request or response. This |
| 11036 | makes it possible to store up to 8 criteria, all extracted from either the |
| 11037 | request or the response, regardless of the number of rules. Only the 8 first |
| 11038 | ones which match will be kept. Using this, it is possible to feed multiple |
| 11039 | 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] | 11040 | another protocol or access method. Using multiple store-request rules with |
| 11041 | the same table is possible and may be used to find the best criterion to rely |
| 11042 | on, by arranging the rules by decreasing preference order. Only the first |
| 11043 | extracted criterion for a given table will be stored. All subsequent store- |
| 11044 | request rules referencing the same table will be skipped and their ACLs will |
| 11045 | not be evaluated. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11046 | |
| 11047 | The "store-request" rules are evaluated once the server connection has been |
| 11048 | established, so that the table will contain the real server that processed |
| 11049 | the request. |
| 11050 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 11051 | Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| 11052 | unless you know what you do : memory is not shared between the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11053 | processes, which can result in random behaviors. |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 11054 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11055 | Example : |
| 11056 | # forward SMTP users to the same server they just used for POP in the |
| 11057 | # last 30 minutes |
| 11058 | backend pop |
| 11059 | mode tcp |
| 11060 | balance roundrobin |
| 11061 | stick store-request src |
| 11062 | stick-table type ip size 200k expire 30m |
| 11063 | server s1 192.168.1.1:110 |
| 11064 | server s2 192.168.1.1:110 |
| 11065 | |
| 11066 | backend smtp |
| 11067 | mode tcp |
| 11068 | balance roundrobin |
| 11069 | stick match src table pop |
| 11070 | server s1 192.168.1.1:25 |
| 11071 | server s2 192.168.1.1:25 |
| 11072 | |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 11073 | See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7 |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 11074 | about ACLs and sample fetching. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11075 | |
| 11076 | |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 11077 | stick-table type {ip | integer | string [len <length>] | binary [len <length>]} |
Thayne McCombs | 92149f9 | 2020-11-20 01:28:26 -0700 | [diff] [blame] | 11078 | size <size> [expire <expire>] [nopurge] [peers <peersect>] [srvkey <srvkey>] |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 11079 | [store <data_type>]* |
Godbach | 64cef79 | 2013-12-04 16:08:22 +0800 | [diff] [blame] | 11080 | Configure the stickiness table for the current section |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11081 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | c00cdc2 | 2010-06-06 16:48:26 +0200 | [diff] [blame] | 11082 | no | yes | yes | yes |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11083 | |
| 11084 | Arguments : |
| 11085 | ip a table declared with "type ip" will only store IPv4 addresses. |
| 11086 | This form is very compact (about 50 bytes per entry) and allows |
| 11087 | very fast entry lookup and stores with almost no overhead. This |
| 11088 | is mainly used to store client source IP addresses. |
| 11089 | |
David du Colombier | 9a6d3c9 | 2011-03-17 10:40:24 +0100 | [diff] [blame] | 11090 | ipv6 a table declared with "type ipv6" will only store IPv6 addresses. |
| 11091 | This form is very compact (about 60 bytes per entry) and allows |
| 11092 | very fast entry lookup and stores with almost no overhead. This |
| 11093 | is mainly used to store client source IP addresses. |
| 11094 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11095 | integer a table declared with "type integer" will store 32bit integers |
| 11096 | which can represent a client identifier found in a request for |
| 11097 | instance. |
| 11098 | |
| 11099 | string a table declared with "type string" will store substrings of up |
| 11100 | to <len> characters. If the string provided by the pattern |
| 11101 | extractor is larger than <len>, it will be truncated before |
| 11102 | being stored. During matching, at most <len> characters will be |
| 11103 | compared between the string in the table and the extracted |
| 11104 | pattern. When not specified, the string is automatically limited |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 11105 | to 32 characters. |
| 11106 | |
| 11107 | binary a table declared with "type binary" will store binary blocks |
| 11108 | of <len> bytes. If the block provided by the pattern |
| 11109 | extractor is larger than <len>, it will be truncated before |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 11110 | being stored. If the block provided by the sample expression |
Emeric Brun | 7c6b82e | 2010-09-24 16:34:28 +0200 | [diff] [blame] | 11111 | is shorter than <len>, it will be padded by 0. When not |
| 11112 | specified, the block is automatically limited to 32 bytes. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11113 | |
| 11114 | <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] | 11115 | "string" type table (See type "string" above). Or the number |
| 11116 | of bytes of the block in "binary" type table. Be careful when |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11117 | changing this parameter as memory usage will proportionally |
| 11118 | increase. |
| 11119 | |
| 11120 | <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] | 11121 | value directly impacts memory usage. Count approximately |
| 11122 | 50 bytes per entry, plus the size of a string if any. The size |
| 11123 | 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] | 11124 | |
| 11125 | [nopurge] indicates that we refuse to purge older entries when the table |
| 11126 | is full. When not specified and the table is full when haproxy |
| 11127 | wants to store an entry in it, it will flush a few of the oldest |
| 11128 | entries in order to release some space for the new ones. This is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11129 | most often the desired behavior. In some specific cases, it |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11130 | be desirable to refuse new entries instead of purging the older |
| 11131 | ones. That may be the case when the amount of data to store is |
| 11132 | far above the hardware limits and we prefer not to offer access |
| 11133 | to new clients than to reject the ones already connected. When |
| 11134 | using this parameter, be sure to properly set the "expire" |
| 11135 | parameter (see below). |
| 11136 | |
Emeric Brun | f099e79 | 2010-09-27 12:05:28 +0200 | [diff] [blame] | 11137 | <peersect> is the name of the peers section to use for replication. Entries |
| 11138 | which associate keys to server IDs are kept synchronized with |
| 11139 | the remote peers declared in this section. All entries are also |
| 11140 | automatically learned from the local peer (old process) during a |
| 11141 | soft restart. |
| 11142 | |
Willy Tarreau | 1abc673 | 2015-05-01 19:21:02 +0200 | [diff] [blame] | 11143 | NOTE : each peers section may be referenced only by tables |
| 11144 | belonging to the same unique process. |
Cyril Bonté | 02ff8ef | 2010-12-14 22:48:49 +0100 | [diff] [blame] | 11145 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11146 | <expire> defines the maximum duration of an entry in the table since it |
| 11147 | was last created, refreshed or matched. The expiration delay is |
| 11148 | defined using the standard time format, similarly as the various |
| 11149 | timeouts. The maximum duration is slightly above 24 days. See |
Willy Tarreau | 4b10302 | 2021-02-12 17:59:10 +0100 | [diff] [blame] | 11150 | section 2.5 for more information. If this delay is not specified, |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 11151 | the session won't automatically expire, but older entries will |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11152 | be removed once full. Be sure not to use the "nopurge" parameter |
| 11153 | if not expiration delay is specified. |
| 11154 | |
Thayne McCombs | 92149f9 | 2020-11-20 01:28:26 -0700 | [diff] [blame] | 11155 | <srvkey> specifies how each server is identified for the purposes of the |
| 11156 | stick table. The valid values are "name" and "addr". If "name" is |
| 11157 | given, then <name> argument for the server (may be generated by |
| 11158 | a template). If "addr" is given, then the server is identified |
| 11159 | by its current network address, including the port. "addr" is |
| 11160 | especially useful if you are using service discovery to generate |
| 11161 | the addresses for servers with peered stick-tables and want |
| 11162 | to consistently use the same host across peers for a stickiness |
| 11163 | token. |
| 11164 | |
Willy Tarreau | 08d5f98 | 2010-06-06 13:34:54 +0200 | [diff] [blame] | 11165 | <data_type> is used to store additional information in the stick-table. This |
| 11166 | may be used by ACLs in order to control various criteria related |
| 11167 | to the activity of the client matching the stick-table. For each |
| 11168 | item specified here, the size of each entry will be inflated so |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11169 | that the additional data can fit. Several data types may be |
| 11170 | stored with an entry. Multiple data types may be specified after |
| 11171 | the "store" keyword, as a comma-separated list. Alternatively, |
| 11172 | it is possible to repeat the "store" keyword followed by one or |
| 11173 | several data types. Except for the "server_id" type which is |
| 11174 | automatically detected and enabled, all data types must be |
| 11175 | explicitly declared to be stored. If an ACL references a data |
| 11176 | type which is not stored, the ACL will simply not match. Some |
| 11177 | data types require an argument which must be passed just after |
| 11178 | the type between parenthesis. See below for the supported data |
| 11179 | types and their arguments. |
| 11180 | |
| 11181 | The data types that can be stored with an entry are the following : |
| 11182 | - server_id : this is an integer which holds the numeric ID of the server a |
| 11183 | request was assigned to. It is used by the "stick match", "stick store", |
| 11184 | and "stick on" rules. It is automatically enabled when referenced. |
| 11185 | |
| 11186 | - gpc0 : first General Purpose Counter. It is a positive 32-bit integer |
| 11187 | integer which may be used for anything. Most of the time it will be used |
| 11188 | to put a special tag on some entries, for instance to note that a |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11189 | specific behavior was detected and must be known for future matches. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11190 | |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 11191 | - gpc0_rate(<period>) : increment rate of the first General Purpose Counter |
| 11192 | over a period. It is a positive 32-bit integer integer which may be used |
| 11193 | for anything. Just like <gpc0>, it counts events, but instead of keeping |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11194 | a cumulative number, it maintains the rate at which the counter is |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 11195 | incremented. Most of the time it will be used to measure the frequency of |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11196 | occurrence of certain events (e.g. requests to a specific URL). |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 11197 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 11198 | - gpc1 : second General Purpose Counter. It is a positive 32-bit integer |
| 11199 | integer which may be used for anything. Most of the time it will be used |
| 11200 | to put a special tag on some entries, for instance to note that a |
| 11201 | specific behavior was detected and must be known for future matches. |
| 11202 | |
| 11203 | - gpc1_rate(<period>) : increment rate of the second General Purpose Counter |
| 11204 | over a period. It is a positive 32-bit integer integer which may be used |
| 11205 | for anything. Just like <gpc1>, it counts events, but instead of keeping |
| 11206 | a cumulative number, it maintains the rate at which the counter is |
| 11207 | incremented. Most of the time it will be used to measure the frequency of |
| 11208 | occurrence of certain events (e.g. requests to a specific URL). |
| 11209 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11210 | - conn_cnt : Connection Count. It is a positive 32-bit integer which counts |
| 11211 | the absolute number of connections received from clients which matched |
| 11212 | this entry. It does not mean the connections were accepted, just that |
| 11213 | they were received. |
| 11214 | |
| 11215 | - conn_cur : Current Connections. It is a positive 32-bit integer which |
| 11216 | stores the concurrent connection counts for the entry. It is incremented |
| 11217 | once an incoming connection matches the entry, and decremented once the |
| 11218 | connection leaves. That way it is possible to know at any time the exact |
| 11219 | number of concurrent connections for an entry. |
| 11220 | |
| 11221 | - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 11222 | integer parameter <period> which indicates in milliseconds the length |
| 11223 | of the period over which the average is measured. It reports the average |
| 11224 | incoming connection rate over that period, in connections per period. The |
| 11225 | result is an integer which can be matched using ACLs. |
| 11226 | |
| 11227 | - sess_cnt : Session Count. It is a positive 32-bit integer which counts |
| 11228 | the absolute number of sessions received from clients which matched this |
| 11229 | entry. A session is a connection that was accepted by the layer 4 rules. |
| 11230 | |
| 11231 | - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 11232 | integer parameter <period> which indicates in milliseconds the length |
| 11233 | of the period over which the average is measured. It reports the average |
| 11234 | incoming session rate over that period, in sessions per period. The |
| 11235 | result is an integer which can be matched using ACLs. |
| 11236 | |
| 11237 | - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which |
| 11238 | counts the absolute number of HTTP requests received from clients which |
| 11239 | matched this entry. It does not matter whether they are valid requests or |
| 11240 | not. Note that this is different from sessions when keep-alive is used on |
| 11241 | the client side. |
| 11242 | |
| 11243 | - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 11244 | integer parameter <period> which indicates in milliseconds the length |
| 11245 | of the period over which the average is measured. It reports the average |
| 11246 | HTTP request rate over that period, in requests per period. The result is |
| 11247 | an integer which can be matched using ACLs. It does not matter whether |
| 11248 | they are valid requests or not. Note that this is different from sessions |
| 11249 | when keep-alive is used on the client side. |
| 11250 | |
| 11251 | - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which |
| 11252 | counts the absolute number of HTTP requests errors induced by clients |
| 11253 | which matched this entry. Errors are counted on invalid and truncated |
| 11254 | requests, as well as on denied or tarpitted requests, and on failed |
| 11255 | authentications. If the server responds with 4xx, then the request is |
| 11256 | also counted as an error since it's an error triggered by the client |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11257 | (e.g. vulnerability scan). |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11258 | |
| 11259 | - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 11260 | integer parameter <period> which indicates in milliseconds the length |
| 11261 | of the period over which the average is measured. It reports the average |
| 11262 | HTTP request error rate over that period, in requests per period (see |
| 11263 | http_err_cnt above for what is accounted as an error). The result is an |
| 11264 | integer which can be matched using ACLs. |
| 11265 | |
Willy Tarreau | 826f3ab | 2021-02-10 12:07:15 +0100 | [diff] [blame] | 11266 | - http_fail_cnt : HTTP Failure Count. It is a positive 32-bit integer which |
| 11267 | counts the absolute number of HTTP response failures induced by servers |
| 11268 | which matched this entry. Errors are counted on invalid and truncated |
| 11269 | responses, as well as any 5xx response other than 501 or 505. It aims at |
| 11270 | being used combined with path or URI to detect service failures. |
| 11271 | |
| 11272 | - http_fail_rate(<period>) : frequency counter (takes 12 bytes). It takes |
| 11273 | an integer parameter <period> which indicates in milliseconds the length |
| 11274 | of the period over which the average is measured. It reports the average |
| 11275 | HTTP response failure rate over that period, in requests per period (see |
| 11276 | http_fail_cnt above for what is accounted as a failure). The result is an |
| 11277 | integer which can be matched using ACLs. |
| 11278 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11279 | - bytes_in_cnt : client to server byte count. It is a positive 64-bit |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11280 | integer which counts the cumulative number of bytes received from clients |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11281 | which matched this entry. Headers are included in the count. This may be |
| 11282 | used to limit abuse of upload features on photo or video servers. |
| 11283 | |
| 11284 | - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| 11285 | integer parameter <period> which indicates in milliseconds the length |
| 11286 | of the period over which the average is measured. It reports the average |
| 11287 | incoming bytes rate over that period, in bytes per period. It may be used |
| 11288 | to detect users which upload too much and too fast. Warning: with large |
| 11289 | uploads, it is possible that the amount of uploaded data will be counted |
| 11290 | once upon termination, thus causing spikes in the average transfer speed |
| 11291 | instead of having a smooth one. This may partially be smoothed with |
| 11292 | "option contstats" though this is not perfect yet. Use of byte_in_cnt is |
| 11293 | recommended for better fairness. |
| 11294 | |
| 11295 | - bytes_out_cnt : server to client byte count. It is a positive 64-bit |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11296 | integer which counts the cumulative number of bytes sent to clients which |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11297 | matched this entry. Headers are included in the count. This may be used |
| 11298 | to limit abuse of bots sucking the whole site. |
| 11299 | |
| 11300 | - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes |
| 11301 | an integer parameter <period> which indicates in milliseconds the length |
| 11302 | of the period over which the average is measured. It reports the average |
| 11303 | outgoing bytes rate over that period, in bytes per period. It may be used |
| 11304 | to detect users which download too much and too fast. Warning: with large |
| 11305 | transfers, it is possible that the amount of transferred data will be |
| 11306 | counted once upon termination, thus causing spikes in the average |
| 11307 | transfer speed instead of having a smooth one. This may partially be |
| 11308 | smoothed with "option contstats" though this is not perfect yet. Use of |
| 11309 | byte_out_cnt is recommended for better fairness. |
Willy Tarreau | 08d5f98 | 2010-06-06 13:34:54 +0200 | [diff] [blame] | 11310 | |
Willy Tarreau | c00cdc2 | 2010-06-06 16:48:26 +0200 | [diff] [blame] | 11311 | There is only one stick-table per proxy. At the moment of writing this doc, |
| 11312 | 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] | 11313 | to be required, simply create a dummy backend with a stick-table in it and |
| 11314 | reference it. |
| 11315 | |
| 11316 | It is important to understand that stickiness based on learning information |
| 11317 | has some limitations, including the fact that all learned associations are |
Baptiste Assmann | 123ff04 | 2016-03-06 23:29:28 +0100 | [diff] [blame] | 11318 | lost upon restart unless peers are properly configured to transfer such |
| 11319 | information upon restart (recommended). In general it can be good as a |
| 11320 | complement but not always as an exclusive stickiness. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11321 | |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 11322 | Last, memory requirements may be important when storing many data types. |
| 11323 | Indeed, storing all indicators above at once in each entry requires 116 bytes |
| 11324 | per entry, or 116 MB for a 1-million entries table. This is definitely not |
| 11325 | something that can be ignored. |
| 11326 | |
| 11327 | Example: |
| 11328 | # Keep track of counters of up to 1 million IP addresses over 5 minutes |
| 11329 | # and store a general purpose counter and the average connection rate |
| 11330 | # computed over a sliding window of 30 seconds. |
| 11331 | stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s) |
| 11332 | |
Willy Tarreau | 4b10302 | 2021-02-12 17:59:10 +0100 | [diff] [blame] | 11333 | See also : "stick match", "stick on", "stick store-request", section 2.5 |
David du Colombier | a13d1b9 | 2011-03-17 10:40:22 +0100 | [diff] [blame] | 11334 | about time format and section 7 about ACLs. |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 11335 | |
| 11336 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11337 | stick store-response <pattern> [table <table>] [{if | unless} <condition>] |
Baptiste Assmann | 2f2d2ec | 2016-03-06 23:27:24 +0100 | [diff] [blame] | 11338 | Define a response pattern used to create an entry in a stickiness table |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11339 | May be used in sections : defaults | frontend | listen | backend |
| 11340 | no | no | yes | yes |
| 11341 | |
| 11342 | Arguments : |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 11343 | <pattern> is a sample expression rule as described in section 7.3. It |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11344 | describes what elements of the response or connection will |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11345 | be analyzed, extracted and stored in the table once a |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11346 | server is selected. |
| 11347 | |
| 11348 | <table> is an optional stickiness table name. If unspecified, the same |
| 11349 | backend's table is used. A stickiness table is declared using |
| 11350 | the "stick-table" statement. |
| 11351 | |
| 11352 | <cond> is an optional storage condition. It makes it possible to store |
| 11353 | certain criteria only when some conditions are met (or not met). |
| 11354 | For instance, it could be used to store the SSL session ID only |
| 11355 | when the response is a SSL server hello. |
| 11356 | |
| 11357 | Some protocols or applications require complex stickiness rules and cannot |
| 11358 | always simply rely on cookies nor hashing. The "stick store-response" |
| 11359 | statement describes a rule to decide what to extract from the response and |
| 11360 | when to do it, in order to store it into a stickiness table for further |
| 11361 | requests to match it using the "stick match" statement. Obviously the |
| 11362 | 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] | 11363 | 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] | 11364 | See section 7 for a complete list of possible patterns and transformation |
| 11365 | rules. |
| 11366 | |
| 11367 | The table has to be declared using the "stick-table" statement. It must be of |
| 11368 | a type compatible with the pattern. By default it is the one which is present |
| 11369 | in the same backend. It is possible to share a table with other backends by |
| 11370 | referencing it using the "table" keyword. If another table is referenced, |
| 11371 | the server's ID inside the backends are used. By default, all server IDs |
| 11372 | start at 1 in each backend, so the server ordering is enough. But in case of |
| 11373 | doubt, it is highly recommended to force server IDs using their "id" setting. |
| 11374 | |
| 11375 | It is possible to restrict the conditions where a "stick store-response" |
| 11376 | statement will apply, using "if" or "unless" followed by a condition. This |
| 11377 | condition will be evaluated while parsing the response, so any criteria can |
| 11378 | be used. See section 7 for ACL based conditions. |
| 11379 | |
| 11380 | There is no limit on the number of "stick store-response" statements, but |
| 11381 | there is a limit of 8 simultaneous stores per request or response. This |
| 11382 | makes it possible to store up to 8 criteria, all extracted from either the |
| 11383 | request or the response, regardless of the number of rules. Only the 8 first |
| 11384 | ones which match will be kept. Using this, it is possible to feed multiple |
| 11385 | 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] | 11386 | another protocol or access method. Using multiple store-response rules with |
| 11387 | the same table is possible and may be used to find the best criterion to rely |
| 11388 | on, by arranging the rules by decreasing preference order. Only the first |
| 11389 | extracted criterion for a given table will be stored. All subsequent store- |
| 11390 | response rules referencing the same table will be skipped and their ACLs will |
| 11391 | not be evaluated. However, even if a store-request rule references a table, a |
| 11392 | store-response rule may also use the same table. This means that each table |
| 11393 | may learn exactly one element from the request and one element from the |
| 11394 | response at once. |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11395 | |
| 11396 | The table will contain the real server that processed the request. |
| 11397 | |
| 11398 | Example : |
| 11399 | # Learn SSL session ID from both request and response and create affinity. |
| 11400 | backend https |
| 11401 | mode tcp |
| 11402 | balance roundrobin |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 11403 | # maximum SSL session ID length is 32 bytes. |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11404 | stick-table type binary len 32 size 30k expire 30m |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 11405 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11406 | acl clienthello req_ssl_hello_type 1 |
| 11407 | acl serverhello rep_ssl_hello_type 2 |
| 11408 | |
| 11409 | # use tcp content accepts to detects ssl client and server hello. |
| 11410 | tcp-request inspect-delay 5s |
| 11411 | tcp-request content accept if clienthello |
| 11412 | |
| 11413 | # no timeout on response inspect delay by default. |
| 11414 | tcp-response content accept if serverhello |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 11415 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11416 | # SSL session ID (SSLID) may be present on a client or server hello. |
| 11417 | # Its length is coded on 1 byte at offset 43 and its value starts |
| 11418 | # at offset 44. |
| 11419 | |
| 11420 | # Match and learn on request if client hello. |
| 11421 | stick on payload_lv(43,1) if clienthello |
| 11422 | |
| 11423 | # Learn on response if server hello. |
| 11424 | stick store-response payload_lv(43,1) if serverhello |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 11425 | |
Emeric Brun | 6a1cefa | 2010-09-24 18:15:17 +0200 | [diff] [blame] | 11426 | server s1 192.168.1.1:443 |
| 11427 | server s2 192.168.1.1:443 |
| 11428 | |
| 11429 | See also : "stick-table", "stick on", and section 7 about ACLs and pattern |
| 11430 | extraction. |
| 11431 | |
| 11432 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11433 | tcp-check comment <string> |
| 11434 | Defines a comment for the following the tcp-check rule, reported in logs if |
| 11435 | it fails. |
| 11436 | May be used in sections : defaults | frontend | listen | backend |
| 11437 | yes | no | yes | yes |
| 11438 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11439 | Arguments : |
| 11440 | <string> is the comment message to add in logs if the following tcp-check |
| 11441 | rule fails. |
| 11442 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11443 | It only works for connect, send and expect rules. It is useful to make |
| 11444 | user-friendly error reporting. |
| 11445 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11446 | See also : "option tcp-check", "tcp-check connect", "tcp-check send" and |
| 11447 | "tcp-check expect". |
| 11448 | |
| 11449 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11450 | tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4] |
| 11451 | [ssl] [sni <sni>] [alpn <alpn>] [linger] |
Christopher Faulet | edc6ed9 | 2020-04-23 16:27:59 +0200 | [diff] [blame] | 11452 | [proto <name>] [comment <msg>] |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11453 | Opens a new connection |
| 11454 | May be used in sections: defaults | frontend | listen | backend |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 11455 | yes | no | yes | yes |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11456 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11457 | Arguments : |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11458 | comment <msg> defines a message to report if the rule evaluation fails. |
| 11459 | |
Christopher Faulet | 4dce592 | 2020-03-30 13:54:42 +0200 | [diff] [blame] | 11460 | default Use default options of the server line to do the health |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 11461 | checks. The server options are used only if not redefined. |
Christopher Faulet | 4dce592 | 2020-03-30 13:54:42 +0200 | [diff] [blame] | 11462 | |
Christopher Faulet | b7d3009 | 2020-03-30 15:19:03 +0200 | [diff] [blame] | 11463 | port <expr> if not set, check port or server port is used. |
Christopher Faulet | 5c28874 | 2020-03-31 08:15:58 +0200 | [diff] [blame] | 11464 | It tells HAProxy where to open the connection to. |
| 11465 | <port> must be a valid TCP port source integer, from 1 to |
Christopher Faulet | b7d3009 | 2020-03-30 15:19:03 +0200 | [diff] [blame] | 11466 | 65535 or an sample-fetch expression. |
Christopher Faulet | 5c28874 | 2020-03-31 08:15:58 +0200 | [diff] [blame] | 11467 | |
| 11468 | addr <ip> defines the IP address to do the health check. |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11469 | |
| 11470 | send-proxy send a PROXY protocol string |
| 11471 | |
Christopher Faulet | 085426a | 2020-03-30 13:07:02 +0200 | [diff] [blame] | 11472 | via-socks4 enables outgoing health checks using upstream socks4 proxy. |
| 11473 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11474 | ssl opens a ciphered connection |
| 11475 | |
Christopher Faulet | 79b31d4 | 2020-03-30 13:00:05 +0200 | [diff] [blame] | 11476 | sni <sni> specifies the SNI to use to do health checks over SSL. |
| 11477 | |
Christopher Faulet | 9857232 | 2020-03-30 13:16:44 +0200 | [diff] [blame] | 11478 | alpn <alpn> defines which protocols to advertise with ALPN. The protocol |
| 11479 | list consists in a comma-delimited list of protocol names, |
| 11480 | for instance: "http/1.1,http/1.0" (without quotes). |
| 11481 | If it is not set, the server ALPN is used. |
| 11482 | |
Christopher Faulet | edc6ed9 | 2020-04-23 16:27:59 +0200 | [diff] [blame] | 11483 | proto <name> forces the multiplexer's protocol to use for this connection. |
| 11484 | It must be a TCP mux protocol and it must be usable on the |
| 11485 | backend side. The list of available protocols is reported in |
| 11486 | haproxy -vv. |
| 11487 | |
Christopher Faulet | 5c28874 | 2020-03-31 08:15:58 +0200 | [diff] [blame] | 11488 | linger cleanly close the connection instead of using a single RST. |
Gaetan Rivet | f8ba677 | 2020-02-07 15:37:17 +0100 | [diff] [blame] | 11489 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11490 | When an application lies on more than a single TCP port or when HAProxy |
| 11491 | load-balance many services in a single backend, it makes sense to probe all |
| 11492 | the services individually before considering a server as operational. |
| 11493 | |
| 11494 | When there are no TCP port configured on the server line neither server port |
| 11495 | directive, then the 'tcp-check connect port <port>' must be the first step |
| 11496 | of the sequence. |
| 11497 | |
| 11498 | In a tcp-check ruleset a 'connect' is required, it is also mandatory to start |
| 11499 | the ruleset with a 'connect' rule. Purpose is to ensure admin know what they |
| 11500 | do. |
| 11501 | |
| 11502 | When a connect must start the ruleset, if may still be preceded by set-var, |
| 11503 | unset-var or comment rules. |
| 11504 | |
| 11505 | Examples : |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11506 | # check HTTP and HTTPs services on a server. |
| 11507 | # first open port 80 thanks to server line port directive, then |
| 11508 | # tcp-check opens port 443, ciphered and run a request on it: |
| 11509 | option tcp-check |
| 11510 | tcp-check connect |
| 11511 | tcp-check send GET\ /\ HTTP/1.0\r\n |
| 11512 | tcp-check send Host:\ haproxy.1wt.eu\r\n |
| 11513 | tcp-check send \r\n |
| 11514 | tcp-check expect rstring (2..|3..) |
| 11515 | tcp-check connect port 443 ssl |
| 11516 | tcp-check send GET\ /\ HTTP/1.0\r\n |
| 11517 | tcp-check send Host:\ haproxy.1wt.eu\r\n |
| 11518 | tcp-check send \r\n |
| 11519 | tcp-check expect rstring (2..|3..) |
| 11520 | server www 10.0.0.1 check port 80 |
| 11521 | |
| 11522 | # check both POP and IMAP from a single server: |
| 11523 | option tcp-check |
Gaetan Rivet | f8ba677 | 2020-02-07 15:37:17 +0100 | [diff] [blame] | 11524 | tcp-check connect port 110 linger |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11525 | tcp-check expect string +OK\ POP3\ ready |
| 11526 | tcp-check connect port 143 |
| 11527 | tcp-check expect string *\ OK\ IMAP4\ ready |
| 11528 | server mail 10.0.0.1 check |
| 11529 | |
| 11530 | See also : "option tcp-check", "tcp-check send", "tcp-check expect" |
| 11531 | |
| 11532 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11533 | tcp-check expect [min-recv <int>] [comment <msg>] |
Christopher Faulet | ec07e38 | 2020-04-07 14:56:26 +0200 | [diff] [blame] | 11534 | [ok-status <st>] [error-status <st>] [tout-status <st>] |
Christopher Faulet | 98cc57c | 2020-04-01 20:52:31 +0200 | [diff] [blame] | 11535 | [on-success <fmt>] [on-error <fmt>] [status-code <expr>] |
Christopher Faulet | cf80f2f | 2020-04-01 11:04:52 +0200 | [diff] [blame] | 11536 | [!] <match> <pattern> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11537 | Specify data to be collected and analyzed during a generic health check |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11538 | May be used in sections: defaults | frontend | listen | backend |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 11539 | yes | no | yes | yes |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11540 | |
| 11541 | Arguments : |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11542 | comment <msg> defines a message to report if the rule evaluation fails. |
| 11543 | |
Gaetan Rivet | 1afd826 | 2020-02-07 15:37:17 +0100 | [diff] [blame] | 11544 | min-recv is optional and can define the minimum amount of data required to |
| 11545 | evaluate the current expect rule. If the number of received bytes |
| 11546 | is under this limit, the check will wait for more data. This |
| 11547 | option can be used to resolve some ambiguous matching rules or to |
| 11548 | avoid executing costly regex matches on content known to be still |
| 11549 | incomplete. If an exact string (string or binary) is used, the |
| 11550 | minimum between the string length and this parameter is used. |
| 11551 | This parameter is ignored if it is set to -1. If the expect rule |
| 11552 | does not match, the check will wait for more data. If set to 0, |
| 11553 | the evaluation result is always conclusive. |
| 11554 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11555 | <match> is a keyword indicating how to look for a specific pattern in the |
Gaetan Rivet | efab6c6 | 2020-02-07 15:37:17 +0100 | [diff] [blame] | 11556 | response. The keyword may be one of "string", "rstring", "binary" or |
| 11557 | "rbinary". |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11558 | The keyword may be preceded by an exclamation mark ("!") to negate |
| 11559 | the match. Spaces are allowed between the exclamation mark and the |
| 11560 | keyword. See below for more details on the supported keywords. |
| 11561 | |
Christopher Faulet | ec07e38 | 2020-04-07 14:56:26 +0200 | [diff] [blame] | 11562 | ok-status <st> is optional and can be used to set the check status if |
| 11563 | the expect rule is successfully evaluated and if it is |
| 11564 | the last rule in the tcp-check ruleset. "L7OK", "L7OKC", |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 11565 | "L6OK" and "L4OK" are supported : |
| 11566 | - L7OK : check passed on layer 7 |
Christopher Faulet | 83662b5 | 2020-11-20 17:47:47 +0100 | [diff] [blame] | 11567 | - L7OKC : check conditionally passed on layer 7, set |
| 11568 | server to NOLB state. |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 11569 | - L6OK : check passed on layer 6 |
| 11570 | - L4OK : check passed on layer 4 |
Christopher Faulet | ec07e38 | 2020-04-07 14:56:26 +0200 | [diff] [blame] | 11571 | By default "L7OK" is used. |
| 11572 | |
Christopher Faulet | cf80f2f | 2020-04-01 11:04:52 +0200 | [diff] [blame] | 11573 | error-status <st> is optional and can be used to set the check status if |
| 11574 | an error occurred during the expect rule evaluation. |
Christopher Faulet | 83662b5 | 2020-11-20 17:47:47 +0100 | [diff] [blame] | 11575 | "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are |
| 11576 | supported : |
| 11577 | - L7OKC : check conditionally passed on layer 7, set |
| 11578 | server to NOLB state. |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 11579 | - L7RSP : layer 7 invalid response - protocol error |
| 11580 | - L7STS : layer 7 response error, for example HTTP 5xx |
| 11581 | - L6RSP : layer 6 invalid response - protocol error |
| 11582 | - L4CON : layer 1-4 connection problem |
| 11583 | By default "L7RSP" is used. |
Christopher Faulet | cf80f2f | 2020-04-01 11:04:52 +0200 | [diff] [blame] | 11584 | |
Christopher Faulet | ec07e38 | 2020-04-07 14:56:26 +0200 | [diff] [blame] | 11585 | tout-status <st> is optional and can be used to set the check status if |
Christopher Faulet | cf80f2f | 2020-04-01 11:04:52 +0200 | [diff] [blame] | 11586 | a timeout occurred during the expect rule evaluation. |
Christopher Faulet | d888f0f | 2020-05-07 07:40:17 +0200 | [diff] [blame] | 11587 | "L7TOUT", "L6TOUT", and "L4TOUT" are supported : |
| 11588 | - L7TOUT : layer 7 (HTTP/SMTP) timeout |
| 11589 | - L6TOUT : layer 6 (SSL) timeout |
| 11590 | - L4TOUT : layer 1-4 timeout |
Christopher Faulet | cf80f2f | 2020-04-01 11:04:52 +0200 | [diff] [blame] | 11591 | By default "L7TOUT" is used. |
| 11592 | |
Christopher Faulet | be52b4d | 2020-04-01 16:30:22 +0200 | [diff] [blame] | 11593 | on-success <fmt> is optional and can be used to customize the |
| 11594 | informational message reported in logs if the expect |
| 11595 | rule is successfully evaluated and if it is the last rule |
| 11596 | in the tcp-check ruleset. <fmt> is a log-format string. |
| 11597 | |
| 11598 | on-error <fmt> is optional and can be used to customize the |
| 11599 | informational message reported in logs if an error |
| 11600 | occurred during the expect rule evaluation. <fmt> is a |
| 11601 | log-format string. |
| 11602 | |
Christopher Faulet | 98cc57c | 2020-04-01 20:52:31 +0200 | [diff] [blame] | 11603 | status-code <expr> is optional and can be used to set the check status code |
| 11604 | reported in logs, on success or on error. <expr> is a |
| 11605 | standard HAProxy expression formed by a sample-fetch |
| 11606 | followed by some converters. |
| 11607 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11608 | <pattern> is the pattern to look for. It may be a string or a regular |
| 11609 | expression. If the pattern contains spaces, they must be escaped |
| 11610 | with the usual backslash ('\'). |
| 11611 | If the match is set to binary, then the pattern must be passed as |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11612 | a series of hexadecimal digits in an even number. Each sequence of |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11613 | two digits will represent a byte. The hexadecimal digits may be |
| 11614 | used upper or lower case. |
| 11615 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11616 | The available matches are intentionally similar to their http-check cousins : |
| 11617 | |
| 11618 | string <string> : test the exact string matches in the response buffer. |
| 11619 | A health check response will be considered valid if the |
| 11620 | response's buffer contains this exact string. If the |
| 11621 | "string" keyword is prefixed with "!", then the response |
| 11622 | will be considered invalid if the body contains this |
| 11623 | string. This can be used to look for a mandatory pattern |
| 11624 | in a protocol response, or to detect a failure when a |
| 11625 | specific error appears in a protocol banner. |
| 11626 | |
| 11627 | rstring <regex> : test a regular expression on the response buffer. |
| 11628 | A health check response will be considered valid if the |
| 11629 | response's buffer matches this expression. If the |
| 11630 | "rstring" keyword is prefixed with "!", then the response |
| 11631 | will be considered invalid if the body matches the |
| 11632 | expression. |
| 11633 | |
Christopher Faulet | aaab083 | 2020-05-05 15:54:22 +0200 | [diff] [blame] | 11634 | string-lf <fmt> : test a log-format string match in the response's buffer. |
| 11635 | A health check response will be considered valid if the |
| 11636 | response's buffer contains the string resulting of the |
| 11637 | evaluation of <fmt>, which follows the log-format rules. |
| 11638 | If prefixed with "!", then the response will be |
| 11639 | considered invalid if the buffer contains the string. |
| 11640 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11641 | binary <hexstring> : test the exact string in its hexadecimal form matches |
| 11642 | in the response buffer. A health check response will |
| 11643 | be considered valid if the response's buffer contains |
| 11644 | this exact hexadecimal string. |
| 11645 | Purpose is to match data on binary protocols. |
| 11646 | |
Gaetan Rivet | efab6c6 | 2020-02-07 15:37:17 +0100 | [diff] [blame] | 11647 | rbinary <regex> : test a regular expression on the response buffer, like |
| 11648 | "rstring". However, the response buffer is transformed |
| 11649 | into its hexadecimal form, including NUL-bytes. This |
| 11650 | allows using all regex engines to match any binary |
| 11651 | content. The hexadecimal transformation takes twice the |
| 11652 | size of the original response. As such, the expected |
| 11653 | pattern should work on at-most half the response buffer |
| 11654 | size. |
| 11655 | |
Christopher Faulet | aaab083 | 2020-05-05 15:54:22 +0200 | [diff] [blame] | 11656 | binary-lf <hexfmt> : test a log-format string in its hexadecimal form |
| 11657 | match in the response's buffer. A health check response |
| 11658 | will be considered valid if the response's buffer |
| 11659 | contains the hexadecimal string resulting of the |
| 11660 | evaluation of <fmt>, which follows the log-format |
| 11661 | rules. If prefixed with "!", then the response will be |
| 11662 | considered invalid if the buffer contains the |
| 11663 | hexadecimal string. The hexadecimal string is converted |
| 11664 | in a binary string before matching the response's |
| 11665 | buffer. |
| 11666 | |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11667 | It is important to note that the responses will be limited to a certain size |
Christopher Faulet | bb9fb8b | 2020-11-25 17:20:57 +0100 | [diff] [blame] | 11668 | defined by the global "tune.bufsize" option, which defaults to 16384 bytes. |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11669 | Thus, too large responses may not contain the mandatory pattern when using |
| 11670 | "string", "rstring" or binary. If a large response is absolutely required, it |
| 11671 | is possible to change the default max size by setting the global variable. |
| 11672 | However, it is worth keeping in mind that parsing very large responses can |
| 11673 | waste some CPU cycles, especially when regular expressions are used, and that |
| 11674 | it is always better to focus the checks on smaller resources. Also, in its |
| 11675 | current state, the check will not find any string nor regex past a null |
| 11676 | character in the response. Similarly it is not possible to request matching |
| 11677 | the null character. |
| 11678 | |
| 11679 | Examples : |
| 11680 | # perform a POP check |
| 11681 | option tcp-check |
| 11682 | tcp-check expect string +OK\ POP3\ ready |
| 11683 | |
| 11684 | # perform an IMAP check |
| 11685 | option tcp-check |
| 11686 | tcp-check expect string *\ OK\ IMAP4\ ready |
| 11687 | |
| 11688 | # look for the redis master server |
| 11689 | option tcp-check |
| 11690 | tcp-check send PING\r\n |
Baptiste Assmann | a332299 | 2015-08-04 10:12:18 +0200 | [diff] [blame] | 11691 | tcp-check expect string +PONG |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11692 | tcp-check send info\ replication\r\n |
| 11693 | tcp-check expect string role:master |
| 11694 | tcp-check send QUIT\r\n |
| 11695 | tcp-check expect string +OK |
| 11696 | |
| 11697 | |
| 11698 | See also : "option tcp-check", "tcp-check connect", "tcp-check send", |
Christopher Faulet | bb9fb8b | 2020-11-25 17:20:57 +0100 | [diff] [blame] | 11699 | "tcp-check send-binary", "http-check expect", tune.bufsize |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11700 | |
| 11701 | |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 11702 | tcp-check send <data> [comment <msg>] |
| 11703 | tcp-check send-lf <fmt> [comment <msg>] |
| 11704 | Specify a string or a log-format string to be sent as a question during a |
| 11705 | generic health check |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11706 | May be used in sections: defaults | frontend | listen | backend |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 11707 | yes | no | yes | yes |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11708 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11709 | Arguments : |
| 11710 | comment <msg> defines a message to report if the rule evaluation fails. |
| 11711 | |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 11712 | <data> is the string that will be sent during a generic health |
| 11713 | check session. |
Christopher Faulet | 16fff67 | 2020-04-30 07:50:54 +0200 | [diff] [blame] | 11714 | |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 11715 | <fmt> is the log-format string that will be sent, once evaluated, |
| 11716 | during a generic health check session. |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11717 | |
| 11718 | Examples : |
| 11719 | # look for the redis master server |
| 11720 | option tcp-check |
| 11721 | tcp-check send info\ replication\r\n |
| 11722 | tcp-check expect string role:master |
| 11723 | |
| 11724 | See also : "option tcp-check", "tcp-check connect", "tcp-check expect", |
Christopher Faulet | bb9fb8b | 2020-11-25 17:20:57 +0100 | [diff] [blame] | 11725 | "tcp-check send-binary", tune.bufsize |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11726 | |
| 11727 | |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 11728 | tcp-check send-binary <hexstring> [comment <msg>] |
| 11729 | tcp-check send-binary-lf <hexfmt> [comment <msg>] |
| 11730 | Specify an hex digits string or an hex digits log-format string to be sent as |
| 11731 | a binary question during a raw tcp health check |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11732 | May be used in sections: defaults | frontend | listen | backend |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 11733 | yes | no | yes | yes |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11734 | |
Christopher Faulet | 4f5c2e2 | 2020-04-23 15:22:33 +0200 | [diff] [blame] | 11735 | Arguments : |
| 11736 | comment <msg> defines a message to report if the rule evaluation fails. |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11737 | |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 11738 | <hexstring> is the hexadecimal string that will be send, once converted |
| 11739 | to binary, during a generic health check session. |
Christopher Faulet | 16fff67 | 2020-04-30 07:50:54 +0200 | [diff] [blame] | 11740 | |
Christopher Faulet | b50b3e6 | 2020-05-05 18:43:43 +0200 | [diff] [blame] | 11741 | <hexfmt> is the hexadecimal log-format string that will be send, once |
| 11742 | evaluated and converted to binary, during a generic health |
| 11743 | check session. |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11744 | |
| 11745 | Examples : |
| 11746 | # redis check in binary |
| 11747 | option tcp-check |
| 11748 | tcp-check send-binary 50494e470d0a # PING\r\n |
| 11749 | tcp-check expect binary 2b504F4e47 # +PONG |
| 11750 | |
| 11751 | |
| 11752 | See also : "option tcp-check", "tcp-check connect", "tcp-check expect", |
Christopher Faulet | bb9fb8b | 2020-11-25 17:20:57 +0100 | [diff] [blame] | 11753 | "tcp-check send", tune.bufsize |
Willy Tarreau | 938c7fe | 2014-04-25 14:21:39 +0200 | [diff] [blame] | 11754 | |
| 11755 | |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11756 | tcp-check set-var(<var-name>) <expr> |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11757 | This operation sets the content of a variable. The variable is declared inline. |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11758 | May be used in sections: defaults | frontend | listen | backend |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 11759 | yes | no | yes | yes |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11760 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11761 | Arguments : |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11762 | <var-name> The name of the variable starts with an indication about its |
| 11763 | scope. The scopes allowed for tcp-check are: |
| 11764 | "proc" : the variable is shared with the whole process. |
| 11765 | "sess" : the variable is shared with the tcp-check session. |
| 11766 | "check": the variable is declared for the lifetime of the tcp-check. |
| 11767 | This prefix is followed by a name. The separator is a '.'. |
| 11768 | The name may only contain characters 'a-z', 'A-Z', '0-9', '.', |
| 11769 | and '-'. |
| 11770 | |
| 11771 | <expr> Is a sample-fetch expression potentially followed by converters. |
| 11772 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11773 | Examples : |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11774 | tcp-check set-var(check.port) int(1234) |
| 11775 | |
| 11776 | |
| 11777 | tcp-check unset-var(<var-name>) |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11778 | Free a reference to a variable within its scope. |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11779 | May be used in sections: defaults | frontend | listen | backend |
Christopher Faulet | 404f919 | 2020-04-09 23:13:54 +0200 | [diff] [blame] | 11780 | yes | no | yes | yes |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11781 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11782 | Arguments : |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11783 | <var-name> The name of the variable starts with an indication about its |
| 11784 | scope. The scopes allowed for tcp-check are: |
| 11785 | "proc" : the variable is shared with the whole process. |
| 11786 | "sess" : the variable is shared with the tcp-check session. |
| 11787 | "check": the variable is declared for the lifetime of the tcp-check. |
| 11788 | This prefix is followed by a name. The separator is a '.'. |
| 11789 | The name may only contain characters 'a-z', 'A-Z', '0-9', '.', |
| 11790 | and '-'. |
| 11791 | |
Christopher Faulet | c52ea4d | 2020-04-23 15:43:35 +0200 | [diff] [blame] | 11792 | Examples : |
Gaetan Rivet | 0c39ecc | 2020-02-24 17:34:11 +0100 | [diff] [blame] | 11793 | tcp-check unset-var(check.port) |
| 11794 | |
| 11795 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11796 | tcp-request connection <action> [{if | unless} <condition>] |
| 11797 | 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] | 11798 | May be used in sections : defaults | frontend | listen | backend |
| 11799 | no | yes | yes | no |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11800 | Arguments : |
Willy Tarreau | c870bfd | 2015-09-28 18:47:38 +0200 | [diff] [blame] | 11801 | <action> defines the action to perform if the condition applies. See |
| 11802 | below. |
Willy Tarreau | 1a68794 | 2010-05-23 22:40:30 +0200 | [diff] [blame] | 11803 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11804 | <condition> is a standard layer4-only ACL-based condition (see section 7). |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11805 | |
| 11806 | Immediately after acceptance of a new incoming connection, it is possible to |
| 11807 | evaluate some conditions to decide whether this connection must be accepted |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11808 | or dropped or have its counters tracked. Those conditions cannot make use of |
| 11809 | any data contents because the connection has not been read from yet, and the |
| 11810 | buffers are not yet allocated. This is used to selectively and very quickly |
| 11811 | accept or drop connections from various sources with a very low overhead. If |
| 11812 | some contents need to be inspected in order to take the decision, the |
| 11813 | "tcp-request content" statements must be used instead. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11814 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11815 | The "tcp-request connection" rules are evaluated in their exact declaration |
| 11816 | order. If no rule matches or if there is no rule, the default action is to |
| 11817 | accept the incoming connection. There is no specific limit to the number of |
| 11818 | rules which may be inserted. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11819 | |
Willy Tarreau | a9083d0 | 2015-05-08 15:27:59 +0200 | [diff] [blame] | 11820 | Four types of actions are supported : |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11821 | - accept : |
| 11822 | accepts the connection if the condition is true (when used with "if") |
| 11823 | or false (when used with "unless"). The first such rule executed ends |
| 11824 | the rules evaluation. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11825 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11826 | - reject : |
| 11827 | rejects the connection if the condition is true (when used with "if") |
| 11828 | or false (when used with "unless"). The first such rule executed ends |
| 11829 | the rules evaluation. Rejected connections do not even become a |
| 11830 | session, which is why they are accounted separately for in the stats, |
| 11831 | as "denied connections". They are not considered for the session |
| 11832 | rate-limit and are not logged either. The reason is that these rules |
| 11833 | should only be used to filter extremely high connection rates such as |
| 11834 | the ones encountered during a massive DDoS attack. Under these extreme |
| 11835 | conditions, the simple action of logging each event would make the |
| 11836 | system collapse and would considerably lower the filtering capacity. If |
| 11837 | logging is absolutely desired, then "tcp-request content" rules should |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 11838 | be used instead, as "tcp-request session" rules will not log either. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11839 | |
Willy Tarreau | 4f0d919 | 2013-06-11 20:40:55 +0200 | [diff] [blame] | 11840 | - expect-proxy layer4 : |
| 11841 | configures the client-facing connection to receive a PROXY protocol |
| 11842 | header before any byte is read from the socket. This is equivalent to |
| 11843 | having the "accept-proxy" keyword on the "bind" line, except that using |
| 11844 | the TCP rule allows the PROXY protocol to be accepted only for certain |
| 11845 | IP address ranges using an ACL. This is convenient when multiple layers |
| 11846 | of load balancers are passed through by traffic coming from public |
| 11847 | hosts. |
| 11848 | |
Bertrand Jacquin | 9075968 | 2016-06-06 15:35:39 +0100 | [diff] [blame] | 11849 | - expect-netscaler-cip layer4 : |
| 11850 | configures the client-facing connection to receive a NetScaler Client |
| 11851 | IP insertion protocol header before any byte is read from the socket. |
| 11852 | This is equivalent to having the "accept-netscaler-cip" keyword on the |
| 11853 | "bind" line, except that using the TCP rule allows the PROXY protocol |
| 11854 | to be accepted only for certain IP address ranges using an ACL. This |
| 11855 | is convenient when multiple layers of load balancers are passed |
| 11856 | through by traffic coming from public hosts. |
| 11857 | |
Willy Tarreau | 18bf01e | 2014-06-13 16:18:52 +0200 | [diff] [blame] | 11858 | - capture <sample> len <length> : |
| 11859 | This only applies to "tcp-request content" rules. It captures sample |
| 11860 | expression <sample> from the request buffer, and converts it to a |
| 11861 | string of at most <len> characters. The resulting string is stored into |
| 11862 | the next request "capture" slot, so it will possibly appear next to |
| 11863 | some captured HTTP headers. It will then automatically appear in the |
| 11864 | logs, and it will be possible to extract it using sample fetch rules to |
| 11865 | feed it into headers or anything. The length should be limited given |
| 11866 | that this size will be allocated for each capture during the whole |
Willy Tarreau | a9083d0 | 2015-05-08 15:27:59 +0200 | [diff] [blame] | 11867 | session life. Please check section 7.3 (Fetching samples) and "capture |
| 11868 | request header" for more information. |
Willy Tarreau | 18bf01e | 2014-06-13 16:18:52 +0200 | [diff] [blame] | 11869 | |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 11870 | - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] : |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11871 | enables tracking of sticky counters from current connection. These |
Moemen MHEDHBI | 9cf4634 | 2018-09-25 17:50:53 +0200 | [diff] [blame] | 11872 | rules do not stop evaluation and do not change default action. The |
| 11873 | number of counters that may be simultaneously tracked by the same |
| 11874 | connection is set in MAX_SESS_STKCTR at build time (reported in |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 11875 | haproxy -vv) which defaults to 3, so the track-sc number is between 0 |
Matteo Contrini | 1857b8c | 2020-10-16 17:35:54 +0200 | [diff] [blame] | 11876 | and (MAX_SESS_STKCTR-1). The first "track-sc0" rule executed enables |
Moemen MHEDHBI | 9cf4634 | 2018-09-25 17:50:53 +0200 | [diff] [blame] | 11877 | tracking of the counters of the specified table as the first set. The |
| 11878 | first "track-sc1" rule executed enables tracking of the counters of the |
| 11879 | specified table as the second set. The first "track-sc2" rule executed |
| 11880 | enables tracking of the counters of the specified table as the third |
| 11881 | set. It is a recommended practice to use the first set of counters for |
| 11882 | the per-frontend counters and the second set for the per-backend ones. |
| 11883 | But this is just a guideline, all may be used everywhere. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11884 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11885 | These actions take one or two arguments : |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 11886 | <key> is mandatory, and is a sample expression rule as described |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 11887 | in section 7.3. It describes what elements of the incoming |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11888 | request or connection will be analyzed, extracted, combined, |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 11889 | and used to select which table entry to update the counters. |
| 11890 | Note that "tcp-request connection" cannot use content-based |
| 11891 | fetches. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11892 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11893 | <table> is an optional table to be used instead of the default one, |
| 11894 | which is the stick-table declared in the current proxy. All |
| 11895 | the counters for the matches and updates for the key will |
| 11896 | then be performed in that table until the session ends. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11897 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11898 | Once a "track-sc*" rule is executed, the key is looked up in the table |
| 11899 | and if it is not found, an entry is allocated for it. Then a pointer to |
| 11900 | that entry is kept during all the session's life, and this entry's |
| 11901 | counters are updated as often as possible, every time the session's |
| 11902 | counters are updated, and also systematically when the session ends. |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 11903 | Counters are only updated for events that happen after the tracking has |
| 11904 | been started. For example, connection counters will not be updated when |
| 11905 | tracking layer 7 information, since the connection event happens before |
| 11906 | layer7 information is extracted. |
| 11907 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 11908 | If the entry tracks concurrent connection counters, one connection is |
| 11909 | counted for as long as the entry is tracked, and the entry will not |
| 11910 | expire during that time. Tracking counters also provides a performance |
| 11911 | advantage over just checking the keys, because only one table lookup is |
| 11912 | performed for all ACL checks that make use of it. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 11913 | |
Thierry FOURNIER | e0627bd | 2015-08-04 08:20:33 +0200 | [diff] [blame] | 11914 | - sc-inc-gpc0(<sc-id>): |
| 11915 | The "sc-inc-gpc0" increments the GPC0 counter according to the sticky |
| 11916 | counter designated by <sc-id>. If an error occurs, this action silently |
| 11917 | fails and the actions evaluation continues. |
| 11918 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 11919 | - sc-inc-gpc1(<sc-id>): |
| 11920 | The "sc-inc-gpc1" increments the GPC1 counter according to the sticky |
| 11921 | counter designated by <sc-id>. If an error occurs, this action silently |
| 11922 | fails and the actions evaluation continues. |
| 11923 | |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 11924 | - sc-set-gpt0(<sc-id>) { <int> | <expr> }: |
| 11925 | This action sets the 32-bit unsigned GPT0 tag according to the sticky |
| 11926 | counter designated by <sc-id> and the value of <int>/<expr>. The |
| 11927 | expected result is a boolean. If an error occurs, this action silently |
| 11928 | fails and the actions evaluation continues. |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 11929 | |
William Lallemand | 2e785f2 | 2016-05-25 01:48:42 +0200 | [diff] [blame] | 11930 | - set-src <expr> : |
| 11931 | Is used to set the source IP address to the value of specified |
| 11932 | expression. Useful if you want to mask source IP for privacy. |
| 11933 | If you want to provide an IP from a HTTP header use "http-request |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 11934 | set-src". |
William Lallemand | 2e785f2 | 2016-05-25 01:48:42 +0200 | [diff] [blame] | 11935 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 11936 | Arguments: |
| 11937 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 11938 | followed by some converters. |
William Lallemand | 2e785f2 | 2016-05-25 01:48:42 +0200 | [diff] [blame] | 11939 | |
| 11940 | Example: |
William Lallemand | 2e785f2 | 2016-05-25 01:48:42 +0200 | [diff] [blame] | 11941 | tcp-request connection set-src src,ipmask(24) |
| 11942 | |
Willy Tarreau | 0c63053 | 2016-10-21 17:52:58 +0200 | [diff] [blame] | 11943 | When possible, set-src preserves the original source port as long as the |
| 11944 | address family allows it, otherwise the source port is set to 0. |
William Lallemand | 2e785f2 | 2016-05-25 01:48:42 +0200 | [diff] [blame] | 11945 | |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 11946 | - set-src-port <expr> : |
| 11947 | Is used to set the source port address to the value of specified |
| 11948 | expression. |
| 11949 | |
Cyril Bonté | 6c81d5f | 2018-10-17 00:14:51 +0200 | [diff] [blame] | 11950 | Arguments: |
| 11951 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 11952 | followed by some converters. |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 11953 | |
| 11954 | Example: |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 11955 | tcp-request connection set-src-port int(4000) |
| 11956 | |
Willy Tarreau | 0c63053 | 2016-10-21 17:52:58 +0200 | [diff] [blame] | 11957 | When possible, set-src-port preserves the original source address as long |
| 11958 | as the address family supports a port, otherwise it forces the source |
| 11959 | address to IPv4 "0.0.0.0" before rewriting the port. |
William Lallemand | 44be640 | 2016-05-25 01:51:35 +0200 | [diff] [blame] | 11960 | |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 11961 | - set-dst <expr> : |
| 11962 | Is used to set the destination IP address to the value of specified |
| 11963 | expression. Useful if you want to mask IP for privacy in log. |
| 11964 | If you want to provide an IP from a HTTP header use "http-request |
| 11965 | set-dst". If you want to connect to the new address/port, use |
| 11966 | '0.0.0.0:0' as a server address in the backend. |
| 11967 | |
| 11968 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 11969 | followed by some converters. |
| 11970 | |
| 11971 | Example: |
| 11972 | |
| 11973 | tcp-request connection set-dst dst,ipmask(24) |
| 11974 | tcp-request connection set-dst ipv4(10.0.0.1) |
| 11975 | |
Willy Tarreau | 0c63053 | 2016-10-21 17:52:58 +0200 | [diff] [blame] | 11976 | When possible, set-dst preserves the original destination port as long as |
| 11977 | the address family allows it, otherwise the destination port is set to 0. |
| 11978 | |
William Lallemand | 13e9b0c | 2016-05-25 02:34:07 +0200 | [diff] [blame] | 11979 | - set-dst-port <expr> : |
| 11980 | Is used to set the destination port address to the value of specified |
| 11981 | expression. If you want to connect to the new address/port, use |
| 11982 | '0.0.0.0:0' as a server address in the backend. |
| 11983 | |
| 11984 | |
| 11985 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 11986 | followed by some converters. |
| 11987 | |
| 11988 | Example: |
| 11989 | |
| 11990 | tcp-request connection set-dst-port int(4000) |
| 11991 | |
Willy Tarreau | 0c63053 | 2016-10-21 17:52:58 +0200 | [diff] [blame] | 11992 | When possible, set-dst-port preserves the original destination address as |
| 11993 | long as the address family supports a port, otherwise it forces the |
| 11994 | destination address to IPv4 "0.0.0.0" before rewriting the port. |
| 11995 | |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 11996 | - "silent-drop" : |
| 11997 | This stops the evaluation of the rules and makes the client-facing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 11998 | connection suddenly disappear using a system-dependent way that tries |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 11999 | to prevent the client from being notified. The effect it then that the |
| 12000 | client still sees an established connection while there's none on |
| 12001 | HAProxy. The purpose is to achieve a comparable effect to "tarpit" |
| 12002 | except that it doesn't use any local resource at all on the machine |
| 12003 | running HAProxy. It can resist much higher loads than "tarpit", and |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12004 | slow down stronger attackers. It is important to understand the impact |
| 12005 | of using this mechanism. All stateful equipment placed between the |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12006 | client and HAProxy (firewalls, proxies, load balancers) will also keep |
| 12007 | the established connection for a long time and may suffer from this |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12008 | action. On modern Linux systems running with enough privileges, the |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12009 | TCP_REPAIR socket option is used to block the emission of a TCP |
| 12010 | reset. On other systems, the socket's TTL is reduced to 1 so that the |
| 12011 | TCP reset doesn't pass the first router, though it's still delivered to |
| 12012 | local networks. Do not use it unless you fully understand how it works. |
| 12013 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12014 | Note that the "if/unless" condition is optional. If no condition is set on |
| 12015 | the action, it is simply performed unconditionally. That can be useful for |
| 12016 | "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] | 12017 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12018 | Example: accept all connections from white-listed hosts, reject too fast |
| 12019 | connection without counting them, and track accepted connections. |
| 12020 | This results in connection rate being capped from abusive sources. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12021 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12022 | tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst } |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12023 | tcp-request connection reject if { src_conn_rate gt 10 } |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 12024 | tcp-request connection track-sc0 src |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12025 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12026 | Example: accept all connections from white-listed hosts, count all other |
| 12027 | connections and reject too fast ones. This results in abusive ones |
| 12028 | being blocked as long as they don't slow down. |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12029 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12030 | tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst } |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 12031 | tcp-request connection track-sc0 src |
| 12032 | tcp-request connection reject if { sc0_conn_rate gt 10 } |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12033 | |
Willy Tarreau | 4f0d919 | 2013-06-11 20:40:55 +0200 | [diff] [blame] | 12034 | Example: enable the PROXY protocol for traffic coming from all known proxies. |
| 12035 | |
| 12036 | tcp-request connection expect-proxy layer4 if { src -f proxies.lst } |
| 12037 | |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12038 | See section 7 about ACL usage. |
| 12039 | |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12040 | See also : "tcp-request session", "tcp-request content", "stick-table" |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12041 | |
| 12042 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12043 | tcp-request content <action> [{if | unless} <condition>] |
| 12044 | 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] | 12045 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | fb35620 | 2010-08-03 14:02:05 +0200 | [diff] [blame] | 12046 | no | yes | yes | yes |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12047 | Arguments : |
Willy Tarreau | c870bfd | 2015-09-28 18:47:38 +0200 | [diff] [blame] | 12048 | <action> defines the action to perform if the condition applies. See |
| 12049 | below. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12050 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12051 | <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] | 12052 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12053 | A request's contents can be analyzed at an early stage of request processing |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12054 | called "TCP content inspection". During this stage, ACL-based rules are |
| 12055 | evaluated every time the request contents are updated, until either an |
Christopher Faulet | ae863c6 | 2021-03-15 12:03:44 +0100 | [diff] [blame] | 12056 | "accept", a "reject" or a "switch-mode" rule matches, or the TCP request |
| 12057 | inspection delay expires with no matching rule. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12058 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12059 | The first difference between these rules and "tcp-request connection" rules |
| 12060 | is that "tcp-request content" rules can make use of contents to take a |
| 12061 | decision. Most often, these decisions will consider a protocol recognition or |
| 12062 | 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] | 12063 | both frontends and backends. In case of HTTP keep-alive with the client, all |
| 12064 | tcp-request content rules are evaluated again, so haproxy keeps a record of |
| 12065 | what sticky counters were assigned by a "tcp-request connection" versus a |
| 12066 | "tcp-request content" rule, and flushes all the content-related ones after |
| 12067 | processing an HTTP request, so that they may be evaluated again by the rules |
| 12068 | being evaluated again for the next request. This is of particular importance |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 12069 | 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] | 12070 | L7-based ACL, since tracking may change between requests. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12071 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12072 | Content-based rules are evaluated in their exact declaration order. If no |
| 12073 | rule matches or if there is no rule, the default action is to accept the |
| 12074 | contents. There is no specific limit to the number of rules which may be |
| 12075 | inserted. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12076 | |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 12077 | Several types of actions are supported : |
Willy Tarreau | 18bf01e | 2014-06-13 16:18:52 +0200 | [diff] [blame] | 12078 | - accept : the request is accepted |
Baptiste Assmann | 333939c | 2019-01-21 08:34:50 +0100 | [diff] [blame] | 12079 | - do-resolve: perform a DNS resolution |
Willy Tarreau | 18bf01e | 2014-06-13 16:18:52 +0200 | [diff] [blame] | 12080 | - reject : the request is rejected and the connection is closed |
| 12081 | - capture : the specified sample expression is captured |
Patrick Hemmer | 268a707 | 2018-05-11 12:52:31 -0400 | [diff] [blame] | 12082 | - set-priority-class <expr> | set-priority-offset <expr> |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 12083 | - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
Thierry FOURNIER | e0627bd | 2015-08-04 08:20:33 +0200 | [diff] [blame] | 12084 | - sc-inc-gpc0(<sc-id>) |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 12085 | - sc-inc-gpc1(<sc-id>) |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 12086 | - sc-set-gpt0(<sc-id>) { <int> | <expr> } |
Baptiste Assmann | e1afd4f | 2019-04-18 16:21:13 +0200 | [diff] [blame] | 12087 | - set-dst <expr> |
| 12088 | - set-dst-port <expr> |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12089 | - set-var(<var-name>) <expr> |
Christopher Faulet | ae863c6 | 2021-03-15 12:03:44 +0100 | [diff] [blame] | 12090 | - switch-mode http [ proto <name> ] |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 12091 | - unset-var(<var-name>) |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12092 | - silent-drop |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12093 | - send-spoe-group <engine-name> <group-name> |
Christopher Faulet | 579d83b | 2019-11-22 15:34:17 +0100 | [diff] [blame] | 12094 | - use-service <service-name> |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12095 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12096 | They have the same meaning as their counter-parts in "tcp-request connection" |
| 12097 | so please refer to that section for a complete description. |
Baptiste Assmann | 333939c | 2019-01-21 08:34:50 +0100 | [diff] [blame] | 12098 | For "do-resolve" action, please check the "http-request do-resolve" |
| 12099 | configuration section. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12100 | |
Willy Tarreau | f333834 | 2014-01-28 21:40:28 +0100 | [diff] [blame] | 12101 | While there is nothing mandatory about it, it is recommended to use the |
| 12102 | track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request |
| 12103 | content" rules in the frontend, and track-sc2 for "tcp-request content" |
| 12104 | rules in the backend, because that makes the configuration more readable |
| 12105 | and easier to troubleshoot, but this is just a guideline and all counters |
| 12106 | may be used everywhere. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12107 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 12108 | 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] | 12109 | the action, it is simply performed unconditionally. That can be useful for |
| 12110 | "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] | 12111 | |
Christopher Faulet | 2079a4a | 2020-10-02 11:48:57 +0200 | [diff] [blame] | 12112 | Note also that it is recommended to use a "tcp-request session" rule to track |
| 12113 | information that does *not* depend on Layer 7 contents, especially for HTTP |
| 12114 | frontends. Some HTTP processing are performed at the session level and may |
| 12115 | lead to an early rejection of the requests. Thus, the tracking at the content |
| 12116 | level may be disturbed in such case. A warning is emitted during startup to |
| 12117 | prevent, as far as possible, such unreliable usage. |
| 12118 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12119 | It is perfectly possible to match layer 7 contents with "tcp-request content" |
Christopher Faulet | 7ea509e | 2020-10-02 11:38:46 +0200 | [diff] [blame] | 12120 | rules from a TCP proxy, since HTTP-specific ACL matches are able to |
| 12121 | preliminarily parse the contents of a buffer before extracting the required |
| 12122 | data. If the buffered contents do not parse as a valid HTTP message, then the |
| 12123 | ACL does not match. The parser which is involved there is exactly the same |
| 12124 | as for all other HTTP processing, so there is no risk of parsing something |
| 12125 | differently. In an HTTP frontend or an HTTP backend, it is guaranteed that |
| 12126 | HTTP contents will always be immediately present when the rule is evaluated |
| 12127 | first because the HTTP parsing is performed in the early stages of the |
| 12128 | connection processing, at the session level. But for such proxies, using |
| 12129 | "http-request" rules is much more natural and recommended. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12130 | |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 12131 | Tracking layer7 information is also possible provided that the information |
Willy Tarreau | 4d54c7c | 2014-09-16 15:48:15 +0200 | [diff] [blame] | 12132 | are present when the rule is processed. The rule processing engine is able to |
| 12133 | wait until the inspect delay expires when the data to be tracked is not yet |
| 12134 | available. |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 12135 | |
Baptiste Assmann | e1afd4f | 2019-04-18 16:21:13 +0200 | [diff] [blame] | 12136 | The "set-dst" and "set-dst-port" are used to set respectively the destination |
| 12137 | IP and port. More information on how to use it at "http-request set-dst". |
| 12138 | |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12139 | The "set-var" is used to set the content of a variable. The variable is |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12140 | declared inline. For "tcp-request session" rules, only session-level |
| 12141 | variables can be used, without any layer7 contents. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12142 | |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12143 | <var-name> The name of the variable starts with an indication about |
| 12144 | its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 12145 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12146 | "sess" : the variable is shared with the whole session |
| 12147 | "txn" : the variable is shared with the transaction |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12148 | (request and response) |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12149 | "req" : the variable is shared only during request |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12150 | processing |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12151 | "res" : the variable is shared only during response |
| 12152 | processing |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12153 | This prefix is followed by a name. The separator is a '.'. |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 12154 | The name may only contain characters 'a-z', 'A-Z', '0-9', |
| 12155 | '.' and '_'. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12156 | |
| 12157 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 12158 | followed by some converters. |
| 12159 | |
Christopher Faulet | ae863c6 | 2021-03-15 12:03:44 +0100 | [diff] [blame] | 12160 | The "switch-mode" is used to perform a conntection upgrade. Only HTTP |
| 12161 | upgrades are supported for now. The protocol may optionally be |
| 12162 | specified. This action is only available for a proxy with the frontend |
| 12163 | capability. The connection upgrade is immediately performed, following |
| 12164 | "tcp-request content" rules are not evaluated. This upgrade method should be |
| 12165 | preferred to the implicit one consisting to rely on the backend mode. When |
| 12166 | used, it is possible to set HTTP directives in a frontend without any |
Ilya Shipitsin | b2be9a1 | 2021-04-24 13:25:42 +0500 | [diff] [blame] | 12167 | warning. These directives will be conditionaly evaluated if the HTTP upgrade |
Christopher Faulet | ae863c6 | 2021-03-15 12:03:44 +0100 | [diff] [blame] | 12168 | is performed. However, an HTTP backend must still be selected. It remains |
| 12169 | unsupported to route an HTTP connection (upgraded or not) to a TCP server. |
| 12170 | |
Christopher Faulet | 4d37e53 | 2021-03-26 14:44:00 +0100 | [diff] [blame] | 12171 | See section 4 about Proxies for more details on HTTP upgrades. |
| 12172 | |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 12173 | The "unset-var" is used to unset a variable. See above for details about |
| 12174 | <var-name>. |
| 12175 | |
Patrick Hemmer | 268a707 | 2018-05-11 12:52:31 -0400 | [diff] [blame] | 12176 | The "set-priority-class" is used to set the queue priority class of the |
| 12177 | current request. The value must be a sample expression which converts to an |
| 12178 | integer in the range -2047..2047. Results outside this range will be |
| 12179 | truncated. The priority class determines the order in which queued requests |
| 12180 | are processed. Lower values have higher priority. |
| 12181 | |
| 12182 | The "set-priority-offset" is used to set the queue priority timestamp offset |
| 12183 | of the current request. The value must be a sample expression which converts |
| 12184 | to an integer in the range -524287..524287. Results outside this range will be |
| 12185 | truncated. When a request is queued, it is ordered first by the priority |
| 12186 | class, then by the current timestamp adjusted by the given offset in |
| 12187 | milliseconds. Lower values have higher priority. |
| 12188 | Note that the resulting timestamp is is only tracked with enough precision for |
| 12189 | 524,287ms (8m44s287ms). If the request is queued long enough to where the |
| 12190 | adjusted timestamp exceeds this value, it will be misidentified as highest |
| 12191 | priority. Thus it is important to set "timeout queue" to a value, where when |
| 12192 | combined with the offset, does not exceed this limit. |
| 12193 | |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 12194 | The "send-spoe-group" is used to trigger sending of a group of SPOE |
| 12195 | messages. To do so, the SPOE engine used to send messages must be defined, as |
| 12196 | well as the SPOE group to send. Of course, the SPOE engine must refer to an |
| 12197 | existing SPOE filter. If not engine name is provided on the SPOE filter line, |
| 12198 | the SPOE agent name must be used. |
| 12199 | |
| 12200 | <engine-name> The SPOE engine name. |
| 12201 | |
| 12202 | <group-name> The SPOE group name as specified in the engine configuration. |
| 12203 | |
Christopher Faulet | 579d83b | 2019-11-22 15:34:17 +0100 | [diff] [blame] | 12204 | The "use-service" is used to executes a TCP service which will reply to the |
| 12205 | request and stop the evaluation of the rules. This service may choose to |
| 12206 | reply by sending any valid response or it may immediately close the |
| 12207 | connection without sending anything. Outside natives services, it is possible |
| 12208 | to write your own services in Lua. No further "tcp-request" rules are |
| 12209 | evaluated. |
| 12210 | |
| 12211 | Example: |
| 12212 | tcp-request content use-service lua.deny { src -f /etc/haproxy/blacklist.lst } |
| 12213 | |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12214 | Example: |
| 12215 | |
| 12216 | tcp-request content set-var(sess.my_var) src |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 12217 | tcp-request content unset-var(sess.my_var2) |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12218 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12219 | Example: |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12220 | # Accept HTTP requests containing a Host header saying "example.com" |
Christopher Faulet | ae863c6 | 2021-03-15 12:03:44 +0100 | [diff] [blame] | 12221 | # and reject everything else. (Only works for HTTP/1 connections) |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12222 | acl is_host_com hdr(Host) -i example.com |
| 12223 | tcp-request inspect-delay 30s |
Willy Tarreau | c0239e0 | 2012-04-16 14:42:55 +0200 | [diff] [blame] | 12224 | tcp-request content accept if is_host_com |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12225 | tcp-request content reject |
| 12226 | |
Christopher Faulet | ae863c6 | 2021-03-15 12:03:44 +0100 | [diff] [blame] | 12227 | # Accept HTTP requests containing a Host header saying "example.com" |
| 12228 | # and reject everything else. (works for HTTP/1 and HTTP/2 connections) |
| 12229 | acl is_host_com hdr(Host) -i example.com |
| 12230 | tcp-request inspect-delay 5s |
| 12231 | tcp-request switch-mode http if HTTP |
| 12232 | tcp-request reject # non-HTTP traffic is implicit here |
| 12233 | ... |
| 12234 | http-request reject unless is_host_com |
| 12235 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12236 | Example: |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12237 | # reject SMTP connection if client speaks first |
| 12238 | tcp-request inspect-delay 30s |
| 12239 | acl content_present req_len gt 0 |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12240 | tcp-request content reject if content_present |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12241 | |
| 12242 | # Forward HTTPS connection only if client speaks |
| 12243 | tcp-request inspect-delay 30s |
| 12244 | acl content_present req_len gt 0 |
Willy Tarreau | 68c03ab | 2010-08-06 15:08:45 +0200 | [diff] [blame] | 12245 | tcp-request content accept if content_present |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12246 | tcp-request content reject |
| 12247 | |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 12248 | Example: |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 12249 | # Track the last IP(stick-table type string) from X-Forwarded-For |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 12250 | tcp-request inspect-delay 10s |
Willy Tarreau | 4d54c7c | 2014-09-16 15:48:15 +0200 | [diff] [blame] | 12251 | tcp-request content track-sc0 hdr(x-forwarded-for,-1) |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 12252 | # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For |
| 12253 | tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1) |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 12254 | |
| 12255 | Example: |
| 12256 | # track request counts per "base" (concatenation of Host+URL) |
| 12257 | tcp-request inspect-delay 10s |
Willy Tarreau | 4d54c7c | 2014-09-16 15:48:15 +0200 | [diff] [blame] | 12258 | tcp-request content track-sc0 base table req-rate |
Willy Tarreau | 5d5b5d8 | 2012-12-09 12:00:04 +0100 | [diff] [blame] | 12259 | |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12260 | Example: track per-frontend and per-backend counters, block abusers at the |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 12261 | frontend when the backend detects abuse(and marks gpc0). |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12262 | |
| 12263 | frontend http |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12264 | # Use General Purpose Counter 0 in SC0 as a global abuse counter |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12265 | # protecting all our sites |
| 12266 | stick-table type ip size 1m expire 5m store gpc0 |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 12267 | tcp-request connection track-sc0 src |
| 12268 | tcp-request connection reject if { sc0_get_gpc0 gt 0 } |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12269 | ... |
| 12270 | use_backend http_dynamic if { path_end .php } |
| 12271 | |
| 12272 | backend http_dynamic |
| 12273 | # if a source makes too fast requests to this dynamic site (tracked |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 12274 | # by SC1), block it globally in the frontend. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12275 | 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] | 12276 | acl click_too_fast sc1_http_req_rate gt 10 |
Jarno Huuskonen | e5ae702 | 2017-04-03 14:36:21 +0300 | [diff] [blame] | 12277 | acl mark_as_abuser sc0_inc_gpc0(http) gt 0 |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 12278 | tcp-request content track-sc1 src |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 12279 | tcp-request content reject if click_too_fast mark_as_abuser |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12280 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 12281 | See section 7 about ACL usage. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12282 | |
Jarno Huuskonen | 95b012b | 2017-04-06 13:59:14 +0300 | [diff] [blame] | 12283 | See also : "tcp-request connection", "tcp-request session", |
| 12284 | "tcp-request inspect-delay", and "http-request". |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12285 | |
| 12286 | |
| 12287 | tcp-request inspect-delay <timeout> |
| 12288 | Set the maximum allowed time to wait for data during content inspection |
| 12289 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | fb35620 | 2010-08-03 14:02:05 +0200 | [diff] [blame] | 12290 | no | yes | yes | yes |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12291 | Arguments : |
| 12292 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12293 | can be in any other unit if the number is suffixed by the unit, |
| 12294 | as explained at the top of this document. |
| 12295 | |
| 12296 | People using haproxy primarily as a TCP relay are often worried about the |
| 12297 | risk of passing any type of protocol to a server without any analysis. In |
| 12298 | order to be able to analyze the request contents, we must first withhold |
| 12299 | the data then analyze them. This statement simply enables withholding of |
| 12300 | data for at most the specified amount of time. |
| 12301 | |
Willy Tarreau | fb35620 | 2010-08-03 14:02:05 +0200 | [diff] [blame] | 12302 | TCP content inspection applies very early when a connection reaches a |
| 12303 | frontend, then very early when the connection is forwarded to a backend. This |
| 12304 | means that a connection may experience a first delay in the frontend and a |
| 12305 | second delay in the backend if both have tcp-request rules. |
| 12306 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12307 | Note that when performing content inspection, haproxy will evaluate the whole |
| 12308 | 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] | 12309 | those data are partial. If no rule matches before the aforementioned delay, |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12310 | a last check is performed upon expiration, this time considering that the |
Willy Tarreau | d869b24 | 2009-03-15 14:43:58 +0100 | [diff] [blame] | 12311 | contents are definitive. If no delay is set, haproxy will not wait at all |
| 12312 | and will immediately apply a verdict based on the available information. |
| 12313 | Obviously this is unlikely to be very useful and might even be racy, so such |
| 12314 | setups are not recommended. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12315 | |
| 12316 | As soon as a rule matches, the request is released and continues as usual. If |
| 12317 | the timeout is reached and no rule matches, the default policy will be to let |
| 12318 | it pass through unaffected. |
| 12319 | |
| 12320 | For most protocols, it is enough to set it to a few seconds, as most clients |
| 12321 | send the full request immediately upon connection. Add 3 or more seconds to |
| 12322 | 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] | 12323 | to use large values, for instance to ensure that the client never talks |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12324 | before the server (e.g. SMTP), or to wait for a client to talk before passing |
| 12325 | data to the server (e.g. SSL). Note that the client timeout must cover at |
Willy Tarreau | b824b00 | 2010-09-29 16:36:16 +0200 | [diff] [blame] | 12326 | least the inspection delay, otherwise it will expire first. If the client |
| 12327 | closes the connection or if the buffer is full, the delay immediately expires |
| 12328 | since the contents will not be able to change anymore. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12329 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 12330 | See also : "tcp-request content accept", "tcp-request content reject", |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 12331 | "timeout client". |
| 12332 | |
| 12333 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12334 | tcp-response content <action> [{if | unless} <condition>] |
| 12335 | Perform an action on a session response depending on a layer 4-7 condition |
| 12336 | May be used in sections : defaults | frontend | listen | backend |
| 12337 | no | no | yes | yes |
| 12338 | Arguments : |
Willy Tarreau | c870bfd | 2015-09-28 18:47:38 +0200 | [diff] [blame] | 12339 | <action> defines the action to perform if the condition applies. See |
| 12340 | below. |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12341 | |
| 12342 | <condition> is a standard layer 4-7 ACL-based condition (see section 7). |
| 12343 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12344 | Response contents can be analyzed at an early stage of response processing |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12345 | called "TCP content inspection". During this stage, ACL-based rules are |
| 12346 | evaluated every time the response contents are updated, until either an |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 12347 | "accept", "close" or a "reject" rule matches, or a TCP response inspection |
| 12348 | delay is set and expires with no matching rule. |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12349 | |
| 12350 | Most often, these decisions will consider a protocol recognition or validity. |
| 12351 | |
| 12352 | Content-based rules are evaluated in their exact declaration order. If no |
| 12353 | rule matches or if there is no rule, the default action is to accept the |
| 12354 | contents. There is no specific limit to the number of rules which may be |
| 12355 | inserted. |
| 12356 | |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 12357 | Several types of actions are supported : |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12358 | - accept : |
| 12359 | accepts the response if the condition is true (when used with "if") |
| 12360 | or false (when used with "unless"). The first such rule executed ends |
| 12361 | the rules evaluation. |
| 12362 | |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 12363 | - close : |
| 12364 | immediately closes the connection with the server if the condition is |
| 12365 | true (when used with "if"), or false (when used with "unless"). The |
| 12366 | first such rule executed ends the rules evaluation. The main purpose of |
| 12367 | this action is to force a connection to be finished between a client |
| 12368 | and a server after an exchange when the application protocol expects |
| 12369 | 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] | 12370 | connections which take significant resources on servers with certain |
Willy Tarreau | cc1e04b | 2013-09-11 23:20:29 +0200 | [diff] [blame] | 12371 | protocols. |
| 12372 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12373 | - reject : |
| 12374 | rejects the response if the condition is true (when used with "if") |
| 12375 | or false (when used with "unless"). The first such rule executed ends |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 12376 | the rules evaluation. Rejected session are immediately closed. |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12377 | |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12378 | - set-var(<var-name>) <expr> |
| 12379 | Sets a variable. |
| 12380 | |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 12381 | - unset-var(<var-name>) |
| 12382 | Unsets a variable. |
| 12383 | |
Thierry FOURNIER | e0627bd | 2015-08-04 08:20:33 +0200 | [diff] [blame] | 12384 | - sc-inc-gpc0(<sc-id>): |
| 12385 | This action increments the GPC0 counter according to the sticky |
| 12386 | counter designated by <sc-id>. If an error occurs, this action fails |
| 12387 | silently and the actions evaluation continues. |
| 12388 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 12389 | - sc-inc-gpc1(<sc-id>): |
| 12390 | This action increments the GPC1 counter according to the sticky |
| 12391 | counter designated by <sc-id>. If an error occurs, this action fails |
| 12392 | silently and the actions evaluation continues. |
| 12393 | |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 12394 | - sc-set-gpt0(<sc-id>) { <int> | <expr> } |
| 12395 | This action sets the 32-bit unsigned GPT0 tag according to the sticky |
| 12396 | counter designated by <sc-id> and the value of <int>/<expr>. The |
| 12397 | expected result is a boolean. If an error occurs, this action silently |
| 12398 | fails and the actions evaluation continues. |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 12399 | |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12400 | - "silent-drop" : |
| 12401 | This stops the evaluation of the rules and makes the client-facing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12402 | connection suddenly disappear using a system-dependent way that tries |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12403 | to prevent the client from being notified. The effect it then that the |
| 12404 | client still sees an established connection while there's none on |
| 12405 | HAProxy. The purpose is to achieve a comparable effect to "tarpit" |
| 12406 | except that it doesn't use any local resource at all on the machine |
| 12407 | running HAProxy. It can resist much higher loads than "tarpit", and |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12408 | slow down stronger attackers. It is important to understand the impact |
| 12409 | of using this mechanism. All stateful equipment placed between the |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12410 | client and HAProxy (firewalls, proxies, load balancers) will also keep |
| 12411 | the established connection for a long time and may suffer from this |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12412 | action. On modern Linux systems running with enough privileges, the |
Willy Tarreau | 2d392c2 | 2015-08-24 01:43:45 +0200 | [diff] [blame] | 12413 | TCP_REPAIR socket option is used to block the emission of a TCP |
| 12414 | reset. On other systems, the socket's TTL is reduced to 1 so that the |
| 12415 | TCP reset doesn't pass the first router, though it's still delivered to |
| 12416 | local networks. Do not use it unless you fully understand how it works. |
| 12417 | |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 12418 | - send-spoe-group <engine-name> <group-name> |
| 12419 | Send a group of SPOE messages. |
| 12420 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12421 | Note that the "if/unless" condition is optional. If no condition is set on |
| 12422 | the action, it is simply performed unconditionally. That can be useful for |
| 12423 | for changing the default action to a reject. |
| 12424 | |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 12425 | It is perfectly possible to match layer 7 contents with "tcp-response |
| 12426 | content" rules, but then it is important to ensure that a full response has |
| 12427 | been buffered, otherwise no contents will match. In order to achieve this, |
| 12428 | the best solution involves detecting the HTTP protocol during the inspection |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12429 | period. |
| 12430 | |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12431 | The "set-var" is used to set the content of a variable. The variable is |
| 12432 | declared inline. |
| 12433 | |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12434 | <var-name> The name of the variable starts with an indication about |
| 12435 | its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 12436 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12437 | "sess" : the variable is shared with the whole session |
| 12438 | "txn" : the variable is shared with the transaction |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12439 | (request and response) |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12440 | "req" : the variable is shared only during request |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12441 | processing |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 12442 | "res" : the variable is shared only during response |
| 12443 | processing |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12444 | This prefix is followed by a name. The separator is a '.'. |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 12445 | The name may only contain characters 'a-z', 'A-Z', '0-9', |
| 12446 | '.' and '_'. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 12447 | |
| 12448 | <expr> Is a standard HAProxy expression formed by a sample-fetch |
| 12449 | followed by some converters. |
| 12450 | |
| 12451 | Example: |
| 12452 | |
| 12453 | tcp-request content set-var(sess.my_var) src |
| 12454 | |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 12455 | The "unset-var" is used to unset a variable. See above for details about |
| 12456 | <var-name>. |
| 12457 | |
| 12458 | Example: |
| 12459 | |
| 12460 | tcp-request content unset-var(sess.my_var) |
| 12461 | |
Christopher Faulet | 76c09ef | 2017-09-21 11:03:52 +0200 | [diff] [blame] | 12462 | The "send-spoe-group" is used to trigger sending of a group of SPOE |
| 12463 | messages. To do so, the SPOE engine used to send messages must be defined, as |
| 12464 | well as the SPOE group to send. Of course, the SPOE engine must refer to an |
| 12465 | existing SPOE filter. If not engine name is provided on the SPOE filter line, |
| 12466 | the SPOE agent name must be used. |
| 12467 | |
| 12468 | <engine-name> The SPOE engine name. |
| 12469 | |
| 12470 | <group-name> The SPOE group name as specified in the engine configuration. |
| 12471 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12472 | See section 7 about ACL usage. |
| 12473 | |
| 12474 | See also : "tcp-request content", "tcp-response inspect-delay" |
| 12475 | |
| 12476 | |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12477 | tcp-request session <action> [{if | unless} <condition>] |
| 12478 | Perform an action on a validated session depending on a layer 5 condition |
| 12479 | May be used in sections : defaults | frontend | listen | backend |
| 12480 | no | yes | yes | no |
| 12481 | Arguments : |
| 12482 | <action> defines the action to perform if the condition applies. See |
| 12483 | below. |
| 12484 | |
| 12485 | <condition> is a standard layer5-only ACL-based condition (see section 7). |
| 12486 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12487 | Once a session is validated, (i.e. after all handshakes have been completed), |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12488 | it is possible to evaluate some conditions to decide whether this session |
| 12489 | must be accepted or dropped or have its counters tracked. Those conditions |
| 12490 | cannot make use of any data contents because no buffers are allocated yet and |
| 12491 | the processing cannot wait at this stage. The main use case it to copy some |
| 12492 | early information into variables (since variables are accessible in the |
| 12493 | session), or to keep track of some information collected after the handshake, |
| 12494 | such as SSL-level elements (SNI, ciphers, client cert's CN) or information |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12495 | from the PROXY protocol header (e.g. track a source forwarded this way). The |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12496 | extracted information can thus be copied to a variable or tracked using |
| 12497 | "track-sc" rules. Of course it is also possible to decide to accept/reject as |
| 12498 | with other rulesets. Most operations performed here could also be performed |
| 12499 | in "tcp-request content" rules, except that in HTTP these rules are evaluated |
| 12500 | for each new request, and that might not always be acceptable. For example a |
| 12501 | rule might increment a counter on each evaluation. It would also be possible |
| 12502 | that a country is resolved by geolocation from the source IP address, |
| 12503 | assigned to a session-wide variable, then the source address rewritten from |
| 12504 | an HTTP header for all requests. If some contents need to be inspected in |
| 12505 | order to take the decision, the "tcp-request content" statements must be used |
| 12506 | instead. |
| 12507 | |
| 12508 | The "tcp-request session" rules are evaluated in their exact declaration |
| 12509 | order. If no rule matches or if there is no rule, the default action is to |
| 12510 | accept the incoming session. There is no specific limit to the number of |
| 12511 | rules which may be inserted. |
| 12512 | |
| 12513 | Several types of actions are supported : |
| 12514 | - accept : the request is accepted |
| 12515 | - reject : the request is rejected and the connection is closed |
| 12516 | - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
| 12517 | - sc-inc-gpc0(<sc-id>) |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 12518 | - sc-inc-gpc1(<sc-id>) |
Cédric Dufour | 0d7712d | 2019-11-06 18:38:53 +0100 | [diff] [blame] | 12519 | - sc-set-gpt0(<sc-id>) { <int> | <expr> } |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12520 | - set-var(<var-name>) <expr> |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 12521 | - unset-var(<var-name>) |
Willy Tarreau | 4f61429 | 2016-10-21 17:49:36 +0200 | [diff] [blame] | 12522 | - silent-drop |
| 12523 | |
| 12524 | These actions have the same meaning as their respective counter-parts in |
| 12525 | "tcp-request connection" and "tcp-request content", so please refer to these |
| 12526 | sections for a complete description. |
| 12527 | |
| 12528 | Note that the "if/unless" condition is optional. If no condition is set on |
| 12529 | the action, it is simply performed unconditionally. That can be useful for |
| 12530 | "track-sc*" actions as well as for changing the default action to a reject. |
| 12531 | |
| 12532 | Example: track the original source address by default, or the one advertised |
| 12533 | in the PROXY protocol header for connection coming from the local |
| 12534 | proxies. The first connection-level rule enables receipt of the |
| 12535 | PROXY protocol for these ones, the second rule tracks whatever |
| 12536 | address we decide to keep after optional decoding. |
| 12537 | |
| 12538 | tcp-request connection expect-proxy layer4 if { src -f proxies.lst } |
| 12539 | tcp-request session track-sc0 src |
| 12540 | |
| 12541 | Example: accept all sessions from white-listed hosts, reject too fast |
| 12542 | sessions without counting them, and track accepted sessions. |
| 12543 | This results in session rate being capped from abusive sources. |
| 12544 | |
| 12545 | tcp-request session accept if { src -f /etc/haproxy/whitelist.lst } |
| 12546 | tcp-request session reject if { src_sess_rate gt 10 } |
| 12547 | tcp-request session track-sc0 src |
| 12548 | |
| 12549 | Example: accept all sessions from white-listed hosts, count all other |
| 12550 | sessions and reject too fast ones. This results in abusive ones |
| 12551 | being blocked as long as they don't slow down. |
| 12552 | |
| 12553 | tcp-request session accept if { src -f /etc/haproxy/whitelist.lst } |
| 12554 | tcp-request session track-sc0 src |
| 12555 | tcp-request session reject if { sc0_sess_rate gt 10 } |
| 12556 | |
| 12557 | See section 7 about ACL usage. |
| 12558 | |
| 12559 | See also : "tcp-request connection", "tcp-request content", "stick-table" |
| 12560 | |
| 12561 | |
Emeric Brun | 0a3b67f | 2010-09-24 15:34:53 +0200 | [diff] [blame] | 12562 | tcp-response inspect-delay <timeout> |
| 12563 | Set the maximum allowed time to wait for a response during content inspection |
| 12564 | May be used in sections : defaults | frontend | listen | backend |
| 12565 | no | no | yes | yes |
| 12566 | Arguments : |
| 12567 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12568 | can be in any other unit if the number is suffixed by the unit, |
| 12569 | as explained at the top of this document. |
| 12570 | |
| 12571 | See also : "tcp-response content", "tcp-request inspect-delay". |
| 12572 | |
| 12573 | |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 12574 | timeout check <timeout> |
| 12575 | Set additional check timeout, but only after a connection has been already |
| 12576 | established. |
| 12577 | |
| 12578 | May be used in sections: defaults | frontend | listen | backend |
| 12579 | yes | no | yes | yes |
| 12580 | Arguments: |
| 12581 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12582 | can be in any other unit if the number is suffixed by the unit, |
| 12583 | as explained at the top of this document. |
| 12584 | |
| 12585 | If set, haproxy uses min("timeout connect", "inter") as a connect timeout |
| 12586 | for check and "timeout check" as an additional read timeout. The "min" is |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12587 | used so that people running with *very* long "timeout connect" (e.g. those |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 12588 | 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] | 12589 | (Please also note that there is no valid reason to have such long connect |
| 12590 | timeouts, because "timeout queue" and "timeout tarpit" can always be used to |
| 12591 | avoid that). |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 12592 | |
| 12593 | If "timeout check" is not set haproxy uses "inter" for complete check |
| 12594 | timeout (connect + read) exactly like all <1.3.15 version. |
| 12595 | |
| 12596 | In most cases check request is much simpler and faster to handle than normal |
| 12597 | 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] | 12598 | be smaller than "timeout server". |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 12599 | |
| 12600 | This parameter is specific to backends, but can be specified once for all in |
| 12601 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 12602 | forget about it. |
| 12603 | |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 12604 | See also: "timeout connect", "timeout queue", "timeout server", |
| 12605 | "timeout tarpit". |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 12606 | |
| 12607 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12608 | timeout client <timeout> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12609 | Set the maximum inactivity time on the client side. |
| 12610 | May be used in sections : defaults | frontend | listen | backend |
| 12611 | yes | yes | yes | no |
| 12612 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12613 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12614 | can be in any other unit if the number is suffixed by the unit, |
| 12615 | as explained at the top of this document. |
| 12616 | |
| 12617 | The inactivity timeout applies when the client is expected to acknowledge or |
| 12618 | send data. In HTTP mode, this timeout is particularly important to consider |
| 12619 | during the first phase, when the client sends the request, and during the |
Baptiste Assmann | 2e1941e | 2016-03-06 23:24:12 +0100 | [diff] [blame] | 12620 | response while it is reading data sent by the server. That said, for the |
| 12621 | first phase, it is preferable to set the "timeout http-request" to better |
| 12622 | protect HAProxy from Slowloris like attacks. The value is specified in |
| 12623 | milliseconds by default, but can be in any other unit if the number is |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12624 | suffixed by the unit, as specified at the top of this document. In TCP mode |
| 12625 | (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| 12626 | 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] | 12627 | 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] | 12628 | losses by specifying timeouts that are slightly above multiples of 3 seconds |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12629 | (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived |
| 12630 | sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel", |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12631 | which overrides "timeout client" and "timeout server" for tunnels, as well as |
| 12632 | "timeout client-fin" for half-closed connections. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12633 | |
| 12634 | This parameter is specific to frontends, but can be specified once for all in |
| 12635 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 12636 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 12637 | is not recommended. Such a usage is accepted and works but reports a warning |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 12638 | during startup because it may result in accumulation of expired sessions in |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12639 | the system if the system's timeouts are not configured either. |
| 12640 | |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 12641 | This also applies to HTTP/2 connections, which will be closed with GOAWAY. |
Lukas Tribus | 75df9d7 | 2017-11-24 19:05:12 +0100 | [diff] [blame] | 12642 | |
Tim Duesterhus | 86e6b6e | 2019-05-14 20:57:59 +0200 | [diff] [blame] | 12643 | See also : "timeout server", "timeout tunnel", "timeout http-request". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12644 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12645 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12646 | timeout client-fin <timeout> |
| 12647 | Set the inactivity timeout on the client side for half-closed connections. |
| 12648 | May be used in sections : defaults | frontend | listen | backend |
| 12649 | yes | yes | yes | no |
| 12650 | Arguments : |
| 12651 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12652 | can be in any other unit if the number is suffixed by the unit, |
| 12653 | as explained at the top of this document. |
| 12654 | |
| 12655 | The inactivity timeout applies when the client is expected to acknowledge or |
| 12656 | send data while one direction is already shut down. This timeout is different |
| 12657 | from "timeout client" in that it only applies to connections which are closed |
| 12658 | in one direction. This is particularly useful to avoid keeping connections in |
| 12659 | FIN_WAIT state for too long when clients do not disconnect cleanly. This |
| 12660 | problem is particularly common long connections such as RDP or WebSocket. |
| 12661 | Note that this timeout can override "timeout tunnel" when a connection shuts |
Willy Tarreau | 599391a | 2017-11-24 10:16:00 +0100 | [diff] [blame] | 12662 | down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY |
| 12663 | frame was sent, often indicating an expectation that the connection quickly |
| 12664 | ends. |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12665 | |
| 12666 | This parameter is specific to frontends, but can be specified once for all in |
| 12667 | "defaults" sections. By default it is not set, so half-closed connections |
| 12668 | will use the other timeouts (timeout.client or timeout.tunnel). |
| 12669 | |
| 12670 | See also : "timeout client", "timeout server-fin", and "timeout tunnel". |
| 12671 | |
| 12672 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12673 | timeout connect <timeout> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12674 | Set the maximum time to wait for a connection attempt to a server to succeed. |
| 12675 | May be used in sections : defaults | frontend | listen | backend |
| 12676 | yes | no | yes | yes |
| 12677 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12678 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12679 | can be in any other unit if the number is suffixed by the unit, |
| 12680 | as explained at the top of this document. |
| 12681 | |
| 12682 | 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] | 12683 | 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] | 12684 | cover one or several TCP packet losses by specifying timeouts that are |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12685 | slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 12686 | connect timeout also presets both queue and tarpit timeouts to the same value |
| 12687 | if these have not been specified. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12688 | |
| 12689 | This parameter is specific to backends, but can be specified once for all in |
| 12690 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 12691 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 12692 | is not recommended. Such a usage is accepted and works but reports a warning |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 12693 | during startup because it may result in accumulation of failed sessions in |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12694 | the system if the system's timeouts are not configured either. |
| 12695 | |
Tim Duesterhus | 86e6b6e | 2019-05-14 20:57:59 +0200 | [diff] [blame] | 12696 | See also: "timeout check", "timeout queue", "timeout server", "timeout tarpit". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12697 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12698 | |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 12699 | timeout http-keep-alive <timeout> |
| 12700 | Set the maximum allowed time to wait for a new HTTP request to appear |
| 12701 | May be used in sections : defaults | frontend | listen | backend |
| 12702 | yes | yes | yes | yes |
| 12703 | Arguments : |
| 12704 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12705 | can be in any other unit if the number is suffixed by the unit, |
| 12706 | as explained at the top of this document. |
| 12707 | |
| 12708 | By default, the time to wait for a new request in case of keep-alive is set |
| 12709 | by "timeout http-request". However this is not always convenient because some |
| 12710 | people want very short keep-alive timeouts in order to release connections |
| 12711 | faster, and others prefer to have larger ones but still have short timeouts |
| 12712 | once the request has started to present itself. |
| 12713 | |
| 12714 | The "http-keep-alive" timeout covers these needs. It will define how long to |
| 12715 | wait for a new HTTP request to start coming after a response was sent. Once |
| 12716 | the first byte of request has been seen, the "http-request" timeout is used |
| 12717 | to wait for the complete request to come. Note that empty lines prior to a |
| 12718 | new request do not refresh the timeout and are not counted as a new request. |
| 12719 | |
| 12720 | There is also another difference between the two timeouts : when a connection |
| 12721 | expires during timeout http-keep-alive, no error is returned, the connection |
| 12722 | just closes. If the connection expires in "http-request" while waiting for a |
| 12723 | connection to complete, a HTTP 408 error is returned. |
| 12724 | |
| 12725 | In general it is optimal to set this value to a few tens to hundreds of |
| 12726 | milliseconds, to allow users to fetch all objects of a page at once but |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12727 | without waiting for further clicks. Also, if set to a very small value (e.g. |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 12728 | 1 millisecond) it will probably only accept pipelined requests but not the |
| 12729 | 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] | 12730 | with tens to hundreds of thousands of clients. |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 12731 | |
| 12732 | If this parameter is not set, the "http-request" timeout applies, and if both |
| 12733 | are not set, "timeout client" still applies at the lower level. It should be |
| 12734 | set in the frontend to take effect, unless the frontend is in TCP mode, in |
| 12735 | which case the HTTP backend's timeout will be used. |
| 12736 | |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 12737 | When using HTTP/2 "timeout client" is applied instead. This is so we can keep |
| 12738 | using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2 |
Lukas Tribus | 75df9d7 | 2017-11-24 19:05:12 +0100 | [diff] [blame] | 12739 | (where we only have one connection per client and a connection setup). |
| 12740 | |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 12741 | See also : "timeout http-request", "timeout client". |
| 12742 | |
| 12743 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12744 | timeout http-request <timeout> |
| 12745 | Set the maximum allowed time to wait for a complete HTTP request |
| 12746 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | cd7afc0 | 2009-07-12 10:03:17 +0200 | [diff] [blame] | 12747 | yes | yes | yes | yes |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12748 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12749 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12750 | can be in any other unit if the number is suffixed by the unit, |
| 12751 | as explained at the top of this document. |
| 12752 | |
| 12753 | In order to offer DoS protection, it may be required to lower the maximum |
| 12754 | accepted time to receive a complete HTTP request without affecting the client |
| 12755 | timeout. This helps protecting against established connections on which |
| 12756 | nothing is sent. The client timeout cannot offer a good protection against |
| 12757 | this abuse because it is an inactivity timeout, which means that if the |
| 12758 | attacker sends one character every now and then, the timeout will not |
| 12759 | trigger. With the HTTP request timeout, no matter what speed the client |
Willy Tarreau | 2705a61 | 2014-05-23 17:38:34 +0200 | [diff] [blame] | 12760 | types, the request will be aborted if it does not complete in time. When the |
| 12761 | timeout expires, an HTTP 408 response is sent to the client to inform it |
| 12762 | about the problem, and the connection is closed. The logs will report |
| 12763 | termination codes "cR". Some recent browsers are having problems with this |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12764 | standard, well-documented behavior, so it might be needed to hide the 408 |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 12765 | code using "option http-ignore-probes" or "errorfile 408 /dev/null". See |
| 12766 | more details in the explanations of the "cR" termination code in section 8.5. |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12767 | |
Baptiste Assmann | eccdf43 | 2015-10-28 13:49:01 +0100 | [diff] [blame] | 12768 | By default, this timeout only applies to the header part of the request, |
| 12769 | and not to any data. As soon as the empty line is received, this timeout is |
| 12770 | not used anymore. When combined with "option http-buffer-request", this |
| 12771 | timeout also applies to the body of the request.. |
| 12772 | It is used again on keep-alive connections to wait for a second |
Willy Tarreau | b16a574 | 2010-01-10 14:46:16 +0100 | [diff] [blame] | 12773 | request if "timeout http-keep-alive" is not set. |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12774 | |
| 12775 | Generally it is enough to set it to a few seconds, as most clients send the |
| 12776 | full request immediately upon connection. Add 3 or more seconds to cover TCP |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12777 | retransmits but that's all. Setting it to very low values (e.g. 50 ms) will |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12778 | generally work on local networks as long as there are no packet losses. This |
| 12779 | will prevent people from sending bare HTTP requests using telnet. |
| 12780 | |
| 12781 | 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] | 12782 | chunk of the incoming request. It should be set in the frontend to take |
| 12783 | effect, unless the frontend is in TCP mode, in which case the HTTP backend's |
| 12784 | timeout will be used. |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12785 | |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 12786 | See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and |
Baptiste Assmann | eccdf43 | 2015-10-28 13:49:01 +0100 | [diff] [blame] | 12787 | "timeout client", "option http-buffer-request". |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 12788 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12789 | |
| 12790 | timeout queue <timeout> |
| 12791 | Set the maximum time to wait in the queue for a connection slot to be free |
| 12792 | May be used in sections : defaults | frontend | listen | backend |
| 12793 | yes | no | yes | yes |
| 12794 | Arguments : |
| 12795 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12796 | can be in any other unit if the number is suffixed by the unit, |
| 12797 | as explained at the top of this document. |
| 12798 | |
| 12799 | When a server's maxconn is reached, connections are left pending in a queue |
| 12800 | which may be server-specific or global to the backend. In order not to wait |
| 12801 | indefinitely, a timeout is applied to requests pending in the queue. If the |
| 12802 | timeout is reached, it is considered that the request will almost never be |
| 12803 | served, so it is dropped and a 503 error is returned to the client. |
| 12804 | |
| 12805 | The "timeout queue" statement allows to fix the maximum time for a request to |
| 12806 | be left pending in a queue. If unspecified, the same value as the backend's |
| 12807 | connection timeout ("timeout connect") is used, for backwards compatibility |
| 12808 | with older versions with no "timeout queue" parameter. |
| 12809 | |
Tim Duesterhus | 86e6b6e | 2019-05-14 20:57:59 +0200 | [diff] [blame] | 12810 | See also : "timeout connect". |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12811 | |
| 12812 | |
| 12813 | timeout server <timeout> |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12814 | Set the maximum inactivity time on the server side. |
| 12815 | May be used in sections : defaults | frontend | listen | backend |
| 12816 | yes | no | yes | yes |
| 12817 | Arguments : |
| 12818 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12819 | can be in any other unit if the number is suffixed by the unit, |
| 12820 | as explained at the top of this document. |
| 12821 | |
| 12822 | The inactivity timeout applies when the server is expected to acknowledge or |
| 12823 | send data. In HTTP mode, this timeout is particularly important to consider |
| 12824 | during the first phase of the server's response, when it has to send the |
| 12825 | headers, as it directly represents the server's processing time for the |
| 12826 | request. To find out what value to put there, it's often good to start with |
| 12827 | what would be considered as unacceptable response times, then check the logs |
| 12828 | to observe the response time distribution, and adjust the value accordingly. |
| 12829 | |
| 12830 | The value is specified in milliseconds by default, but can be in any other |
| 12831 | unit if the number is suffixed by the unit, as specified at the top of this |
| 12832 | document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly |
| 12833 | recommended that the client timeout remains equal to the server timeout in |
| 12834 | order to avoid complex situations to debug. Whatever the expected server |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 12835 | 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] | 12836 | packet losses by specifying timeouts that are slightly above multiples of 3 |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12837 | seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed |
| 12838 | with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12839 | "timeout tunnel", which overrides "timeout client" and "timeout server" for |
| 12840 | tunnels. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12841 | |
| 12842 | This parameter is specific to backends, but can be specified once for all in |
| 12843 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 12844 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 12845 | is not recommended. Such a usage is accepted and works but reports a warning |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 12846 | during startup because it may result in accumulation of expired sessions in |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12847 | the system if the system's timeouts are not configured either. |
| 12848 | |
Tim Duesterhus | 86e6b6e | 2019-05-14 20:57:59 +0200 | [diff] [blame] | 12849 | See also : "timeout client" and "timeout tunnel". |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12850 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12851 | |
| 12852 | timeout server-fin <timeout> |
| 12853 | Set the inactivity timeout on the server side for half-closed connections. |
| 12854 | May be used in sections : defaults | frontend | listen | backend |
| 12855 | yes | no | yes | yes |
| 12856 | Arguments : |
| 12857 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12858 | can be in any other unit if the number is suffixed by the unit, |
| 12859 | as explained at the top of this document. |
| 12860 | |
| 12861 | The inactivity timeout applies when the server is expected to acknowledge or |
| 12862 | send data while one direction is already shut down. This timeout is different |
| 12863 | from "timeout server" in that it only applies to connections which are closed |
| 12864 | in one direction. This is particularly useful to avoid keeping connections in |
| 12865 | FIN_WAIT state for too long when a remote server does not disconnect cleanly. |
| 12866 | This problem is particularly common long connections such as RDP or WebSocket. |
| 12867 | Note that this timeout can override "timeout tunnel" when a connection shuts |
| 12868 | down in one direction. This setting was provided for completeness, but in most |
| 12869 | situations, it should not be needed. |
| 12870 | |
| 12871 | This parameter is specific to backends, but can be specified once for all in |
| 12872 | "defaults" sections. By default it is not set, so half-closed connections |
| 12873 | will use the other timeouts (timeout.server or timeout.tunnel). |
| 12874 | |
| 12875 | See also : "timeout client-fin", "timeout server", and "timeout tunnel". |
| 12876 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12877 | |
| 12878 | timeout tarpit <timeout> |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 12879 | Set the duration for which tarpitted connections will be maintained |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12880 | May be used in sections : defaults | frontend | listen | backend |
| 12881 | yes | yes | yes | yes |
| 12882 | Arguments : |
| 12883 | <timeout> is the tarpit duration specified in milliseconds by default, but |
| 12884 | can be in any other unit if the number is suffixed by the unit, |
| 12885 | as explained at the top of this document. |
| 12886 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 12887 | When a connection is tarpitted using "http-request tarpit", it is maintained |
| 12888 | open with no activity for a certain amount of time, then closed. "timeout |
| 12889 | tarpit" defines how long it will be maintained open. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12890 | |
| 12891 | The value is specified in milliseconds by default, but can be in any other |
| 12892 | unit if the number is suffixed by the unit, as specified at the top of this |
| 12893 | document. If unspecified, the same value as the backend's connection timeout |
| 12894 | ("timeout connect") is used, for backwards compatibility with older versions |
Cyril Bonté | 78caf84 | 2010-03-10 22:41:43 +0100 | [diff] [blame] | 12895 | with no "timeout tarpit" parameter. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12896 | |
Tim Duesterhus | 86e6b6e | 2019-05-14 20:57:59 +0200 | [diff] [blame] | 12897 | See also : "timeout connect". |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12898 | |
| 12899 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12900 | timeout tunnel <timeout> |
| 12901 | Set the maximum inactivity time on the client and server side for tunnels. |
| 12902 | May be used in sections : defaults | frontend | listen | backend |
| 12903 | yes | no | yes | yes |
| 12904 | Arguments : |
| 12905 | <timeout> is the timeout value specified in milliseconds by default, but |
| 12906 | can be in any other unit if the number is suffixed by the unit, |
| 12907 | as explained at the top of this document. |
| 12908 | |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 12909 | The tunnel timeout applies when a bidirectional connection is established |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12910 | between a client and a server, and the connection remains inactive in both |
| 12911 | directions. This timeout supersedes both the client and server timeouts once |
| 12912 | the connection becomes a tunnel. In TCP, this timeout is used as soon as no |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12913 | analyzer remains attached to either connection (e.g. tcp content rules are |
| 12914 | accepted). In HTTP, this timeout is used when a connection is upgraded (e.g. |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12915 | when switching to the WebSocket protocol, or forwarding a CONNECT request |
| 12916 | to a proxy), or after the first response when no keepalive/close option is |
| 12917 | specified. |
| 12918 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12919 | Since this timeout is usually used in conjunction with long-lived connections, |
| 12920 | it usually is a good idea to also set "timeout client-fin" to handle the |
| 12921 | situation where a client suddenly disappears from the net and does not |
| 12922 | acknowledge a close, or sends a shutdown and does not acknowledge pending |
| 12923 | data anymore. This can happen in lossy networks where firewalls are present, |
| 12924 | and is detected by the presence of large amounts of sessions in a FIN_WAIT |
| 12925 | state. |
| 12926 | |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12927 | The value is specified in milliseconds by default, but can be in any other |
| 12928 | unit if the number is suffixed by the unit, as specified at the top of this |
| 12929 | document. Whatever the expected normal idle time, it is a good practice to |
| 12930 | cover at least one or several TCP packet losses by specifying timeouts that |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 12931 | are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum). |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12932 | |
| 12933 | This parameter is specific to backends, but can be specified once for all in |
| 12934 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 12935 | forget about it. |
| 12936 | |
| 12937 | Example : |
| 12938 | defaults http |
| 12939 | option http-server-close |
| 12940 | timeout connect 5s |
| 12941 | timeout client 30s |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12942 | timeout client-fin 30s |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12943 | timeout server 30s |
| 12944 | timeout tunnel 1h # timeout to use with WebSocket and CONNECT |
| 12945 | |
Willy Tarreau | 05cdd96 | 2014-05-10 14:30:07 +0200 | [diff] [blame] | 12946 | See also : "timeout client", "timeout client-fin", "timeout server". |
Willy Tarreau | ce887fd | 2012-05-12 12:50:00 +0200 | [diff] [blame] | 12947 | |
| 12948 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12949 | transparent (deprecated) |
| 12950 | Enable client-side transparent proxying |
| 12951 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 4b1f859 | 2008-12-23 23:13:55 +0100 | [diff] [blame] | 12952 | yes | no | yes | yes |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12953 | Arguments : none |
| 12954 | |
| 12955 | This keyword was introduced in order to provide layer 7 persistence to layer |
| 12956 | 3 load balancers. The idea is to use the OS's ability to redirect an incoming |
| 12957 | connection for a remote address to a local process (here HAProxy), and let |
| 12958 | this process know what address was initially requested. When this option is |
| 12959 | used, sessions without cookies will be forwarded to the original destination |
| 12960 | IP address of the incoming request (which should match that of another |
| 12961 | equipment), while requests with cookies will still be forwarded to the |
| 12962 | appropriate server. |
| 12963 | |
| 12964 | The "transparent" keyword is deprecated, use "option transparent" instead. |
| 12965 | |
| 12966 | Note that contrary to a common belief, this option does NOT make HAProxy |
| 12967 | present the client's IP to the server when establishing the connection. |
| 12968 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 12969 | See also: "option transparent" |
| 12970 | |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12971 | unique-id-format <string> |
| 12972 | Generate a unique ID for each request. |
| 12973 | May be used in sections : defaults | frontend | listen | backend |
| 12974 | yes | yes | yes | no |
| 12975 | Arguments : |
| 12976 | <string> is a log-format string. |
| 12977 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 12978 | This keyword creates a ID for each request using the custom log format. A |
| 12979 | unique ID is useful to trace a request passing through many components of |
| 12980 | a complex infrastructure. The newly created ID may also be logged using the |
| 12981 | %ID tag the log-format string. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12982 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 12983 | The format should be composed from elements that are guaranteed to be |
| 12984 | unique when combined together. For instance, if multiple haproxy instances |
| 12985 | are involved, it might be important to include the node name. It is often |
| 12986 | needed to log the incoming connection's source and destination addresses |
| 12987 | and ports. Note that since multiple requests may be performed over the same |
| 12988 | connection, including a request counter may help differentiate them. |
| 12989 | Similarly, a timestamp may protect against a rollover of the counter. |
| 12990 | Logging the process ID will avoid collisions after a service restart. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12991 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 12992 | It is recommended to use hexadecimal notation for many fields since it |
| 12993 | makes them more compact and saves space in logs. |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12994 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 12995 | Example: |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12996 | |
Julien Vehent | f21be32 | 2014-03-07 08:27:34 -0500 | [diff] [blame] | 12997 | unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 12998 | |
| 12999 | will generate: |
| 13000 | |
| 13001 | 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A |
| 13002 | |
| 13003 | See also: "unique-id-header" |
| 13004 | |
| 13005 | unique-id-header <name> |
| 13006 | Add a unique ID header in the HTTP request. |
| 13007 | May be used in sections : defaults | frontend | listen | backend |
| 13008 | yes | yes | yes | no |
| 13009 | Arguments : |
| 13010 | <name> is the name of the header. |
| 13011 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 13012 | Add a unique-id header in the HTTP request sent to the server, using the |
| 13013 | 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] | 13014 | |
Cyril Bonté | 108cf6e | 2012-04-21 23:30:29 +0200 | [diff] [blame] | 13015 | Example: |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 13016 | |
Julien Vehent | f21be32 | 2014-03-07 08:27:34 -0500 | [diff] [blame] | 13017 | unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 13018 | unique-id-header X-Unique-ID |
| 13019 | |
| 13020 | will generate: |
| 13021 | |
| 13022 | X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A |
| 13023 | |
| 13024 | See also: "unique-id-format" |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 13025 | |
Willy Tarreau | f51658d | 2014-04-23 01:21:56 +0200 | [diff] [blame] | 13026 | use_backend <backend> [{if | unless} <condition>] |
Willy Tarreau | 1d0dfb1 | 2009-07-07 15:10:31 +0200 | [diff] [blame] | 13027 | 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] | 13028 | May be used in sections : defaults | frontend | listen | backend |
| 13029 | no | yes | yes | no |
| 13030 | Arguments : |
Bertrand Jacquin | 702d44f | 2013-11-19 11:43:06 +0100 | [diff] [blame] | 13031 | <backend> is the name of a valid backend or "listen" section, or a |
| 13032 | "log-format" string resolving to a backend name. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 13033 | |
Willy Tarreau | f51658d | 2014-04-23 01:21:56 +0200 | [diff] [blame] | 13034 | <condition> is a condition composed of ACLs, as described in section 7. If |
| 13035 | it is omitted, the rule is unconditionally applied. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 13036 | |
| 13037 | When doing content-switching, connections arrive on a frontend and are then |
| 13038 | dispatched to various backends depending on a number of conditions. The |
| 13039 | relation between the conditions and the backends is described with the |
Willy Tarreau | 1d0dfb1 | 2009-07-07 15:10:31 +0200 | [diff] [blame] | 13040 | "use_backend" keyword. While it is normally used with HTTP processing, it can |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13041 | also be used in pure TCP, either without content using stateless ACLs (e.g. |
Willy Tarreau | 1d0dfb1 | 2009-07-07 15:10:31 +0200 | [diff] [blame] | 13042 | source address validation) or combined with a "tcp-request" rule to wait for |
| 13043 | some payload. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 13044 | |
| 13045 | There may be as many "use_backend" rules as desired. All of these rules are |
| 13046 | evaluated in their declaration order, and the first one which matches will |
| 13047 | assign the backend. |
| 13048 | |
| 13049 | In the first form, the backend will be used if the condition is met. In the |
| 13050 | second form, the backend will be used if the condition is not met. If no |
| 13051 | condition is valid, the backend defined with "default_backend" will be used. |
| 13052 | If no default backend is defined, either the servers in the same section are |
| 13053 | used (in case of a "listen" section) or, in case of a frontend, no server is |
| 13054 | used and a 503 service unavailable response is returned. |
| 13055 | |
Willy Tarreau | 51aecc7 | 2009-07-12 09:47:04 +0200 | [diff] [blame] | 13056 | 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] | 13057 | 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] | 13058 | and backend processing will immediately follow, or the backend will wait for |
| 13059 | a complete HTTP request to get in. This feature is useful when a frontend |
| 13060 | must decode several protocols on a unique port, one of them being HTTP. |
| 13061 | |
Bertrand Jacquin | 702d44f | 2013-11-19 11:43:06 +0100 | [diff] [blame] | 13062 | When <backend> is a simple name, it is resolved at configuration time, and an |
| 13063 | error is reported if the specified backend does not exist. If <backend> is |
| 13064 | a log-format string instead, no check may be done at configuration time, so |
| 13065 | the backend name is resolved dynamically at run time. If the resulting |
| 13066 | backend name does not correspond to any valid backend, no other rule is |
| 13067 | evaluated, and the default_backend directive is applied instead. Note that |
| 13068 | when using dynamic backend names, it is highly recommended to use a prefix |
| 13069 | that no other backend uses in order to ensure that an unauthorized backend |
| 13070 | cannot be forced from the request. |
| 13071 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 13072 | 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] | 13073 | used to detect the association between frontends and backends to compute the |
| 13074 | backend's "fullconn" setting. This cannot be done for dynamic names. |
| 13075 | |
| 13076 | See also: "default_backend", "tcp-request", "fullconn", "log-format", and |
| 13077 | section 7 about ACLs. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 13078 | |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 13079 | use-fcgi-app <name> |
| 13080 | Defines the FastCGI application to use for the backend. |
| 13081 | May be used in sections : defaults | frontend | listen | backend |
| 13082 | no | no | yes | yes |
| 13083 | Arguments : |
| 13084 | <name> is the name of the FastCGI application to use. |
| 13085 | |
| 13086 | See section 10.1 about FastCGI application setup for details. |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 13087 | |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 13088 | use-server <server> if <condition> |
| 13089 | use-server <server> unless <condition> |
| 13090 | Only use a specific server if/unless an ACL-based condition is matched. |
| 13091 | May be used in sections : defaults | frontend | listen | backend |
| 13092 | no | no | yes | yes |
| 13093 | Arguments : |
Jerome Magnin | 824186b | 2020-03-29 09:37:12 +0200 | [diff] [blame] | 13094 | <server> is the name of a valid server in the same backend section |
| 13095 | or a "log-format" string resolving to a server name. |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 13096 | |
| 13097 | <condition> is a condition composed of ACLs, as described in section 7. |
| 13098 | |
| 13099 | By default, connections which arrive to a backend are load-balanced across |
| 13100 | the available servers according to the configured algorithm, unless a |
| 13101 | persistence mechanism such as a cookie is used and found in the request. |
| 13102 | |
| 13103 | Sometimes it is desirable to forward a particular request to a specific |
| 13104 | server without having to declare a dedicated backend for this server. This |
| 13105 | can be achieved using the "use-server" rules. These rules are evaluated after |
| 13106 | the "redirect" rules and before evaluating cookies, and they have precedence |
| 13107 | on them. There may be as many "use-server" rules as desired. All of these |
| 13108 | rules are evaluated in their declaration order, and the first one which |
| 13109 | matches will assign the server. |
| 13110 | |
| 13111 | If a rule designates a server which is down, and "option persist" is not used |
| 13112 | and no force-persist rule was validated, it is ignored and evaluation goes on |
| 13113 | with the next rules until one matches. |
| 13114 | |
| 13115 | In the first form, the server will be used if the condition is met. In the |
| 13116 | second form, the server will be used if the condition is not met. If no |
| 13117 | condition is valid, the processing continues and the server will be assigned |
| 13118 | according to other persistence mechanisms. |
| 13119 | |
| 13120 | Note that even if a rule is matched, cookie processing is still performed but |
| 13121 | does not assign the server. This allows prefixed cookies to have their prefix |
| 13122 | stripped. |
| 13123 | |
| 13124 | The "use-server" statement works both in HTTP and TCP mode. This makes it |
| 13125 | suitable for use with content-based inspection. For instance, a server could |
Lukas Tribus | a267b5d | 2020-07-19 00:25:06 +0200 | [diff] [blame] | 13126 | be selected in a farm according to the TLS SNI field when using protocols with |
| 13127 | implicit TLS (also see "req_ssl_sni"). And if these servers have their weight |
| 13128 | set to zero, they will not be used for other traffic. |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 13129 | |
| 13130 | Example : |
| 13131 | # intercept incoming TLS requests based on the SNI field |
| 13132 | use-server www if { req_ssl_sni -i www.example.com } |
| 13133 | server www 192.168.0.1:443 weight 0 |
| 13134 | use-server mail if { req_ssl_sni -i mail.example.com } |
Lukas Tribus | a267b5d | 2020-07-19 00:25:06 +0200 | [diff] [blame] | 13135 | server mail 192.168.0.1:465 weight 0 |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 13136 | use-server imap if { req_ssl_sni -i imap.example.com } |
Lukas Tribus | 98a3e3f | 2017-03-26 12:55:35 +0000 | [diff] [blame] | 13137 | server imap 192.168.0.1:993 weight 0 |
Willy Tarreau | 4a5cade | 2012-04-05 21:09:48 +0200 | [diff] [blame] | 13138 | # all the rest is forwarded to this server |
| 13139 | server default 192.168.0.2:443 check |
| 13140 | |
Jerome Magnin | 824186b | 2020-03-29 09:37:12 +0200 | [diff] [blame] | 13141 | When <server> is a simple name, it is checked against existing servers in the |
| 13142 | configuration and an error is reported if the specified server does not exist. |
| 13143 | If it is a log-format, no check is performed when parsing the configuration, |
| 13144 | and if we can't resolve a valid server name at runtime but the use-server rule |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 13145 | was conditioned by an ACL returning true, no other use-server rule is applied |
Jerome Magnin | 824186b | 2020-03-29 09:37:12 +0200 | [diff] [blame] | 13146 | and we fall back to load balancing. |
| 13147 | |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 13148 | 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] | 13149 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13150 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13151 | 5. Bind and server options |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13152 | -------------------------- |
| 13153 | |
| 13154 | The "bind", "server" and "default-server" keywords support a number of settings |
| 13155 | depending on some build options and on the system HAProxy was built on. These |
| 13156 | settings generally each consist in one word sometimes followed by a value, |
| 13157 | written on the same line as the "bind" or "server" line. All these options are |
| 13158 | described in this section. |
| 13159 | |
| 13160 | |
| 13161 | 5.1. Bind options |
| 13162 | ----------------- |
| 13163 | |
| 13164 | The "bind" keyword supports a certain number of settings which are all passed |
| 13165 | as arguments on the same line. The order in which those arguments appear makes |
| 13166 | no importance, provided that they appear after the bind address. All of these |
| 13167 | parameters are optional. Some of them consist in a single words (booleans), |
| 13168 | while other ones expect a value after them. In this case, the value must be |
| 13169 | provided immediately after the setting name. |
| 13170 | |
| 13171 | The currently supported settings are the following ones. |
| 13172 | |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 13173 | accept-netscaler-cip <magic number> |
| 13174 | Enforces the use of the NetScaler Client IP insertion protocol over any |
| 13175 | connection accepted by any of the TCP sockets declared on the same line. The |
| 13176 | NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of |
| 13177 | the incoming connection to be used everywhere an address is used, with the |
| 13178 | only exception of "tcp-request connection" rules which will only see the |
| 13179 | real connection address. Logs will reflect the addresses indicated in the |
| 13180 | protocol, unless it is violated, in which case the real address will still |
| 13181 | be used. This keyword combined with support from external components can be |
| 13182 | used as an efficient and reliable alternative to the X-Forwarded-For |
Bertrand Jacquin | 9075968 | 2016-06-06 15:35:39 +0100 | [diff] [blame] | 13183 | mechanism which is not always reliable and not even always usable. See also |
| 13184 | "tcp-request connection expect-netscaler-cip" for a finer-grained setting of |
| 13185 | which client is allowed to use the protocol. |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 13186 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13187 | accept-proxy |
| 13188 | Enforces the use of the PROXY protocol over any connection accepted by any of |
Willy Tarreau | 7799267 | 2014-06-14 11:06:17 +0200 | [diff] [blame] | 13189 | the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol |
| 13190 | are supported and correctly detected. The PROXY protocol dictates the layer |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13191 | 3/4 addresses of the incoming connection to be used everywhere an address is |
| 13192 | used, with the only exception of "tcp-request connection" rules which will |
| 13193 | only see the real connection address. Logs will reflect the addresses |
| 13194 | indicated in the protocol, unless it is violated, in which case the real |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13195 | address will still be used. This keyword combined with support from external |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13196 | components can be used as an efficient and reliable alternative to the |
| 13197 | 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] | 13198 | usable. See also "tcp-request connection expect-proxy" for a finer-grained |
| 13199 | setting of which client is allowed to use the protocol. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13200 | |
Olivier Houchard | c2aae74 | 2017-09-22 18:26:28 +0200 | [diff] [blame] | 13201 | allow-0rtt |
Bertrand Jacquin | a25282b | 2018-08-14 00:56:13 +0100 | [diff] [blame] | 13202 | Allow receiving early data when using TLSv1.3. This is disabled by default, |
Olivier Houchard | 6975296 | 2019-01-08 15:35:32 +0100 | [diff] [blame] | 13203 | due to security considerations. Because it is vulnerable to replay attacks, |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 13204 | you should only allow if for requests that are safe to replay, i.e. requests |
Olivier Houchard | 6975296 | 2019-01-08 15:35:32 +0100 | [diff] [blame] | 13205 | that are idempotent. You can use the "wait-for-handshake" action for any |
| 13206 | request that wouldn't be safe with early data. |
Olivier Houchard | c2aae74 | 2017-09-22 18:26:28 +0200 | [diff] [blame] | 13207 | |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 13208 | alpn <protocols> |
| 13209 | This enables the TLS ALPN extension and advertises the specified protocol |
| 13210 | list as supported on top of ALPN. The protocol list consists in a comma- |
| 13211 | delimited list of protocol names, for instance: "http/1.1,http/1.0" (without |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 13212 | quotes). This requires that the SSL library is built with support for TLS |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 13213 | extensions enabled (check with haproxy -vv). The ALPN extension replaces the |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 13214 | initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend. |
| 13215 | Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the |
| 13216 | now obsolete NPN extension. At the time of writing this, most browsers still |
| 13217 | support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for |
| 13218 | a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1 |
| 13219 | are expected to be supported, both versions can be advertised, in order of |
| 13220 | preference, like below : |
| 13221 | |
| 13222 | bind :443 ssl crt pub.pem alpn h2,http/1.1 |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 13223 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13224 | backlog <backlog> |
Willy Tarreau | e2711c7 | 2019-02-27 15:39:41 +0100 | [diff] [blame] | 13225 | Sets the socket's backlog to this value. If unspecified or 0, the frontend's |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13226 | backlog is used instead, which generally defaults to the maxconn value. |
| 13227 | |
Emmanuel Hocdet | e7f2b73 | 2017-01-09 16:15:54 +0100 | [diff] [blame] | 13228 | curves <curves> |
| 13229 | This setting is only available when support for OpenSSL was built in. It sets |
| 13230 | the string describing the list of elliptic curves algorithms ("curve suite") |
| 13231 | that are negotiated during the SSL/TLS handshake with ECDHE. The format of the |
| 13232 | string is a colon-delimited list of curve name. |
| 13233 | Example: "X25519:P-256" (without quote) |
| 13234 | When "curves" is set, "ecdhe" parameter is ignored. |
| 13235 | |
Emeric Brun | 7fb3442 | 2012-09-28 15:26:15 +0200 | [diff] [blame] | 13236 | ecdhe <named curve> |
| 13237 | 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] | 13238 | the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default, |
| 13239 | used named curve is prime256v1. |
Emeric Brun | 7fb3442 | 2012-09-28 15:26:15 +0200 | [diff] [blame] | 13240 | |
Emeric Brun | fd33a26 | 2012-10-11 16:28:27 +0200 | [diff] [blame] | 13241 | ca-file <cafile> |
Emeric Brun | 1a073b4 | 2012-09-28 17:07:34 +0200 | [diff] [blame] | 13242 | This setting is only available when support for OpenSSL was built in. It |
| 13243 | designates a PEM file from which to load CA certificates used to verify |
| 13244 | client's certificate. |
| 13245 | |
Emeric Brun | b6dc934 | 2012-09-28 17:55:37 +0200 | [diff] [blame] | 13246 | ca-ignore-err [all|<errorID>,...] |
| 13247 | This setting is only available when support for OpenSSL was built in. |
| 13248 | Sets a comma separated list of errorIDs to ignore during verify at depth > 0. |
| 13249 | If set to 'all', all errors are ignored. SSL handshake is not aborted if an |
| 13250 | error is ignored. |
| 13251 | |
Christopher Faulet | 31af49d | 2015-06-09 17:29:50 +0200 | [diff] [blame] | 13252 | ca-sign-file <cafile> |
| 13253 | This setting is only available when support for OpenSSL was built in. It |
| 13254 | designates a PEM file containing both the CA certificate and the CA private |
| 13255 | key used to create and sign server's certificates. This is a mandatory |
| 13256 | setting when the dynamic generation of certificates is enabled. See |
| 13257 | 'generate-certificates' for details. |
| 13258 | |
Bertrand Jacquin | d4d0a23 | 2016-11-13 16:37:12 +0000 | [diff] [blame] | 13259 | ca-sign-pass <passphrase> |
Christopher Faulet | 31af49d | 2015-06-09 17:29:50 +0200 | [diff] [blame] | 13260 | This setting is only available when support for OpenSSL was built in. It is |
| 13261 | the CA private key passphrase. This setting is optional and used only when |
| 13262 | the dynamic generation of certificates is enabled. See |
| 13263 | 'generate-certificates' for details. |
| 13264 | |
Emmanuel Hocdet | 842e94e | 2019-12-16 16:39:17 +0100 | [diff] [blame] | 13265 | ca-verify-file <cafile> |
| 13266 | This setting designates a PEM file from which to load CA certificates used to |
| 13267 | verify client's certificate. It designates CA certificates which must not be |
| 13268 | included in CA names sent in server hello message. Typically, "ca-file" must |
| 13269 | be defined with intermediate certificates, and "ca-verify-file" with |
| 13270 | certificates to ending the chain, like root CA. |
| 13271 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13272 | ciphers <ciphers> |
| 13273 | This setting is only available when support for OpenSSL was built in. It sets |
| 13274 | the string describing the list of cipher algorithms ("cipher suite") that are |
Bertrand Jacquin | 8cf7c1e | 2019-02-03 18:35:25 +0000 | [diff] [blame] | 13275 | negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 13276 | string is defined in "man 1 ciphers" from OpenSSL man pages. For background |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 13277 | information and recommendations see e.g. |
| 13278 | (https://wiki.mozilla.org/Security/Server_Side_TLS) and |
| 13279 | (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3 |
| 13280 | cipher configuration, please check the "ciphersuites" keyword. |
| 13281 | |
| 13282 | ciphersuites <ciphersuites> |
| 13283 | This setting is only available when support for OpenSSL was built in and |
| 13284 | OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing |
| 13285 | the list of cipher algorithms ("cipher suite") that are negotiated during the |
| 13286 | TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 13287 | OpenSSL man pages under the "ciphersuites" section. For cipher configuration |
| 13288 | for TLSv1.2 and earlier, please check the "ciphers" keyword. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13289 | |
Emeric Brun | fd33a26 | 2012-10-11 16:28:27 +0200 | [diff] [blame] | 13290 | crl-file <crlfile> |
Emeric Brun | 1a073b4 | 2012-09-28 17:07:34 +0200 | [diff] [blame] | 13291 | This setting is only available when support for OpenSSL was built in. It |
| 13292 | designates a PEM file from which to load certificate revocation list used |
| 13293 | to verify client's certificate. |
| 13294 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13295 | crt <cert> |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13296 | This setting is only available when support for OpenSSL was built in. It |
| 13297 | designates a PEM file containing both the required certificates and any |
| 13298 | associated private keys. This file can be built by concatenating multiple |
| 13299 | PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA |
| 13300 | requires an intermediate certificate, this can also be concatenated into this |
Emmanuel Hocdet | 70df7bf | 2019-01-04 11:08:20 +0100 | [diff] [blame] | 13301 | file. Intermediate certificate can also be shared in a directory via |
| 13302 | "issuers-chain-path" directive. |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13303 | |
William Lallemand | 4c5adbf | 2020-02-24 14:23:22 +0100 | [diff] [blame] | 13304 | If the file does not contain a private key, HAProxy will try to load |
| 13305 | the key at the same path suffixed by a ".key". |
| 13306 | |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13307 | If the OpenSSL used supports Diffie-Hellman, parameters present in this file |
| 13308 | are loaded. |
| 13309 | |
| 13310 | If a directory name is used instead of a PEM file, then all files found in |
William Lallemand | 3f25ae3 | 2020-02-24 16:30:12 +0100 | [diff] [blame] | 13311 | that directory will be loaded in alphabetic order unless their name ends |
| 13312 | with '.key', '.issuer', '.ocsp' or '.sctl' (reserved extensions). This |
| 13313 | directive may be specified multiple times in order to load certificates from |
| 13314 | multiple files or directories. The certificates will be presented to clients |
| 13315 | who provide a valid TLS Server Name Indication field matching one of their |
| 13316 | CN or alt subjects. Wildcards are supported, where a wildcard character '*' |
| 13317 | is used instead of the first hostname component (e.g. *.example.org matches |
Janusz Dziemidowicz | 2c701b5 | 2015-03-07 23:03:59 +0100 | [diff] [blame] | 13318 | www.example.org but not www.sub.example.org). |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13319 | |
| 13320 | If no SNI is provided by the client or if the SSL library does not support |
| 13321 | TLS extensions, or if the client provides an SNI hostname which does not |
| 13322 | match any certificate, then the first loaded certificate will be presented. |
| 13323 | This means that when loading certificates from a directory, it is highly |
Cyril Bonté | 3180f7b | 2015-01-25 00:16:08 +0100 | [diff] [blame] | 13324 | recommended to load the default one first as a file or to ensure that it will |
| 13325 | always be the first one in the directory. |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13326 | |
Emeric Brun | e032bfa | 2012-09-28 13:01:45 +0200 | [diff] [blame] | 13327 | 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] | 13328 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13329 | Some CAs (such as GoDaddy) offer a drop down list of server types that do not |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13330 | include HAProxy when obtaining a certificate. If this happens be sure to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13331 | choose a web server that the CA believes requires an intermediate CA (for |
| 13332 | GoDaddy, selection Apache Tomcat will get the correct bundle, but many |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13333 | others, e.g. nginx, result in a wrong bundle that will not work for some |
| 13334 | clients). |
| 13335 | |
Emeric Brun | 4147b2e | 2014-06-16 18:36:30 +0200 | [diff] [blame] | 13336 | For each PEM file, haproxy checks for the presence of file at the same path |
| 13337 | suffixed by ".ocsp". If such file is found, support for the TLS Certificate |
| 13338 | Status Request extension (also known as "OCSP stapling") is automatically |
| 13339 | enabled. The content of this file is optional. If not empty, it must contain |
| 13340 | a valid OCSP Response in DER format. In order to be valid an OCSP Response |
| 13341 | must comply with the following rules: it has to indicate a good status, |
| 13342 | it has to be a single response for the certificate of the PEM file, and it |
| 13343 | has to be valid at the moment of addition. If these rules are not respected |
| 13344 | the OCSP Response is ignored and a warning is emitted. In order to identify |
| 13345 | which certificate an OCSP Response applies to, the issuer's certificate is |
| 13346 | necessary. If the issuer's certificate is not found in the PEM file, it will |
| 13347 | be loaded from a file at the same path as the PEM file suffixed by ".issuer" |
| 13348 | if it exists otherwise it will fail with an error. |
| 13349 | |
Janusz Dziemidowicz | 2c701b5 | 2015-03-07 23:03:59 +0100 | [diff] [blame] | 13350 | For each PEM file, haproxy also checks for the presence of file at the same |
| 13351 | path suffixed by ".sctl". If such file is found, support for Certificate |
| 13352 | Transparency (RFC6962) TLS extension is enabled. The file must contain a |
| 13353 | valid Signed Certificate Timestamp List, as described in RFC. File is parsed |
| 13354 | to check basic syntax, but no signatures are verified. |
| 13355 | |
yanbzhu | 6c25e9e | 2016-01-05 12:52:02 -0500 | [diff] [blame] | 13356 | There are cases where it is desirable to support multiple key types, e.g. RSA |
| 13357 | and ECDSA in the cipher suites offered to the clients. This allows clients |
| 13358 | that support EC certificates to be able to use EC ciphers, while |
| 13359 | simultaneously supporting older, RSA only clients. |
yanbzhu | d19630c | 2015-12-14 15:10:25 -0500 | [diff] [blame] | 13360 | |
William Lallemand | f9ff3ec | 2020-10-02 17:57:44 +0200 | [diff] [blame] | 13361 | To achieve this, OpenSSL 1.1.1 is required, you can configure this behavior |
| 13362 | by providing one crt entry per certificate type, or by configuring a "cert |
| 13363 | bundle" like it was required before HAProxy 1.8. See "ssl-load-extra-files". |
yanbzhu | d19630c | 2015-12-14 15:10:25 -0500 | [diff] [blame] | 13364 | |
Emeric Brun | b6dc934 | 2012-09-28 17:55:37 +0200 | [diff] [blame] | 13365 | crt-ignore-err <errors> |
Alex Davies | 0fbf016 | 2013-03-02 16:04:50 +0000 | [diff] [blame] | 13366 | This setting is only available when support for OpenSSL was built in. Sets a |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13367 | 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] | 13368 | 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] | 13369 | is ignored. |
Emeric Brun | b6dc934 | 2012-09-28 17:55:37 +0200 | [diff] [blame] | 13370 | |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 13371 | crt-list <file> |
| 13372 | This setting is only available when support for OpenSSL was built in. It |
Emmanuel Hocdet | 9826329 | 2016-12-29 18:26:15 +0100 | [diff] [blame] | 13373 | designates a list of PEM file with an optional ssl configuration and a SNI |
| 13374 | filter per certificate, with the following format for each line : |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 13375 | |
Emmanuel Hocdet | 9826329 | 2016-12-29 18:26:15 +0100 | [diff] [blame] | 13376 | <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...] |
| 13377 | |
William Lallemand | 5d03639 | 2020-06-30 16:11:36 +0200 | [diff] [blame] | 13378 | sslbindconf supports "allow-0rtt", "alpn", "ca-file", "ca-verify-file", |
| 13379 | "ciphers", "ciphersuites", "crl-file", "curves", "ecdhe", "no-ca-names", |
| 13380 | "npn", "verify" configuration. With BoringSSL and Openssl >= 1.1.1 |
| 13381 | "ssl-min-ver" and "ssl-max-ver" are also supported. It overrides the |
| 13382 | configuration set in bind line for the certificate. |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 13383 | |
Emmanuel Hocdet | 7c41a1b | 2013-05-07 20:20:06 +0200 | [diff] [blame] | 13384 | Wildcards are supported in the SNI filter. Negative filter are also supported, |
Joao Morais | e51fab0 | 2020-11-21 07:42:20 -0300 | [diff] [blame] | 13385 | useful in combination with a wildcard filter to exclude a particular SNI, or |
| 13386 | after the first certificate to exclude a pattern from its CN or Subject Alt |
| 13387 | Name (SAN). The certificates will be presented to clients who provide a valid |
| 13388 | TLS Server Name Indication field matching one of the SNI filters. If no SNI |
| 13389 | filter is specified, the CN and SAN are used. This directive may be specified |
Emmanuel Hocdet | 7c41a1b | 2013-05-07 20:20:06 +0200 | [diff] [blame] | 13390 | multiple times. See the "crt" option for more information. The default |
| 13391 | certificate is still needed to meet OpenSSL expectations. If it is not used, |
| 13392 | the 'strict-sni' option may be used. |
Emmanuel Hocdet | fe61656 | 2013-01-22 15:31:15 +0100 | [diff] [blame] | 13393 | |
William Lallemand | f9ff3ec | 2020-10-02 17:57:44 +0200 | [diff] [blame] | 13394 | Multi-cert bundling (see "ssl-load-extra-files") is supported with crt-list, |
| 13395 | as long as only the base name is given in the crt-list. SNI filter will do |
| 13396 | the same work on all bundled certificates. |
yanbzhu | d19630c | 2015-12-14 15:10:25 -0500 | [diff] [blame] | 13397 | |
William Lallemand | 7c26ed7 | 2020-06-03 17:34:48 +0200 | [diff] [blame] | 13398 | Empty lines as well as lines beginning with a hash ('#') will be ignored. |
| 13399 | |
Joao Morais | aa8fcc4 | 2020-11-24 08:24:30 -0300 | [diff] [blame] | 13400 | The first declared certificate of a bind line is used as the default |
| 13401 | certificate, either from crt or crt-list option, which haproxy should use in |
| 13402 | the TLS handshake if no other certificate matches. This certificate will also |
| 13403 | be used if the provided SNI matches its CN or SAN, even if a matching SNI |
| 13404 | filter is found on any crt-list. The SNI filter !* can be used after the first |
| 13405 | declared certificate to not include its CN and SAN in the SNI tree, so it will |
| 13406 | never match except if no other certificate matches. This way the first |
| 13407 | declared certificate act as a fallback. |
Joao Morais | e51fab0 | 2020-11-21 07:42:20 -0300 | [diff] [blame] | 13408 | |
Emmanuel Hocdet | 9826329 | 2016-12-29 18:26:15 +0100 | [diff] [blame] | 13409 | crt-list file example: |
Joao Morais | e51fab0 | 2020-11-21 07:42:20 -0300 | [diff] [blame] | 13410 | cert1.pem !* |
William Lallemand | 7c26ed7 | 2020-06-03 17:34:48 +0200 | [diff] [blame] | 13411 | # comment |
Emmanuel Hocdet | 0594211 | 2017-02-20 16:11:50 +0100 | [diff] [blame] | 13412 | cert2.pem [alpn h2,http/1.1] |
Emmanuel Hocdet | 9826329 | 2016-12-29 18:26:15 +0100 | [diff] [blame] | 13413 | certW.pem *.domain.tld !secure.domain.tld |
Emmanuel Hocdet | 0594211 | 2017-02-20 16:11:50 +0100 | [diff] [blame] | 13414 | certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld |
Emmanuel Hocdet | 9826329 | 2016-12-29 18:26:15 +0100 | [diff] [blame] | 13415 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13416 | defer-accept |
| 13417 | Is an optional keyword which is supported only on certain Linux kernels. It |
| 13418 | states that a connection will only be accepted once some data arrive on it, |
| 13419 | or at worst after the first retransmit. This should be used only on protocols |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13420 | for which the client talks first (e.g. HTTP). It can slightly improve |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13421 | performance by ensuring that most of the request is already available when |
| 13422 | the connection is accepted. On the other hand, it will not be able to detect |
| 13423 | connections which don't talk. It is important to note that this option is |
| 13424 | broken in all kernels up to 2.6.31, as the connection is never accepted until |
| 13425 | the client talks. This can cause issues with front firewalls which would see |
| 13426 | an established connection while the proxy will only see it in SYN_RECV. This |
| 13427 | option is only supported on TCPv4/TCPv6 sockets and ignored by other ones. |
| 13428 | |
William Lallemand | f6975e9 | 2017-05-26 17:42:10 +0200 | [diff] [blame] | 13429 | expose-fd listeners |
| 13430 | This option is only usable with the stats socket. It gives your stats socket |
| 13431 | the capability to pass listeners FD to another HAProxy process. |
William Lallemand | e202b1e | 2017-06-01 17:38:56 +0200 | [diff] [blame] | 13432 | During a reload with the master-worker mode, the process is automatically |
| 13433 | reexecuted adding -x and one of the stats socket with this option. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13434 | See also "-x" in the management guide. |
William Lallemand | f6975e9 | 2017-05-26 17:42:10 +0200 | [diff] [blame] | 13435 | |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13436 | force-sslv3 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 13437 | This option enforces use of SSLv3 only on SSL connections instantiated from |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13438 | this listener. SSLv3 is generally less expensive than the TLS counterparts |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13439 | for high connection rates. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13440 | "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver". |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13441 | |
| 13442 | force-tlsv10 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 13443 | This option enforces use of TLSv1.0 only on SSL connections instantiated from |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13444 | this listener. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13445 | "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver". |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13446 | |
| 13447 | force-tlsv11 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 13448 | This option enforces use of TLSv1.1 only on SSL connections instantiated from |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13449 | this listener. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13450 | "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver". |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13451 | |
| 13452 | force-tlsv12 |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 13453 | This option enforces use of TLSv1.2 only on SSL connections instantiated from |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13454 | this listener. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13455 | "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver". |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13456 | |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 13457 | force-tlsv13 |
| 13458 | This option enforces use of TLSv1.3 only on SSL connections instantiated from |
| 13459 | this listener. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13460 | "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver". |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 13461 | |
Christopher Faulet | 31af49d | 2015-06-09 17:29:50 +0200 | [diff] [blame] | 13462 | generate-certificates |
| 13463 | This setting is only available when support for OpenSSL was built in. It |
| 13464 | enables the dynamic SSL certificates generation. A CA certificate and its |
| 13465 | private key are necessary (see 'ca-sign-file'). When HAProxy is configured as |
| 13466 | a transparent forward proxy, SSL requests generate errors because of a common |
| 13467 | name mismatch on the certificate presented to the client. With this option |
| 13468 | enabled, HAProxy will try to forge a certificate using the SNI hostname |
| 13469 | indicated by the client. This is done only if no certificate matches the SNI |
| 13470 | hostname (see 'crt-list'). If an error occurs, the default certificate is |
| 13471 | used, else the 'strict-sni' option is set. |
| 13472 | It can also be used when HAProxy is configured as a reverse proxy to ease the |
| 13473 | deployment of an architecture with many backends. |
| 13474 | |
| 13475 | Creating a SSL certificate is an expensive operation, so a LRU cache is used |
| 13476 | to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13477 | increases the HAProxy's memory footprint to reduce latency when the same |
Christopher Faulet | 31af49d | 2015-06-09 17:29:50 +0200 | [diff] [blame] | 13478 | certificate is used many times. |
| 13479 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13480 | gid <gid> |
| 13481 | Sets the group of the UNIX sockets to the designated system gid. It can also |
| 13482 | be set by default in the global section's "unix-bind" statement. Note that |
| 13483 | some platforms simply ignore this. This setting is equivalent to the "group" |
| 13484 | setting except that the group ID is used instead of its name. This setting is |
| 13485 | ignored by non UNIX sockets. |
| 13486 | |
| 13487 | group <group> |
| 13488 | Sets the group of the UNIX sockets to the designated system group. It can |
| 13489 | also be set by default in the global section's "unix-bind" statement. Note |
| 13490 | that some platforms simply ignore this. This setting is equivalent to the |
| 13491 | "gid" setting except that the group name is used instead of its gid. This |
| 13492 | setting is ignored by non UNIX sockets. |
| 13493 | |
| 13494 | id <id> |
| 13495 | Fixes the socket ID. By default, socket IDs are automatically assigned, but |
| 13496 | sometimes it is more convenient to fix them to ease monitoring. This value |
| 13497 | must be strictly positive and unique within the listener/frontend. This |
| 13498 | option can only be used when defining only a single socket. |
| 13499 | |
| 13500 | interface <interface> |
Lukas Tribus | fce2e96 | 2013-02-12 22:13:19 +0100 | [diff] [blame] | 13501 | Restricts the socket to a specific interface. When specified, only packets |
| 13502 | received from that particular interface are processed by the socket. This is |
| 13503 | currently only supported on Linux. The interface must be a primary system |
| 13504 | interface, not an aliased interface. It is also possible to bind multiple |
| 13505 | frontends to the same address if they are bound to different interfaces. Note |
| 13506 | that binding to a network interface requires root privileges. This parameter |
Jérôme Magnin | 6127519 | 2018-02-07 11:39:58 +0100 | [diff] [blame] | 13507 | is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic |
| 13508 | uses the same interface as inbound traffic, and its associated routing table, |
| 13509 | even if there are explicit routes through different interfaces configured. |
| 13510 | This can prove useful to address asymmetric routing issues when the same |
| 13511 | client IP addresses need to be able to reach frontends hosted on different |
| 13512 | interfaces. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13513 | |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 13514 | level <level> |
| 13515 | This setting is used with the stats sockets only to restrict the nature of |
| 13516 | the commands that can be issued on the socket. It is ignored by other |
| 13517 | sockets. <level> can be one of : |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13518 | - "user" is the least privileged level; only non-sensitive stats can be |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 13519 | read, and no change is allowed. It would make sense on systems where it |
| 13520 | is not easy to restrict access to the socket. |
| 13521 | - "operator" is the default level and fits most common uses. All data can |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13522 | be read, and only non-sensitive changes are permitted (e.g. clear max |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 13523 | counters). |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13524 | - "admin" should be used with care, as everything is permitted (e.g. clear |
Willy Tarreau | abb175f | 2012-09-24 12:43:26 +0200 | [diff] [blame] | 13525 | all counters). |
| 13526 | |
Andjelko Iharos | c4df59e | 2017-07-20 11:59:48 +0200 | [diff] [blame] | 13527 | severity-output <format> |
| 13528 | This setting is used with the stats sockets only to configure severity |
| 13529 | level output prepended to informational feedback messages. Severity |
| 13530 | level of messages can range between 0 and 7, conforming to syslog |
| 13531 | rfc5424. Valid and successful socket commands requesting data |
| 13532 | (i.e. "show map", "get acl foo" etc.) will never have a severity level |
| 13533 | prepended. It is ignored by other sockets. <format> can be one of : |
| 13534 | - "none" (default) no severity level is prepended to feedback messages. |
| 13535 | - "number" severity level is prepended as a number. |
| 13536 | - "string" severity level is prepended as a string following the |
| 13537 | rfc5424 convention. |
| 13538 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13539 | maxconn <maxconn> |
| 13540 | Limits the sockets to this number of concurrent connections. Extraneous |
| 13541 | connections will remain in the system's backlog until a connection is |
| 13542 | released. If unspecified, the limit will be the same as the frontend's |
| 13543 | maxconn. Note that in case of port ranges or multiple addresses, the same |
| 13544 | value will be applied to each socket. This setting enables different |
| 13545 | limitations on expensive sockets, for instance SSL entries which may easily |
| 13546 | eat all memory. |
| 13547 | |
| 13548 | mode <mode> |
| 13549 | Sets the octal mode used to define access permissions on the UNIX socket. It |
| 13550 | can also be set by default in the global section's "unix-bind" statement. |
| 13551 | Note that some platforms simply ignore this. This setting is ignored by non |
| 13552 | UNIX sockets. |
| 13553 | |
| 13554 | mss <maxseg> |
| 13555 | Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming |
| 13556 | connections. This can be used to force a lower MSS for certain specific |
| 13557 | ports, for instance for connections passing through a VPN. Note that this |
| 13558 | relies on a kernel feature which is theoretically supported under Linux but |
| 13559 | was buggy in all versions prior to 2.6.28. It may or may not work on other |
| 13560 | operating systems. It may also not change the advertised value but change the |
| 13561 | effective size of outgoing segments. The commonly advertised value for TCPv4 |
| 13562 | over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is |
| 13563 | positive, it will be used as the advertised MSS. If it is negative, it will |
| 13564 | indicate by how much to reduce the incoming connection's advertised MSS for |
| 13565 | outgoing segments. This parameter is only compatible with TCP v4/v6 sockets. |
| 13566 | |
| 13567 | name <name> |
| 13568 | Sets an optional name for these sockets, which will be reported on the stats |
| 13569 | page. |
| 13570 | |
Willy Tarreau | d72f0f3 | 2015-10-13 14:50:22 +0200 | [diff] [blame] | 13571 | namespace <name> |
| 13572 | On Linux, it is possible to specify which network namespace a socket will |
| 13573 | belong to. This directive makes it possible to explicitly bind a listener to |
| 13574 | a namespace different from the default one. Please refer to your operating |
| 13575 | system's documentation to find more details about network namespaces. |
| 13576 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13577 | nice <nice> |
| 13578 | Sets the 'niceness' of connections initiated from the socket. Value must be |
| 13579 | in the range -1024..1024 inclusive, and defaults to zero. Positive values |
| 13580 | means that such connections are more friendly to others and easily offer |
| 13581 | their place in the scheduler. On the opposite, negative values mean that |
| 13582 | connections want to run with a higher priority than others. The difference |
| 13583 | only happens under high loads when the system is close to saturation. |
| 13584 | Negative values are appropriate for low-latency or administration services, |
| 13585 | and high values are generally recommended for CPU intensive tasks such as SSL |
| 13586 | processing or bulk transfers which are less sensible to latency. For example, |
| 13587 | it may make sense to use a positive value for an SMTP socket and a negative |
| 13588 | one for an RDP socket. |
| 13589 | |
Emmanuel Hocdet | 174dfe5 | 2017-07-28 15:01:05 +0200 | [diff] [blame] | 13590 | no-ca-names |
| 13591 | This setting is only available when support for OpenSSL was built in. It |
| 13592 | prevents from send CA names in server hello message when ca-file is used. |
Emmanuel Hocdet | 842e94e | 2019-12-16 16:39:17 +0100 | [diff] [blame] | 13593 | Use "ca-verify-file" instead of "ca-file" with "no-ca-names". |
Emmanuel Hocdet | 174dfe5 | 2017-07-28 15:01:05 +0200 | [diff] [blame] | 13594 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 13595 | no-sslv3 |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13596 | 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] | 13597 | disables support for SSLv3 on any sockets instantiated from the listener when |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13598 | SSL is supported. Note that SSLv2 is forced disabled in the code and cannot |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13599 | be enabled using any configuration option. This option is also available on |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13600 | global statement "ssl-default-bind-options". Use "ssl-min-ver" and |
| 13601 | "ssl-max-ver" instead. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13602 | |
Emeric Brun | 90ad872 | 2012-10-02 14:00:59 +0200 | [diff] [blame] | 13603 | no-tls-tickets |
| 13604 | This setting is only available when support for OpenSSL was built in. It |
| 13605 | disables the stateless session resumption (RFC 5077 TLS Ticket |
| 13606 | extension) and force to use stateful session resumption. Stateless |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13607 | session resumption is more expensive in CPU usage. This option is also |
| 13608 | available on global statement "ssl-default-bind-options". |
Lukas Tribus | bdb386d | 2020-03-10 00:56:09 +0100 | [diff] [blame] | 13609 | The TLS ticket mechanism is only used up to TLS 1.2. |
| 13610 | Forward Secrecy is compromised with TLS tickets, unless ticket keys |
| 13611 | are periodically rotated (via reload or by using "tls-ticket-keys"). |
Emeric Brun | 90ad872 | 2012-10-02 14:00:59 +0200 | [diff] [blame] | 13612 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 13613 | no-tlsv10 |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13614 | 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] | 13615 | disables support for TLSv1.0 on any sockets instantiated from the listener |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13616 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13617 | cannot be enabled using any configuration option. This option is also |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13618 | available on global statement "ssl-default-bind-options". Use "ssl-min-ver" |
| 13619 | and "ssl-max-ver" instead. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13620 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 13621 | no-tlsv11 |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 13622 | 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] | 13623 | disables support for TLSv1.1 on any sockets instantiated from the listener |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13624 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13625 | cannot be enabled using any configuration option. This option is also |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13626 | available on global statement "ssl-default-bind-options". Use "ssl-min-ver" |
| 13627 | and "ssl-max-ver" instead. |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 13628 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 13629 | no-tlsv12 |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 13630 | 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] | 13631 | disables support for TLSv1.2 on any sockets instantiated from the listener |
Emeric Brun | 2cb7ae5 | 2012-10-05 14:14:21 +0200 | [diff] [blame] | 13632 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 13633 | cannot be enabled using any configuration option. This option is also |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13634 | available on global statement "ssl-default-bind-options". Use "ssl-min-ver" |
| 13635 | and "ssl-max-ver" instead. |
Emeric Brun | f5da493 | 2012-09-28 19:42:54 +0200 | [diff] [blame] | 13636 | |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 13637 | no-tlsv13 |
| 13638 | This setting is only available when support for OpenSSL was built in. It |
| 13639 | disables support for TLSv1.3 on any sockets instantiated from the listener |
| 13640 | when SSL is supported. Note that SSLv2 is forced disabled in the code and |
| 13641 | cannot be enabled using any configuration option. This option is also |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13642 | available on global statement "ssl-default-bind-options". Use "ssl-min-ver" |
| 13643 | and "ssl-max-ver" instead. |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 13644 | |
Willy Tarreau | 6c9a3d5 | 2012-10-18 18:57:14 +0200 | [diff] [blame] | 13645 | npn <protocols> |
| 13646 | This enables the NPN TLS extension and advertises the specified protocol list |
| 13647 | as supported on top of NPN. The protocol list consists in a comma-delimited |
| 13648 | list of protocol names, for instance: "http/1.1,http/1.0" (without quotes). |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 13649 | This requires that the SSL library is built with support for TLS extensions |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 13650 | enabled (check with haproxy -vv). Note that the NPN extension has been |
Willy Tarreau | 95c4e14 | 2017-11-26 12:18:55 +0100 | [diff] [blame] | 13651 | replaced with the ALPN extension (see the "alpn" keyword), though this one is |
| 13652 | only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older |
| 13653 | version of OpenSSL, NPN might still be used as most clients still support it |
| 13654 | at the time of writing this. It is possible to enable both NPN and ALPN |
| 13655 | though it probably doesn't make any sense out of testing. |
Willy Tarreau | 6c9a3d5 | 2012-10-18 18:57:14 +0200 | [diff] [blame] | 13656 | |
Lukas Tribus | 53ae85c | 2017-05-04 15:45:40 +0000 | [diff] [blame] | 13657 | prefer-client-ciphers |
| 13658 | Use the client's preference when selecting the cipher suite, by default |
| 13659 | the server's preference is enforced. This option is also available on |
| 13660 | global statement "ssl-default-bind-options". |
Lukas Tribus | 926594f | 2018-05-18 17:55:57 +0200 | [diff] [blame] | 13661 | Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway |
| 13662 | (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of |
| 13663 | the client cipher list. |
Lukas Tribus | 53ae85c | 2017-05-04 15:45:40 +0000 | [diff] [blame] | 13664 | |
Christopher Faulet | c644fa9 | 2017-11-23 22:44:11 +0100 | [diff] [blame] | 13665 | process <process-set>[/<thread-set>] |
Willy Tarreau | a36b324 | 2019-02-02 13:14:34 +0100 | [diff] [blame] | 13666 | This restricts the list of processes or threads on which this listener is |
Christopher Faulet | c644fa9 | 2017-11-23 22:44:11 +0100 | [diff] [blame] | 13667 | allowed to run. It does not enforce any process but eliminates those which do |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13668 | not match. If the frontend uses a "bind-process" setting, the intersection |
Christopher Faulet | c644fa9 | 2017-11-23 22:44:11 +0100 | [diff] [blame] | 13669 | between the two is applied. If in the end the listener is not allowed to run |
| 13670 | on any remaining process, a warning is emitted, and the listener will either |
| 13671 | run on the first process of the listener if a single process was specified, |
| 13672 | or on all of its processes if multiple processes were specified. If a thread |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13673 | set is specified, it limits the threads allowed to process incoming |
Willy Tarreau | a36b324 | 2019-02-02 13:14:34 +0100 | [diff] [blame] | 13674 | connections for this listener, for the the process set. If multiple processes |
| 13675 | and threads are configured, a warning is emitted, as it either results from a |
| 13676 | configuration error or a misunderstanding of these models. For the unlikely |
| 13677 | case where several ranges are needed, this directive may be repeated. |
| 13678 | <process-set> and <thread-set> must use the format |
Christopher Faulet | c644fa9 | 2017-11-23 22:44:11 +0100 | [diff] [blame] | 13679 | |
| 13680 | all | odd | even | number[-[number]] |
| 13681 | |
| 13682 | Ranges can be partially defined. The higher bound can be omitted. In such |
| 13683 | case, it is replaced by the corresponding maximum value. The main purpose of |
| 13684 | this directive is to be used with the stats sockets and have one different |
| 13685 | socket per process. The second purpose is to have multiple bind lines sharing |
| 13686 | the same IP:port but not the same process in a listener, so that the system |
| 13687 | can distribute the incoming connections into multiple queues and allow a |
| 13688 | smoother inter-process load balancing. Currently Linux 3.9 and above is known |
| 13689 | for supporting this. See also "bind-process" and "nbproc". |
Willy Tarreau | 6ae1ba6 | 2014-05-07 19:01:58 +0200 | [diff] [blame] | 13690 | |
Christopher Faulet | a717b99 | 2018-04-10 14:43:00 +0200 | [diff] [blame] | 13691 | proto <name> |
| 13692 | Forces the multiplexer's protocol to use for the incoming connections. It |
| 13693 | must be compatible with the mode of the frontend (TCP or HTTP). It must also |
| 13694 | be usable on the frontend side. The list of available protocols is reported |
Christopher Faulet | 982e17d | 2021-03-26 14:44:18 +0100 | [diff] [blame] | 13695 | in haproxy -vv. The protocols properties are reported : the mode (TCP/HTTP), |
| 13696 | the side (FE/BE), the mux name and its flags. |
| 13697 | |
| 13698 | Some protocols report errors on aborts (flag=CLEAN_ABRT). Some others are |
| 13699 | subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally |
| 13700 | some protocols don't support upgrades (flag=NO_UPG). The HTX compatibility is |
| 13701 | also reported (flag=HTX). |
| 13702 | |
| 13703 | Here are the protocols that may be used as argument to a "proto" directive on |
| 13704 | a bind line : |
| 13705 | |
| 13706 | h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|CLEAN_ABRT|HOL_RISK|NO_UPG |
| 13707 | h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG |
| 13708 | none : mode=TCP side=FE|BE mux=PASS flags=NO_UPG |
| 13709 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 13710 | Idea behind this option is to bypass the selection of the best multiplexer's |
Christopher Faulet | a717b99 | 2018-04-10 14:43:00 +0200 | [diff] [blame] | 13711 | protocol for all connections instantiated from this listening socket. For |
Joseph Herlant | 71b4b15 | 2018-11-13 16:55:16 -0800 | [diff] [blame] | 13712 | instance, it is possible to force the http/2 on clear TCP by specifying "proto |
Christopher Faulet | a717b99 | 2018-04-10 14:43:00 +0200 | [diff] [blame] | 13713 | h2" on the bind line. |
| 13714 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13715 | ssl |
| 13716 | 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] | 13717 | enables SSL deciphering on connections instantiated from this listener. A |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13718 | certificate is necessary (see "crt" above). All contents in the buffers will |
| 13719 | appear in clear text, so that ACLs and HTTP processing will only have access |
Emmanuel Hocdet | bd695fe | 2017-05-15 15:53:41 +0200 | [diff] [blame] | 13720 | to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3" |
| 13721 | to enable it. |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13722 | |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13723 | ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ] |
| 13724 | This option enforces use of <version> or lower on SSL connections instantiated |
William Lallemand | 50df1cb | 2020-06-02 10:52:24 +0200 | [diff] [blame] | 13725 | from this listener. Using this setting without "ssl-min-ver" can be |
| 13726 | ambiguous because the default ssl-min-ver value could change in future HAProxy |
| 13727 | versions. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13728 | "ssl-default-bind-options". See also "ssl-min-ver". |
| 13729 | |
| 13730 | ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ] |
William Lallemand | 50df1cb | 2020-06-02 10:52:24 +0200 | [diff] [blame] | 13731 | This option enforces use of <version> or upper on SSL connections |
| 13732 | instantiated from this listener. The default value is "TLSv1.2". This option |
| 13733 | is also available on global statement "ssl-default-bind-options". |
| 13734 | See also "ssl-max-ver". |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 13735 | |
Emmanuel Hocdet | 6562337 | 2013-01-24 17:17:15 +0100 | [diff] [blame] | 13736 | strict-sni |
| 13737 | This setting is only available when support for OpenSSL was built in. The |
| 13738 | SSL/TLS negotiation is allow only if the client provided an SNI which match |
| 13739 | a certificate. The default certificate is not used. |
| 13740 | See the "crt" option for more information. |
| 13741 | |
Willy Tarreau | 2af207a | 2015-02-04 00:45:58 +0100 | [diff] [blame] | 13742 | tcp-ut <delay> |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 13743 | Sets the TCP User Timeout for all incoming connections instantiated from this |
Willy Tarreau | 2af207a | 2015-02-04 00:45:58 +0100 | [diff] [blame] | 13744 | listening socket. This option is available on Linux since version 2.6.37. It |
| 13745 | allows haproxy to configure a timeout for sockets which contain data not |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13746 | receiving an acknowledgment for the configured delay. This is especially |
Willy Tarreau | 2af207a | 2015-02-04 00:45:58 +0100 | [diff] [blame] | 13747 | useful on long-lived connections experiencing long idle periods such as |
| 13748 | remote terminals or database connection pools, where the client and server |
| 13749 | timeouts must remain high to allow a long period of idle, but where it is |
| 13750 | important to detect that the client has disappeared in order to release all |
| 13751 | resources associated with its connection (and the server's session). The |
| 13752 | argument is a delay expressed in milliseconds by default. This only works |
| 13753 | for regular TCP connections, and is ignored for other protocols. |
| 13754 | |
Willy Tarreau | 1c862c5 | 2012-10-05 16:21:00 +0200 | [diff] [blame] | 13755 | tfo |
Lukas Tribus | 0defb90 | 2013-02-13 23:35:39 +0100 | [diff] [blame] | 13756 | 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] | 13757 | enables TCP Fast Open on the listening socket, which means that clients which |
| 13758 | support this feature will be able to send a request and receive a response |
| 13759 | during the 3-way handshake starting from second connection, thus saving one |
| 13760 | round-trip after the first connection. This only makes sense with protocols |
| 13761 | that use high connection rates and where each round trip matters. This can |
| 13762 | possibly cause issues with many firewalls which do not accept data on SYN |
| 13763 | 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] | 13764 | is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may |
| 13765 | need to build HAProxy with USE_TFO=1 if your libc doesn't define |
| 13766 | TCP_FASTOPEN. |
Willy Tarreau | 1c862c5 | 2012-10-05 16:21:00 +0200 | [diff] [blame] | 13767 | |
Nenad Merdanovic | 188ad3e | 2015-02-27 19:56:50 +0100 | [diff] [blame] | 13768 | tls-ticket-keys <keyfile> |
| 13769 | Sets the TLS ticket keys file to load the keys from. The keys need to be 48 |
Emeric Brun | 9e75477 | 2019-01-10 17:51:55 +0100 | [diff] [blame] | 13770 | or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64 |
| 13771 | with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo). |
| 13772 | The first key determines the key length used for next keys: you can't mix |
| 13773 | aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO |
| 13774 | build option (default 3) and at least as many keys need to be present in |
| 13775 | the file. Last TLS_TICKETS_NO keys will be used for decryption and the |
| 13776 | penultimate one for encryption. This enables easy key rotation by just |
| 13777 | appending new key to the file and reloading the process. Keys must be |
| 13778 | periodically rotated (ex. every 12h) or Perfect Forward Secrecy is |
| 13779 | compromised. It is also a good idea to keep the keys off any permanent |
Nenad Merdanovic | 188ad3e | 2015-02-27 19:56:50 +0100 | [diff] [blame] | 13780 | storage such as hard drives (hint: use tmpfs and don't swap those files). |
| 13781 | Lifetime hint can be changed using tune.ssl.timeout. |
| 13782 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13783 | transparent |
| 13784 | Is an optional keyword which is supported only on certain Linux kernels. It |
| 13785 | indicates that the addresses will be bound even if they do not belong to the |
| 13786 | local machine, and that packets targeting any of these addresses will be |
| 13787 | intercepted just as if the addresses were locally configured. This normally |
| 13788 | requires that IP forwarding is enabled. Caution! do not use this with the |
| 13789 | default address '*', as it would redirect any traffic for the specified port. |
| 13790 | This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1. |
| 13791 | This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on |
| 13792 | kernel version. Some distribution kernels include backports of the feature, |
| 13793 | so check for support with your vendor. |
| 13794 | |
Willy Tarreau | 77e3af9 | 2012-11-24 15:07:23 +0100 | [diff] [blame] | 13795 | v4v6 |
| 13796 | Is an optional keyword which is supported only on most recent systems |
| 13797 | including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4 |
| 13798 | and IPv6 when it uses the default address. Doing so is sometimes necessary |
| 13799 | 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] | 13800 | sockets, and is overridden by the "v6only" option. |
Willy Tarreau | 77e3af9 | 2012-11-24 15:07:23 +0100 | [diff] [blame] | 13801 | |
Willy Tarreau | 9b6700f | 2012-11-24 11:55:28 +0100 | [diff] [blame] | 13802 | v6only |
| 13803 | Is an optional keyword which is supported only on most recent systems |
| 13804 | including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only |
| 13805 | 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] | 13806 | system-wide as it is per-listener. It has no effect on non-IPv6 sockets and |
| 13807 | has precedence over the "v4v6" option. |
Willy Tarreau | 9b6700f | 2012-11-24 11:55:28 +0100 | [diff] [blame] | 13808 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13809 | uid <uid> |
| 13810 | Sets the owner of the UNIX sockets to the designated system uid. It can also |
| 13811 | be set by default in the global section's "unix-bind" statement. Note that |
| 13812 | some platforms simply ignore this. This setting is equivalent to the "user" |
| 13813 | setting except that the user numeric ID is used instead of its name. This |
| 13814 | setting is ignored by non UNIX sockets. |
| 13815 | |
| 13816 | user <user> |
| 13817 | Sets the owner of the UNIX sockets to the designated system user. It can also |
| 13818 | be set by default in the global section's "unix-bind" statement. Note that |
| 13819 | some platforms simply ignore this. This setting is equivalent to the "uid" |
| 13820 | setting except that the user name is used instead of its uid. This setting is |
| 13821 | ignored by non UNIX sockets. |
| 13822 | |
Emeric Brun | 1a073b4 | 2012-09-28 17:07:34 +0200 | [diff] [blame] | 13823 | verify [none|optional|required] |
| 13824 | This setting is only available when support for OpenSSL was built in. If set |
| 13825 | to 'none', client certificate is not requested. This is the default. In other |
| 13826 | cases, a client certificate is requested. If the client does not provide a |
| 13827 | certificate after the request and if 'verify' is set to 'required', then the |
| 13828 | 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] | 13829 | certificate provided by the client is always verified using CAs from |
| 13830 | 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake |
| 13831 | is aborted, regardless of the 'verify' option, unless the error code exactly |
| 13832 | 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] | 13833 | |
Willy Tarreau | b6205fd | 2012-09-24 12:27:33 +0200 | [diff] [blame] | 13834 | 5.2. Server and default-server options |
Cyril Bonté | f0c6061 | 2010-02-06 14:44:47 +0100 | [diff] [blame] | 13835 | ------------------------------------ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 13836 | |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 13837 | The "server" and "default-server" keywords support a certain number of settings |
| 13838 | which are all passed as arguments on the server line. The order in which those |
| 13839 | arguments appear does not count, and they are all optional. Some of those |
| 13840 | settings are single words (booleans) while others expect one or several values |
| 13841 | after them. In this case, the values must immediately follow the setting name. |
| 13842 | Except default-server, all those settings must be specified after the server's |
| 13843 | address if they are used: |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 13844 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 13845 | server <name> <address>[:port] [settings ...] |
Krzysztof Piotr Oledzki | c6df066 | 2010-01-05 16:38:49 +0100 | [diff] [blame] | 13846 | default-server [settings ...] |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 13847 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 13848 | Note that all these settings are supported both by "server" and "default-server" |
| 13849 | keywords, except "id" which is only supported by "server". |
| 13850 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 13851 | The currently supported settings are the following ones. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 13852 | |
Willy Tarreau | ceb4ac9 | 2012-04-28 00:41:46 +0200 | [diff] [blame] | 13853 | addr <ipv4|ipv6> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 13854 | Using the "addr" parameter, it becomes possible to use a different IP address |
Baptiste Assmann | 13f8353 | 2016-03-06 23:14:36 +0100 | [diff] [blame] | 13855 | to send health-checks or to probe the agent-check. On some servers, it may be |
| 13856 | desirable to dedicate an IP address to specific component able to perform |
| 13857 | complex tests which are more suitable to health-checks than the application. |
| 13858 | This parameter is ignored if the "check" parameter is not set. See also the |
| 13859 | "port" parameter. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 13860 | |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13861 | agent-check |
| 13862 | Enable an auxiliary agent check which is run independently of a regular |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13863 | health check. An agent health check is performed by making a TCP connection |
Willy Tarreau | 7a0139e | 2018-12-16 08:42:56 +0100 | [diff] [blame] | 13864 | to the port set by the "agent-port" parameter and reading an ASCII string |
| 13865 | terminated by the first '\r' or '\n' met. The string is made of a series of |
| 13866 | words delimited by spaces, tabs or commas in any order, each consisting of : |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13867 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13868 | - An ASCII representation of a positive integer percentage, e.g. "75%". |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13869 | Values in this format will set the weight proportional to the initial |
Willy Tarreau | c5af3a6 | 2014-10-07 15:27:33 +0200 | [diff] [blame] | 13870 | weight of a server as configured when haproxy starts. Note that a zero |
| 13871 | weight is reported on the stats page as "DRAIN" since it has the same |
| 13872 | effect on the server (it's removed from the LB farm). |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13873 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13874 | - The string "maxconn:" followed by an integer (no space between). Values |
| 13875 | in this format will set the maxconn of a server. The maximum number of |
| 13876 | connections advertised needs to be multiplied by the number of load |
| 13877 | balancers and different backends that use this health check to get the |
| 13878 | total number of connections the server might receive. Example: maxconn:30 |
Nenad Merdanovic | 174dd37 | 2016-04-24 23:10:06 +0200 | [diff] [blame] | 13879 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13880 | - The word "ready". This will turn the server's administrative state to the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13881 | READY mode, thus canceling any DRAIN or MAINT state |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13882 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13883 | - The word "drain". This will turn the server's administrative state to the |
| 13884 | DRAIN mode, thus it will not accept any new connections other than those |
| 13885 | that are accepted via persistence. |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13886 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13887 | - The word "maint". This will turn the server's administrative state to the |
| 13888 | MAINT mode, thus it will not accept any new connections at all, and health |
| 13889 | checks will be stopped. |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13890 | |
William Dauchy | f8e795c | 2020-09-26 13:35:51 +0200 | [diff] [blame] | 13891 | - The words "down", "fail", or "stopped", optionally followed by a |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13892 | description string after a sharp ('#'). All of these mark the server's |
| 13893 | operating state as DOWN, but since the word itself is reported on the stats |
| 13894 | page, the difference allows an administrator to know if the situation was |
| 13895 | expected or not : the service may intentionally be stopped, may appear up |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 13896 | but fail some validity tests, or may be seen as down (e.g. missing process, |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13897 | or port not responding). |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13898 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13899 | - The word "up" sets back the server's operating state as UP if health checks |
| 13900 | also report that the service is accessible. |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13901 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13902 | Parameters which are not advertised by the agent are not changed. For |
| 13903 | example, an agent might be designed to monitor CPU usage and only report a |
| 13904 | relative weight and never interact with the operating status. Similarly, an |
| 13905 | agent could be designed as an end-user interface with 3 radio buttons |
| 13906 | allowing an administrator to change only the administrative state. However, |
| 13907 | it is important to consider that only the agent may revert its own actions, |
| 13908 | so if a server is set to DRAIN mode or to DOWN state using the agent, the |
| 13909 | agent must implement the other equivalent actions to bring the service into |
| 13910 | operations again. |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13911 | |
Simon Horman | 2f1f955 | 2013-11-25 10:46:37 +0900 | [diff] [blame] | 13912 | Failure to connect to the agent is not considered an error as connectivity |
| 13913 | is tested by the regular health check which is enabled by the "check" |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13914 | parameter. Warning though, it is not a good idea to stop an agent after it |
| 13915 | reports "down", since only an agent reporting "up" will be able to turn the |
| 13916 | server up again. Note that the CLI on the Unix stats socket is also able to |
Willy Tarreau | 989222a | 2016-01-15 10:26:26 +0100 | [diff] [blame] | 13917 | force an agent's result in order to work around a bogus agent if needed. |
Simon Horman | 2f1f955 | 2013-11-25 10:46:37 +0900 | [diff] [blame] | 13918 | |
Willy Tarreau | 81f5d94 | 2013-12-09 20:51:51 +0100 | [diff] [blame] | 13919 | Requires the "agent-port" parameter to be set. See also the "agent-inter" |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 13920 | and "no-agent-check" parameters. |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13921 | |
James Brown | 55f9ff1 | 2015-10-21 18:19:05 -0700 | [diff] [blame] | 13922 | agent-send <string> |
| 13923 | If this option is specified, haproxy will send the given string (verbatim) |
| 13924 | to the agent server upon connection. You could, for example, encode |
| 13925 | the backend name into this string, which would enable your agent to send |
| 13926 | different responses based on the backend. Make sure to include a '\n' if |
| 13927 | you want to terminate your request with a newline. |
| 13928 | |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13929 | agent-inter <delay> |
| 13930 | The "agent-inter" parameter sets the interval between two agent checks |
| 13931 | to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms. |
| 13932 | |
| 13933 | Just as with every other time-based parameter, it may be entered in any |
| 13934 | other explicit unit among { us, ms, s, m, h, d }. The "agent-inter" |
| 13935 | parameter also serves as a timeout for agent checks "timeout check" is |
| 13936 | not set. In order to reduce "resonance" effects when multiple servers are |
| 13937 | hosted on the same hardware, the agent and health checks of all servers |
| 13938 | are started with a small time offset between them. It is also possible to |
| 13939 | add some random noise in the agent and health checks interval using the |
| 13940 | global "spread-checks" keyword. This makes sense for instance when a lot |
| 13941 | of backends use the same servers. |
| 13942 | |
| 13943 | See also the "agent-check" and "agent-port" parameters. |
| 13944 | |
Misiek | 768d860 | 2017-01-09 09:52:43 +0100 | [diff] [blame] | 13945 | agent-addr <addr> |
| 13946 | The "agent-addr" parameter sets address for agent check. |
| 13947 | |
| 13948 | You can offload agent-check to another target, so you can make single place |
| 13949 | managing status and weights of servers defined in haproxy in case you can't |
| 13950 | make self-aware and self-managing services. You can specify both IP or |
| 13951 | hostname, it will be resolved. |
| 13952 | |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 13953 | agent-port <port> |
| 13954 | The "agent-port" parameter sets the TCP port used for agent checks. |
| 13955 | |
| 13956 | See also the "agent-check" and "agent-inter" parameters. |
| 13957 | |
Olivier Houchard | 8cb2d2e | 2019-05-06 18:58:48 +0200 | [diff] [blame] | 13958 | allow-0rtt |
| 13959 | Allow sending early data to the server when using TLS 1.3. |
Olivier Houchard | 22c9b44 | 2019-05-06 19:01:04 +0200 | [diff] [blame] | 13960 | Note that early data will be sent only if the client used early data, or |
| 13961 | if the backend uses "retry-on" with the "0rtt-rejected" keyword. |
Olivier Houchard | 8cb2d2e | 2019-05-06 18:58:48 +0200 | [diff] [blame] | 13962 | |
Olivier Houchard | c756600 | 2018-11-20 23:33:50 +0100 | [diff] [blame] | 13963 | alpn <protocols> |
| 13964 | This enables the TLS ALPN extension and advertises the specified protocol |
| 13965 | list as supported on top of ALPN. The protocol list consists in a comma- |
| 13966 | delimited list of protocol names, for instance: "http/1.1,http/1.0" (without |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 13967 | quotes). This requires that the SSL library is built with support for TLS |
Olivier Houchard | c756600 | 2018-11-20 23:33:50 +0100 | [diff] [blame] | 13968 | extensions enabled (check with haproxy -vv). The ALPN extension replaces the |
| 13969 | initial NPN extension. ALPN is required to connect to HTTP/2 servers. |
| 13970 | Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the |
| 13971 | now obsolete NPN extension. |
| 13972 | If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can |
| 13973 | be advertised, in order of preference, like below : |
| 13974 | |
| 13975 | server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1 |
| 13976 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 13977 | backup |
| 13978 | When "backup" is present on a server line, the server is only used in load |
| 13979 | balancing when all other non-backup servers are unavailable. Requests coming |
| 13980 | with a persistence cookie referencing the server will always be served |
| 13981 | though. By default, only the first operational backup server is used, unless |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 13982 | the "allbackups" option is set in the backend. See also the "no-backup" and |
| 13983 | "allbackups" options. |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 13984 | |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 13985 | ca-file <cafile> |
| 13986 | This setting is only available when support for OpenSSL was built in. It |
| 13987 | designates a PEM file from which to load CA certificates used to verify |
| 13988 | server's certificate. |
| 13989 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 13990 | check |
Jerome Magnin | 90702bc | 2020-04-26 14:23:04 +0200 | [diff] [blame] | 13991 | This option enables health checks on a server: |
| 13992 | - when not set, no health checking is performed, and the server is always |
| 13993 | considered available. |
| 13994 | - when set and no other check method is configured, the server is considered |
| 13995 | available when a connection can be established at the highest configured |
| 13996 | transport layer. This means TCP by default, or SSL/TLS when "ssl" or |
| 13997 | "check-ssl" are set, both possibly combined with connection prefixes such |
| 13998 | as a PROXY protocol header when "send-proxy" or "check-send-proxy" are |
| 13999 | set. |
| 14000 | - when set and an application-level health check is defined, the |
| 14001 | application-level exchanges are performed on top of the configured |
| 14002 | transport layer and the server is considered available if all of the |
| 14003 | exchanges succeed. |
| 14004 | |
| 14005 | By default, health checks are performed on the same address and port as |
| 14006 | configured on the server, using the same encapsulation parameters (SSL/TLS, |
| 14007 | proxy-protocol header, etc... ). It is possible to change the destination |
| 14008 | address using "addr" and the port using "port". When done, it is assumed the |
| 14009 | server isn't checked on the service port, and configured encapsulation |
Ilya Shipitsin | 4329a9a | 2020-05-05 21:17:10 +0500 | [diff] [blame] | 14010 | parameters are not reused. One must explicitly set "check-send-proxy" to send |
Jerome Magnin | 90702bc | 2020-04-26 14:23:04 +0200 | [diff] [blame] | 14011 | connection headers, "check-ssl" to use SSL/TLS. |
| 14012 | |
| 14013 | When "sni" or "alpn" are set on the server line, their value is not used for |
| 14014 | health checks and one must use "check-sni" or "check-alpn". |
| 14015 | |
| 14016 | The default source address for health check traffic is the same as the one |
| 14017 | defined in the backend. It can be changed with the "source" keyword. |
| 14018 | |
| 14019 | The interval between checks can be set using the "inter" keyword, and the |
| 14020 | "rise" and "fall" keywords can be used to define how many successful or |
| 14021 | failed health checks are required to flag a server available or not |
| 14022 | available. |
| 14023 | |
| 14024 | Optional application-level health checks can be configured with "option |
| 14025 | httpchk", "option mysql-check" "option smtpchk", "option pgsql-check", |
| 14026 | "option ldap-check", or "option redis-check". |
| 14027 | |
| 14028 | Example: |
| 14029 | # simple tcp check |
| 14030 | backend foo |
| 14031 | server s1 192.168.0.1:80 check |
| 14032 | # this does a tcp connect + tls handshake |
| 14033 | backend foo |
| 14034 | server s1 192.168.0.1:443 ssl check |
| 14035 | # simple tcp check is enough for check success |
| 14036 | backend foo |
| 14037 | option tcp-check |
| 14038 | tcp-check connect |
| 14039 | server s1 192.168.0.1:443 ssl check |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14040 | |
Willy Tarreau | 6c16adc | 2012-10-05 00:04:16 +0200 | [diff] [blame] | 14041 | check-send-proxy |
| 14042 | This option forces emission of a PROXY protocol line with outgoing health |
| 14043 | checks, regardless of whether the server uses send-proxy or not for the |
| 14044 | normal traffic. By default, the PROXY protocol is enabled for health checks |
| 14045 | if it is already enabled for normal traffic and if no "port" nor "addr" |
| 14046 | directive is present. However, if such a directive is present, the |
| 14047 | "check-send-proxy" option needs to be used to force the use of the |
| 14048 | protocol. See also the "send-proxy" option for more information. |
| 14049 | |
Olivier Houchard | 9215014 | 2018-12-21 19:47:01 +0100 | [diff] [blame] | 14050 | check-alpn <protocols> |
| 14051 | Defines which protocols to advertise with ALPN. The protocol list consists in |
| 14052 | a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0" |
| 14053 | (without quotes). If it is not set, the server ALPN is used. |
| 14054 | |
Christopher Faulet | edc6ed9 | 2020-04-23 16:27:59 +0200 | [diff] [blame] | 14055 | check-proto <name> |
| 14056 | Forces the multiplexer's protocol to use for the server's health-check |
| 14057 | connections. It must be compatible with the health-check type (TCP or |
| 14058 | HTTP). It must also be usable on the backend side. The list of available |
Christopher Faulet | 982e17d | 2021-03-26 14:44:18 +0100 | [diff] [blame] | 14059 | protocols is reported in haproxy -vv. The protocols properties are |
| 14060 | reported : the mode (TCP/HTTP), the side (FE/BE), the mux name and its flags. |
| 14061 | |
| 14062 | Some protocols report errors on aborts (flag=CLEAN_ABRT). Some others are |
| 14063 | subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally |
| 14064 | some protocols don't support upgrades (flag=NO_UPG). The HTX compatibility is |
| 14065 | also reported (flag=HTX). |
| 14066 | |
| 14067 | Here are the protocols that may be used as argument to a "check-proto" |
| 14068 | directive on a server line: |
| 14069 | |
| 14070 | h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|CLEAN_ABRT|HOL_RISK|NO_UPG |
| 14071 | fcgi : mode=HTTP side=BE mux=FCGI flags=HTX|HOL_RISK|NO_UPG |
| 14072 | h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG |
| 14073 | none : mode=TCP side=FE|BE mux=PASS flags=NO_UPG |
| 14074 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 14075 | Idea behind this option is to bypass the selection of the best multiplexer's |
Christopher Faulet | edc6ed9 | 2020-04-23 16:27:59 +0200 | [diff] [blame] | 14076 | protocol for health-check connections established to this server. |
| 14077 | If not defined, the server one will be used, if set. |
| 14078 | |
Jérôme Magnin | ae9bb76 | 2018-12-09 16:08:26 +0100 | [diff] [blame] | 14079 | check-sni <sni> |
Olivier Houchard | 9130a96 | 2017-10-17 17:33:43 +0200 | [diff] [blame] | 14080 | This option allows you to specify the SNI to be used when doing health checks |
Jérôme Magnin | ae9bb76 | 2018-12-09 16:08:26 +0100 | [diff] [blame] | 14081 | over SSL. It is only possible to use a string to set <sni>. If you want to |
| 14082 | set a SNI for proxied traffic, see "sni". |
Olivier Houchard | 9130a96 | 2017-10-17 17:33:43 +0200 | [diff] [blame] | 14083 | |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 14084 | check-ssl |
| 14085 | This option forces encryption of all health checks over SSL, regardless of |
| 14086 | whether the server uses SSL or not for the normal traffic. This is generally |
| 14087 | used when an explicit "port" or "addr" directive is specified and SSL health |
| 14088 | checks are not inherited. It is important to understand that this option |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 14089 | 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] | 14090 | check becomes an SSL connect, which replaces the old ssl-hello-chk. The most |
| 14091 | common use is to send HTTPS checks by combining "httpchk" with SSL checks. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14092 | All SSL settings are common to health checks and traffic (e.g. ciphers). |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14093 | See the "ssl" option for more information and "no-check-ssl" to disable |
| 14094 | this option. |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 14095 | |
Alexander Liu | 2a54bb7 | 2019-05-22 19:44:48 +0800 | [diff] [blame] | 14096 | check-via-socks4 |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 14097 | This option enables outgoing health checks using upstream socks4 proxy. By |
Alexander Liu | 2a54bb7 | 2019-05-22 19:44:48 +0800 | [diff] [blame] | 14098 | default, the health checks won't go through socks tunnel even it was enabled |
| 14099 | for normal traffic. |
| 14100 | |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14101 | ciphers <ciphers> |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 14102 | This setting is only available when support for OpenSSL was built in. This |
| 14103 | option sets the string describing the list of cipher algorithms that is |
| 14104 | negotiated during the SSL/TLS handshake with the server. The format of the |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 14105 | string is defined in "man 1 ciphers" from OpenSSL man pages. For background |
| 14106 | information and recommendations see e.g. |
| 14107 | (https://wiki.mozilla.org/Security/Server_Side_TLS) and |
| 14108 | (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3 |
| 14109 | cipher configuration, please check the "ciphersuites" keyword. |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14110 | |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 14111 | ciphersuites <ciphersuites> |
| 14112 | This setting is only available when support for OpenSSL was built in and |
| 14113 | OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string |
| 14114 | describing the list of cipher algorithms that is negotiated during the TLS |
| 14115 | 1.3 handshake with the server. The format of the string is defined in |
Bertrand Jacquin | 4f03ab0 | 2019-02-03 18:48:49 +0000 | [diff] [blame] | 14116 | "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section. |
| 14117 | For cipher configuration for TLSv1.2 and earlier, please check the "ciphers" |
| 14118 | keyword. |
Dirkjan Bussink | 415150f | 2018-09-14 11:14:21 +0200 | [diff] [blame] | 14119 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14120 | cookie <value> |
| 14121 | The "cookie" parameter sets the cookie value assigned to the server to |
| 14122 | <value>. This value will be checked in incoming requests, and the first |
| 14123 | operational server possessing the same value will be selected. In return, in |
| 14124 | cookie insertion or rewrite modes, this value will be assigned to the cookie |
| 14125 | sent to the client. There is nothing wrong in having several servers sharing |
| 14126 | the same cookie value, and it is in fact somewhat common between normal and |
| 14127 | backup servers. See also the "cookie" keyword in backend section. |
| 14128 | |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 14129 | crl-file <crlfile> |
| 14130 | This setting is only available when support for OpenSSL was built in. It |
| 14131 | designates a PEM file from which to load certificate revocation list used |
| 14132 | to verify server's certificate. |
| 14133 | |
Emeric Brun | a7aa309 | 2012-10-26 12:58:00 +0200 | [diff] [blame] | 14134 | crt <cert> |
| 14135 | This setting is only available when support for OpenSSL was built in. |
| 14136 | It designates a PEM file from which to load both a certificate and the |
| 14137 | associated private key. This file can be built by concatenating both PEM |
| 14138 | files into one. This certificate will be sent if the server send a client |
| 14139 | certificate request. |
| 14140 | |
Willy Tarreau | 9683909 | 2010-03-29 10:02:24 +0200 | [diff] [blame] | 14141 | disabled |
| 14142 | The "disabled" keyword starts the server in the "disabled" state. That means |
| 14143 | that it is marked down in maintenance mode, and no connection other than the |
| 14144 | ones allowed by persist mode will reach it. It is very well suited to setup |
| 14145 | new servers, because normal traffic will never reach them, while it is still |
| 14146 | possible to test the service by making use of the force-persist mechanism. |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14147 | See also "enabled" setting. |
Willy Tarreau | 9683909 | 2010-03-29 10:02:24 +0200 | [diff] [blame] | 14148 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14149 | enabled |
| 14150 | This option may be used as 'server' setting to reset any 'disabled' |
| 14151 | setting which would have been inherited from 'default-server' directive as |
| 14152 | default value. |
| 14153 | It may also be used as 'default-server' setting to reset any previous |
| 14154 | 'default-server' 'disabled' setting. |
Willy Tarreau | 9683909 | 2010-03-29 10:02:24 +0200 | [diff] [blame] | 14155 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14156 | error-limit <count> |
Willy Tarreau | 983e01e | 2010-01-11 18:42:06 +0100 | [diff] [blame] | 14157 | If health observing is enabled, the "error-limit" parameter specifies the |
| 14158 | number of consecutive errors that triggers event selected by the "on-error" |
| 14159 | option. By default it is set to 10 consecutive errors. |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 14160 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14161 | See also the "check", "error-limit" and "on-error". |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 14162 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14163 | fall <count> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14164 | The "fall" parameter states that a server will be considered as dead after |
| 14165 | <count> consecutive unsuccessful health checks. This value defaults to 3 if |
| 14166 | unspecified. See also the "check", "inter" and "rise" parameters. |
| 14167 | |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14168 | force-sslv3 |
| 14169 | This option enforces use of SSLv3 only when SSL is used to communicate with |
| 14170 | the server. SSLv3 is generally less expensive than the TLS counterparts for |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14171 | high connection rates. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14172 | "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver". |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14173 | |
| 14174 | force-tlsv10 |
| 14175 | This option enforces use of TLSv1.0 only when SSL is used to communicate with |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14176 | the server. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14177 | "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver". |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14178 | |
| 14179 | force-tlsv11 |
| 14180 | This option enforces use of TLSv1.1 only when SSL is used to communicate with |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14181 | the server. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14182 | "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver". |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14183 | |
| 14184 | force-tlsv12 |
| 14185 | This option enforces use of TLSv1.2 only when SSL is used to communicate with |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14186 | the server. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14187 | "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver". |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14188 | |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 14189 | force-tlsv13 |
| 14190 | This option enforces use of TLSv1.3 only when SSL is used to communicate with |
| 14191 | the server. This option is also available on global statement |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14192 | "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver". |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 14193 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14194 | id <value> |
Willy Tarreau | 53fb4ae | 2009-10-04 23:04:08 +0200 | [diff] [blame] | 14195 | Set a persistent ID for the server. This ID must be positive and unique for |
| 14196 | the proxy. An unused ID will automatically be assigned if unset. The first |
| 14197 | 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] | 14198 | |
Willy Tarreau | 6a031d1 | 2016-11-07 19:42:35 +0100 | [diff] [blame] | 14199 | init-addr {last | libc | none | <ip>},[...]* |
| 14200 | Indicate in what order the server's address should be resolved upon startup |
| 14201 | if it uses an FQDN. Attempts are made to resolve the address by applying in |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14202 | turn each of the methods mentioned in the comma-delimited list. The first |
Willy Tarreau | 6a031d1 | 2016-11-07 19:42:35 +0100 | [diff] [blame] | 14203 | method which succeeds is used. If the end of the list is reached without |
| 14204 | finding a working method, an error is thrown. Method "last" suggests to pick |
| 14205 | the address which appears in the state file (see "server-state-file"). Method |
| 14206 | "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo() |
| 14207 | depending on the operating system and build options). Method "none" |
| 14208 | specifically indicates that the server should start without any valid IP |
| 14209 | address in a down state. It can be useful to ignore some DNS issues upon |
| 14210 | startup, waiting for the situation to get fixed later. Finally, an IP address |
| 14211 | (IPv4 or IPv6) may be provided. It can be the currently known address of the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14212 | server (e.g. filled by a configuration generator), or the address of a dummy |
Willy Tarreau | 6a031d1 | 2016-11-07 19:42:35 +0100 | [diff] [blame] | 14213 | server used to catch old sessions and present them with a decent error |
| 14214 | message for example. When the "first" load balancing algorithm is used, this |
| 14215 | IP address could point to a fake server used to trigger the creation of new |
| 14216 | instances on the fly. This option defaults to "last,libc" indicating that the |
| 14217 | previous address found in the state file (if any) is used first, otherwise |
| 14218 | the libc's resolver is used. This ensures continued compatibility with the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14219 | historic behavior. |
Willy Tarreau | 6a031d1 | 2016-11-07 19:42:35 +0100 | [diff] [blame] | 14220 | |
| 14221 | Example: |
| 14222 | defaults |
| 14223 | # never fail on address resolution |
| 14224 | default-server init-addr last,libc,none |
| 14225 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14226 | inter <delay> |
| 14227 | fastinter <delay> |
| 14228 | downinter <delay> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14229 | The "inter" parameter sets the interval between two consecutive health checks |
| 14230 | to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms. |
| 14231 | It is also possible to use "fastinter" and "downinter" to optimize delays |
| 14232 | between checks depending on the server state : |
| 14233 | |
Pieter Baauw | 44fc9df | 2015-09-17 21:30:46 +0200 | [diff] [blame] | 14234 | Server state | Interval used |
| 14235 | ----------------------------------------+---------------------------------- |
| 14236 | UP 100% (non-transitional) | "inter" |
| 14237 | ----------------------------------------+---------------------------------- |
| 14238 | Transitionally UP (going down "fall"), | "fastinter" if set, |
| 14239 | Transitionally DOWN (going up "rise"), | "inter" otherwise. |
| 14240 | or yet unchecked. | |
| 14241 | ----------------------------------------+---------------------------------- |
| 14242 | DOWN 100% (non-transitional) | "downinter" if set, |
| 14243 | | "inter" otherwise. |
| 14244 | ----------------------------------------+---------------------------------- |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 14245 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14246 | Just as with every other time-based parameter, they can be entered in any |
| 14247 | other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also |
| 14248 | serves as a timeout for health checks sent to servers if "timeout check" is |
| 14249 | not set. In order to reduce "resonance" effects when multiple servers are |
Simon Horman | d60d691 | 2013-11-25 10:46:36 +0900 | [diff] [blame] | 14250 | hosted on the same hardware, the agent and health checks of all servers |
| 14251 | are started with a small time offset between them. It is also possible to |
| 14252 | add some random noise in the agent and health checks interval using the |
| 14253 | global "spread-checks" keyword. This makes sense for instance when a lot |
| 14254 | of backends use the same servers. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14255 | |
Emeric Brun | 9755647 | 2020-05-30 01:42:45 +0200 | [diff] [blame] | 14256 | log-proto <logproto> |
| 14257 | The "log-proto" specifies the protocol used to forward event messages to |
| 14258 | a server configured in a ring section. Possible values are "legacy" |
| 14259 | and "octet-count" corresponding respectively to "Non-transparent-framing" |
| 14260 | and "Octet counting" in rfc6587. "legacy" is the default. |
| 14261 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14262 | maxconn <maxconn> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14263 | The "maxconn" parameter specifies the maximal number of concurrent |
| 14264 | connections that will be sent to this server. If the number of incoming |
Tim Duesterhus | cefbbd9 | 2019-11-27 22:35:27 +0100 | [diff] [blame] | 14265 | concurrent connections goes higher than this value, they will be queued, |
| 14266 | waiting for a slot to be released. This parameter is very important as it can |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14267 | save fragile servers from going down under extreme loads. If a "minconn" |
| 14268 | parameter is specified, the limit becomes dynamic. The default value is "0" |
| 14269 | which means unlimited. See also the "minconn" and "maxqueue" parameters, and |
| 14270 | the backend's "fullconn" keyword. |
| 14271 | |
Tim Duesterhus | cefbbd9 | 2019-11-27 22:35:27 +0100 | [diff] [blame] | 14272 | In HTTP mode this parameter limits the number of concurrent requests instead |
| 14273 | of the number of connections. Multiple requests might be multiplexed over a |
| 14274 | single TCP connection to the server. As an example if you specify a maxconn |
| 14275 | of 50 you might see between 1 and 50 actual server connections, but no more |
| 14276 | than 50 concurrent requests. |
| 14277 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14278 | maxqueue <maxqueue> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14279 | The "maxqueue" parameter specifies the maximal number of connections which |
| 14280 | will wait in the queue for this server. If this limit is reached, next |
| 14281 | requests will be redispatched to other servers instead of indefinitely |
| 14282 | waiting to be served. This will break persistence but may allow people to |
Willy Tarreau | 8ae8c48 | 2020-10-22 17:19:07 +0200 | [diff] [blame] | 14283 | quickly re-log in when the server they try to connect to is dying. Some load |
| 14284 | balancing algorithms such as leastconn take this into account and accept to |
| 14285 | add requests into a server's queue up to this value if it is explicitly set |
| 14286 | to a value greater than zero, which often allows to better smooth the load |
| 14287 | when dealing with single-digit maxconn values. The default value is "0" which |
| 14288 | means the queue is unlimited. See also the "maxconn" and "minconn" parameters |
| 14289 | and "balance leastconn". |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14290 | |
Willy Tarreau | 9c538e0 | 2019-01-23 10:21:49 +0100 | [diff] [blame] | 14291 | max-reuse <count> |
| 14292 | The "max-reuse" argument indicates the HTTP connection processors that they |
| 14293 | should not reuse a server connection more than this number of times to send |
| 14294 | new requests. Permitted values are -1 (the default), which disables this |
| 14295 | limit, or any positive value. Value zero will effectively disable keep-alive. |
| 14296 | This is only used to work around certain server bugs which cause them to leak |
| 14297 | resources over time. The argument is not necessarily respected by the lower |
| 14298 | layers as there might be technical limitations making it impossible to |
| 14299 | enforce. At least HTTP/2 connections to servers will respect it. |
| 14300 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14301 | minconn <minconn> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14302 | When the "minconn" parameter is set, the maxconn limit becomes a dynamic |
| 14303 | limit following the backend's load. The server will always accept at least |
| 14304 | <minconn> connections, never more than <maxconn>, and the limit will be on |
| 14305 | the ramp between both values when the backend has less than <fullconn> |
| 14306 | concurrent connections. This makes it possible to limit the load on the |
| 14307 | 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] | 14308 | overloading the server during exceptional loads. See also the "maxconn" |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14309 | and "maxqueue" parameters, as well as the "fullconn" backend keyword. |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 14310 | |
Willy Tarreau | d72f0f3 | 2015-10-13 14:50:22 +0200 | [diff] [blame] | 14311 | namespace <name> |
| 14312 | On Linux, it is possible to specify which network namespace a socket will |
| 14313 | belong to. This directive makes it possible to explicitly bind a server to |
| 14314 | a namespace different from the default one. Please refer to your operating |
| 14315 | system's documentation to find more details about network namespaces. |
| 14316 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14317 | no-agent-check |
| 14318 | This option may be used as "server" setting to reset any "agent-check" |
| 14319 | setting which would have been inherited from "default-server" directive as |
| 14320 | default value. |
| 14321 | It may also be used as "default-server" setting to reset any previous |
| 14322 | "default-server" "agent-check" setting. |
| 14323 | |
| 14324 | no-backup |
| 14325 | This option may be used as "server" setting to reset any "backup" |
| 14326 | setting which would have been inherited from "default-server" directive as |
| 14327 | default value. |
| 14328 | It may also be used as "default-server" setting to reset any previous |
| 14329 | "default-server" "backup" setting. |
| 14330 | |
| 14331 | no-check |
| 14332 | This option may be used as "server" setting to reset any "check" |
| 14333 | setting which would have been inherited from "default-server" directive as |
| 14334 | default value. |
| 14335 | It may also be used as "default-server" setting to reset any previous |
| 14336 | "default-server" "check" setting. |
| 14337 | |
| 14338 | no-check-ssl |
| 14339 | This option may be used as "server" setting to reset any "check-ssl" |
| 14340 | setting which would have been inherited from "default-server" directive as |
| 14341 | default value. |
| 14342 | It may also be used as "default-server" setting to reset any previous |
| 14343 | "default-server" "check-ssl" setting. |
| 14344 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14345 | no-send-proxy |
| 14346 | This option may be used as "server" setting to reset any "send-proxy" |
| 14347 | setting which would have been inherited from "default-server" directive as |
| 14348 | default value. |
| 14349 | It may also be used as "default-server" setting to reset any previous |
| 14350 | "default-server" "send-proxy" setting. |
| 14351 | |
| 14352 | no-send-proxy-v2 |
| 14353 | This option may be used as "server" setting to reset any "send-proxy-v2" |
| 14354 | setting which would have been inherited from "default-server" directive as |
| 14355 | default value. |
| 14356 | It may also be used as "default-server" setting to reset any previous |
| 14357 | "default-server" "send-proxy-v2" setting. |
| 14358 | |
| 14359 | no-send-proxy-v2-ssl |
| 14360 | This option may be used as "server" setting to reset any "send-proxy-v2-ssl" |
| 14361 | setting which would have been inherited from "default-server" directive as |
| 14362 | default value. |
| 14363 | It may also be used as "default-server" setting to reset any previous |
| 14364 | "default-server" "send-proxy-v2-ssl" setting. |
| 14365 | |
| 14366 | no-send-proxy-v2-ssl-cn |
| 14367 | This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn" |
| 14368 | setting which would have been inherited from "default-server" directive as |
| 14369 | default value. |
| 14370 | It may also be used as "default-server" setting to reset any previous |
| 14371 | "default-server" "send-proxy-v2-ssl-cn" setting. |
| 14372 | |
| 14373 | no-ssl |
| 14374 | This option may be used as "server" setting to reset any "ssl" |
| 14375 | setting which would have been inherited from "default-server" directive as |
| 14376 | default value. |
| 14377 | It may also be used as "default-server" setting to reset any previous |
| 14378 | "default-server" "ssl" setting. |
| 14379 | |
William Dauchy | f637044 | 2020-11-14 19:25:33 +0100 | [diff] [blame] | 14380 | Note that using `default-server ssl` setting and `no-ssl` on server will |
| 14381 | however init SSL connection, so it can be later be enabled through the |
| 14382 | runtime API: see `set server` commands in management doc. |
| 14383 | |
Willy Tarreau | 2a3fb1c | 2015-02-05 16:47:07 +0100 | [diff] [blame] | 14384 | no-ssl-reuse |
| 14385 | This option disables SSL session reuse when SSL is used to communicate with |
| 14386 | the server. It will force the server to perform a full handshake for every |
| 14387 | new connection. It's probably only useful for benchmarking, troubleshooting, |
| 14388 | and for paranoid users. |
| 14389 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 14390 | no-sslv3 |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14391 | This option disables support for SSLv3 when SSL is used to communicate with |
| 14392 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14393 | using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead. |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14394 | |
Emmanuel Hocdet | 6cb2d1e | 2017-03-30 14:43:31 +0200 | [diff] [blame] | 14395 | Supported in default-server: No |
| 14396 | |
Emeric Brun | f9c5c47 | 2012-10-11 15:28:34 +0200 | [diff] [blame] | 14397 | no-tls-tickets |
| 14398 | This setting is only available when support for OpenSSL was built in. It |
| 14399 | disables the stateless session resumption (RFC 5077 TLS Ticket |
| 14400 | extension) and force to use stateful session resumption. Stateless |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14401 | session resumption is more expensive in CPU usage for servers. This option |
| 14402 | is also available on global statement "ssl-default-server-options". |
Lukas Tribus | bdb386d | 2020-03-10 00:56:09 +0100 | [diff] [blame] | 14403 | The TLS ticket mechanism is only used up to TLS 1.2. |
| 14404 | Forward Secrecy is compromised with TLS tickets, unless ticket keys |
| 14405 | are periodically rotated (via reload or by using "tls-ticket-keys"). |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14406 | See also "tls-tickets". |
Emeric Brun | f9c5c47 | 2012-10-11 15:28:34 +0200 | [diff] [blame] | 14407 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 14408 | no-tlsv10 |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14409 | 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] | 14410 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 14411 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14412 | often makes sense to disable it when communicating with local servers. This |
| 14413 | option is also available on global statement "ssl-default-server-options". |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14414 | Use "ssl-min-ver" and "ssl-max-ver" instead. |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 14415 | |
Emmanuel Hocdet | 6cb2d1e | 2017-03-30 14:43:31 +0200 | [diff] [blame] | 14416 | Supported in default-server: No |
| 14417 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 14418 | no-tlsv11 |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14419 | 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] | 14420 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 14421 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14422 | often makes sense to disable it when communicating with local servers. This |
| 14423 | option is also available on global statement "ssl-default-server-options". |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14424 | Use "ssl-min-ver" and "ssl-max-ver" instead. |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 14425 | |
Emmanuel Hocdet | 6cb2d1e | 2017-03-30 14:43:31 +0200 | [diff] [blame] | 14426 | Supported in default-server: No |
| 14427 | |
Emeric Brun | 9b3009b | 2012-10-05 11:55:06 +0200 | [diff] [blame] | 14428 | no-tlsv12 |
Emeric Brun | 8694b9a | 2012-10-05 14:39:07 +0200 | [diff] [blame] | 14429 | 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] | 14430 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 14431 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
Emeric Brun | 2c86cbf | 2014-10-30 15:56:50 +0100 | [diff] [blame] | 14432 | often makes sense to disable it when communicating with local servers. This |
| 14433 | option is also available on global statement "ssl-default-server-options". |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14434 | Use "ssl-min-ver" and "ssl-max-ver" instead. |
Emmanuel Hocdet | 42fb980 | 2017-03-30 19:29:39 +0200 | [diff] [blame] | 14435 | |
| 14436 | Supported in default-server: No |
| 14437 | |
| 14438 | no-tlsv13 |
| 14439 | This option disables support for TLSv1.3 when SSL is used to communicate with |
| 14440 | the server. Note that SSLv2 is disabled in the code and cannot be enabled |
| 14441 | using any configuration option. TLSv1 is more expensive than SSLv3 so it |
| 14442 | often makes sense to disable it when communicating with local servers. This |
| 14443 | option is also available on global statement "ssl-default-server-options". |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14444 | Use "ssl-min-ver" and "ssl-max-ver" instead. |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14445 | |
Emmanuel Hocdet | 6cb2d1e | 2017-03-30 14:43:31 +0200 | [diff] [blame] | 14446 | Supported in default-server: No |
| 14447 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14448 | no-verifyhost |
| 14449 | This option may be used as "server" setting to reset any "verifyhost" |
| 14450 | setting which would have been inherited from "default-server" directive as |
| 14451 | default value. |
| 14452 | It may also be used as "default-server" setting to reset any previous |
| 14453 | "default-server" "verifyhost" setting. |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 14454 | |
Frédéric Lécaille | 1b9423d | 2019-07-04 14:19:06 +0200 | [diff] [blame] | 14455 | no-tfo |
| 14456 | This option may be used as "server" setting to reset any "tfo" |
| 14457 | setting which would have been inherited from "default-server" directive as |
| 14458 | default value. |
| 14459 | It may also be used as "default-server" setting to reset any previous |
| 14460 | "default-server" "tfo" setting. |
| 14461 | |
Simon Horman | fa46168 | 2011-06-25 09:39:49 +0900 | [diff] [blame] | 14462 | non-stick |
| 14463 | Never add connections allocated to this sever to a stick-table. |
| 14464 | This may be used in conjunction with backup to ensure that |
| 14465 | stick-table persistence is disabled for backup servers. |
| 14466 | |
Olivier Houchard | c756600 | 2018-11-20 23:33:50 +0100 | [diff] [blame] | 14467 | npn <protocols> |
| 14468 | This enables the NPN TLS extension and advertises the specified protocol list |
| 14469 | as supported on top of NPN. The protocol list consists in a comma-delimited |
| 14470 | list of protocol names, for instance: "http/1.1,http/1.0" (without quotes). |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 14471 | This requires that the SSL library is built with support for TLS extensions |
Olivier Houchard | c756600 | 2018-11-20 23:33:50 +0100 | [diff] [blame] | 14472 | enabled (check with haproxy -vv). Note that the NPN extension has been |
| 14473 | replaced with the ALPN extension (see the "alpn" keyword), though this one is |
| 14474 | only available starting with OpenSSL 1.0.2. |
| 14475 | |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 14476 | observe <mode> |
| 14477 | This option enables health adjusting based on observing communication with |
| 14478 | the server. By default this functionality is disabled and enabling it also |
| 14479 | requires to enable health checks. There are two supported modes: "layer4" and |
| 14480 | "layer7". In layer4 mode, only successful/unsuccessful tcp connections are |
| 14481 | significant. In layer7, which is only allowed for http proxies, responses |
| 14482 | received from server are verified, like valid/wrong http code, unparsable |
Willy Tarreau | 150d146 | 2012-03-10 08:19:02 +0100 | [diff] [blame] | 14483 | 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] | 14484 | |
| 14485 | See also the "check", "on-error" and "error-limit". |
| 14486 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14487 | on-error <mode> |
Krzysztof Piotr Oledzki | 97f07b8 | 2009-12-15 22:31:24 +0100 | [diff] [blame] | 14488 | Select what should happen when enough consecutive errors are detected. |
| 14489 | Currently, four modes are available: |
| 14490 | - fastinter: force fastinter |
| 14491 | - fail-check: simulate a failed check, also forces fastinter (default) |
| 14492 | - sudden-death: simulate a pre-fatal failed health check, one more failed |
| 14493 | check will mark a server down, forces fastinter |
| 14494 | - mark-down: mark the server immediately down and force fastinter |
| 14495 | |
| 14496 | See also the "check", "observe" and "error-limit". |
| 14497 | |
Simon Horman | e0d1bfb | 2011-06-21 14:34:58 +0900 | [diff] [blame] | 14498 | on-marked-down <action> |
| 14499 | Modify what occurs when a server is marked down. |
| 14500 | Currently one action is available: |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 14501 | - shutdown-sessions: Shutdown peer sessions. When this setting is enabled, |
| 14502 | all connections to the server are immediately terminated when the server |
| 14503 | goes down. It might be used if the health check detects more complex cases |
| 14504 | than a simple connection status, and long timeouts would cause the service |
| 14505 | to remain unresponsive for too long a time. For instance, a health check |
| 14506 | might detect that a database is stuck and that there's no chance to reuse |
| 14507 | existing connections anymore. Connections killed this way are logged with |
| 14508 | a 'D' termination code (for "Down"). |
Simon Horman | e0d1bfb | 2011-06-21 14:34:58 +0900 | [diff] [blame] | 14509 | |
| 14510 | Actions are disabled by default |
| 14511 | |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 14512 | on-marked-up <action> |
| 14513 | Modify what occurs when a server is marked up. |
| 14514 | Currently one action is available: |
| 14515 | - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is |
| 14516 | done only if the server is not in backup state and if it is not disabled |
| 14517 | (it must have an effective weight > 0). This can be used sometimes to force |
| 14518 | an active server to take all the traffic back after recovery when dealing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14519 | with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble |
| 14520 | than it tries to solve (e.g. incomplete transactions), so use this feature |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 14521 | with extreme care. Sessions killed because a server comes up are logged |
| 14522 | with an 'U' termination code (for "Up"). |
| 14523 | |
| 14524 | Actions are disabled by default |
| 14525 | |
Willy Tarreau | 2f3f4d3 | 2020-07-01 07:43:51 +0200 | [diff] [blame] | 14526 | pool-low-conn <max> |
| 14527 | Set a low threshold on the number of idling connections for a server, below |
| 14528 | which a thread will not try to steal a connection from another thread. This |
| 14529 | can be useful to improve CPU usage patterns in scenarios involving many very |
| 14530 | fast servers, in order to ensure all threads will keep a few idle connections |
| 14531 | all the time instead of letting them accumulate over one thread and migrating |
| 14532 | them from thread to thread. Typical values of twice the number of threads |
| 14533 | seem to show very good performance already with sub-millisecond response |
| 14534 | times. The default is zero, indicating that any idle connection can be used |
| 14535 | at any time. It is the recommended setting for normal use. This only applies |
| 14536 | to connections that can be shared according to the same principles as those |
Willy Tarreau | 0784db8 | 2021-02-19 11:45:22 +0100 | [diff] [blame] | 14537 | applying to "http-reuse". In case connection sharing between threads would |
| 14538 | be disabled via "tune.idle-pool.shared", it can become very important to use |
| 14539 | this setting to make sure each thread always has a few connections, or the |
| 14540 | connection reuse rate will decrease as thread count increases. |
Willy Tarreau | 2f3f4d3 | 2020-07-01 07:43:51 +0200 | [diff] [blame] | 14541 | |
Olivier Houchard | 006e310 | 2018-12-10 18:30:32 +0100 | [diff] [blame] | 14542 | pool-max-conn <max> |
| 14543 | Set the maximum number of idling connections for a server. -1 means unlimited |
| 14544 | connections, 0 means no idle connections. The default is -1. When idle |
| 14545 | connections are enabled, orphaned idle connections which do not belong to any |
| 14546 | client session anymore are moved to a dedicated pool so that they remain |
| 14547 | usable by future clients. This only applies to connections that can be shared |
| 14548 | according to the same principles as those applying to "http-reuse". |
| 14549 | |
Olivier Houchard | b7b3faa | 2018-12-14 18:15:36 +0100 | [diff] [blame] | 14550 | pool-purge-delay <delay> |
| 14551 | Sets the delay to start purging idle connections. Each <delay> interval, half |
Olivier Houchard | a56eebf | 2019-03-19 16:44:02 +0100 | [diff] [blame] | 14552 | of the idle connections are closed. 0 means we don't keep any idle connection. |
Willy Tarreau | fb55365 | 2019-06-04 14:06:31 +0200 | [diff] [blame] | 14553 | The default is 5s. |
Olivier Houchard | b7b3faa | 2018-12-14 18:15:36 +0100 | [diff] [blame] | 14554 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14555 | port <port> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14556 | Using the "port" parameter, it becomes possible to use a different port to |
William Dauchy | 4858fb2 | 2021-02-03 22:30:09 +0100 | [diff] [blame] | 14557 | send health-checks or to probe the agent-check. On some servers, it may be |
| 14558 | desirable to dedicate a port to a specific component able to perform complex |
| 14559 | tests which are more suitable to health-checks than the application. It is |
| 14560 | common to run a simple script in inetd for instance. This parameter is |
| 14561 | ignored if the "check" parameter is not set. See also the "addr" parameter. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14562 | |
Christopher Faulet | 8ed0a3e | 2018-04-10 14:45:45 +0200 | [diff] [blame] | 14563 | proto <name> |
Christopher Faulet | 8ed0a3e | 2018-04-10 14:45:45 +0200 | [diff] [blame] | 14564 | Forces the multiplexer's protocol to use for the outgoing connections to this |
| 14565 | server. It must be compatible with the mode of the backend (TCP or HTTP). It |
| 14566 | must also be usable on the backend side. The list of available protocols is |
Christopher Faulet | 982e17d | 2021-03-26 14:44:18 +0100 | [diff] [blame] | 14567 | reported in haproxy -vv.The protocols properties are reported : the mode |
| 14568 | (TCP/HTTP), the side (FE/BE), the mux name and its flags. |
| 14569 | |
| 14570 | Some protocols report errors on aborts (flag=CLEAN_ABRT). Some others are |
| 14571 | subject to the head-of-line blocking on server side (flag=HOL_RISK). Finally |
| 14572 | some protocols don't support upgrades (flag=NO_UPG). The HTX compatibility is |
| 14573 | also reported (flag=HTX). |
| 14574 | |
| 14575 | Here are the protocols that may be used as argument to a "proto" directive on |
| 14576 | a server line : |
| 14577 | |
| 14578 | h2 : mode=HTTP side=FE|BE mux=H2 flags=HTX|CLEAN_ABRT|HOL_RISK|NO_UPG |
| 14579 | fcgi : mode=HTTP side=BE mux=FCGI flags=HTX|HOL_RISK|NO_UPG |
| 14580 | h1 : mode=HTTP side=FE|BE mux=H1 flags=HTX|NO_UPG |
| 14581 | none : mode=TCP side=FE|BE mux=PASS flags=NO_UPG |
| 14582 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 14583 | Idea behind this option is to bypass the selection of the best multiplexer's |
Christopher Faulet | 8ed0a3e | 2018-04-10 14:45:45 +0200 | [diff] [blame] | 14584 | protocol for all connections established to this server. |
| 14585 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14586 | redir <prefix> |
| 14587 | The "redir" parameter enables the redirection mode for all GET and HEAD |
| 14588 | requests addressing this server. This means that instead of having HAProxy |
| 14589 | forward the request to the server, it will send an "HTTP 302" response with |
| 14590 | the "Location" header composed of this prefix immediately followed by the |
| 14591 | requested URI beginning at the leading '/' of the path component. That means |
| 14592 | that no trailing slash should be used after <prefix>. All invalid requests |
| 14593 | will be rejected, and all non-GET or HEAD requests will be normally served by |
| 14594 | 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] | 14595 | mangling nor cookie insertion is possible in the response. However, cookies in |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14596 | requests are still analyzed, making this solution completely usable to direct |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14597 | users to a remote location in case of local disaster. Main use consists in |
| 14598 | increasing bandwidth for static servers by having the clients directly |
| 14599 | connect to them. Note: never use a relative location here, it would cause a |
| 14600 | loop between the client and HAProxy! |
| 14601 | |
| 14602 | Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check |
| 14603 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14604 | rise <count> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14605 | The "rise" parameter states that a server will be considered as operational |
| 14606 | after <count> consecutive successful health checks. This value defaults to 2 |
| 14607 | if unspecified. See also the "check", "inter" and "fall" parameters. |
| 14608 | |
Baptiste Assmann | 8e2d943 | 2018-06-22 15:04:43 +0200 | [diff] [blame] | 14609 | resolve-opts <option>,<option>,... |
| 14610 | Comma separated list of options to apply to DNS resolution linked to this |
| 14611 | server. |
| 14612 | |
| 14613 | Available options: |
| 14614 | |
| 14615 | * allow-dup-ip |
| 14616 | By default, HAProxy prevents IP address duplication in a backend when DNS |
| 14617 | resolution at runtime is in operation. |
| 14618 | That said, for some cases, it makes sense that two servers (in the same |
| 14619 | backend, being resolved by the same FQDN) have the same IP address. |
| 14620 | For such case, simply enable this option. |
| 14621 | This is the opposite of prevent-dup-ip. |
| 14622 | |
Daniel Corbett | f871691 | 2019-11-17 09:48:56 -0500 | [diff] [blame] | 14623 | * ignore-weight |
| 14624 | Ignore any weight that is set within an SRV record. This is useful when |
| 14625 | you would like to control the weights using an alternate method, such as |
| 14626 | using an "agent-check" or through the runtime api. |
| 14627 | |
Baptiste Assmann | 8e2d943 | 2018-06-22 15:04:43 +0200 | [diff] [blame] | 14628 | * prevent-dup-ip |
| 14629 | Ensure HAProxy's default behavior is enforced on a server: prevent re-using |
| 14630 | an IP address already set to a server in the same backend and sharing the |
| 14631 | same fqdn. |
| 14632 | This is the opposite of allow-dup-ip. |
| 14633 | |
| 14634 | Example: |
| 14635 | backend b_myapp |
| 14636 | default-server init-addr none resolvers dns |
| 14637 | server s1 myapp.example.com:80 check resolve-opts allow-dup-ip |
| 14638 | server s2 myapp.example.com:81 check resolve-opts allow-dup-ip |
| 14639 | |
| 14640 | With the option allow-dup-ip set: |
| 14641 | * if the nameserver returns a single IP address, then both servers will use |
| 14642 | it |
| 14643 | * If the nameserver returns 2 IP addresses, then each server will pick up a |
| 14644 | different address |
| 14645 | |
| 14646 | Default value: not set |
| 14647 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14648 | resolve-prefer <family> |
| 14649 | When DNS resolution is enabled for a server and multiple IP addresses from |
| 14650 | different families are returned, HAProxy will prefer using an IP address |
| 14651 | from the family mentioned in the "resolve-prefer" parameter. |
| 14652 | Available families: "ipv4" and "ipv6" |
| 14653 | |
Baptiste Assmann | c4aabae | 2015-08-04 22:43:06 +0200 | [diff] [blame] | 14654 | Default value: ipv6 |
| 14655 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 14656 | Example: |
| 14657 | |
| 14658 | server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6 |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14659 | |
Thierry Fournier | ac88cfe | 2016-02-17 22:05:30 +0100 | [diff] [blame] | 14660 | resolve-net <network>[,<network[,...]] |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 14661 | This option prioritizes the choice of an ip address matching a network. This is |
Thierry Fournier | ac88cfe | 2016-02-17 22:05:30 +0100 | [diff] [blame] | 14662 | useful with clouds to prefer a local ip. In some cases, a cloud high |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 14663 | availability service can be announced with many ip addresses on many |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14664 | different datacenters. The latency between datacenter is not negligible, so |
| 14665 | this patch permits to prefer a local datacenter. If no address matches the |
Thierry Fournier | ac88cfe | 2016-02-17 22:05:30 +0100 | [diff] [blame] | 14666 | configured network, another address is selected. |
| 14667 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 14668 | Example: |
| 14669 | |
| 14670 | server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8 |
Thierry Fournier | ac88cfe | 2016-02-17 22:05:30 +0100 | [diff] [blame] | 14671 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14672 | resolvers <id> |
| 14673 | Points to an existing "resolvers" section to resolve current server's |
| 14674 | hostname. |
| 14675 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 14676 | Example: |
| 14677 | |
| 14678 | server s1 app1.domain.com:80 check resolvers mydns |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14679 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 14680 | See also section 5.3 |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14681 | |
Willy Tarreau | 5ab04ec | 2011-03-20 10:32:26 +0100 | [diff] [blame] | 14682 | send-proxy |
| 14683 | The "send-proxy" parameter enforces use of the PROXY protocol over any |
| 14684 | connection established to this server. The PROXY protocol informs the other |
| 14685 | end about the layer 3/4 addresses of the incoming connection, so that it can |
| 14686 | know the client's address or the public address it accessed to, whatever the |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 14687 | upper layer protocol. For connections accepted by an "accept-proxy" or |
| 14688 | "accept-netscaler-cip" listener, the advertised address will be used. Only |
| 14689 | TCPv4 and TCPv6 address families are supported. Other families such as |
| 14690 | Unix sockets, will report an UNKNOWN family. Servers using this option can |
| 14691 | fully be chained to another instance of haproxy listening with an |
| 14692 | "accept-proxy" setting. This setting must not be used if the server isn't |
| 14693 | aware of the protocol. When health checks are sent to the server, the PROXY |
| 14694 | protocol is automatically used when this option is set, unless there is an |
| 14695 | explicit "port" or "addr" directive, in which case an explicit |
| 14696 | "check-send-proxy" directive would also be needed to use the PROXY protocol. |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14697 | See also the "no-send-proxy" option of this section and "accept-proxy" and |
| 14698 | "accept-netscaler-cip" option of the "bind" keyword. |
Willy Tarreau | 5ab04ec | 2011-03-20 10:32:26 +0100 | [diff] [blame] | 14699 | |
David S | afb7683 | 2014-05-08 23:42:08 -0400 | [diff] [blame] | 14700 | send-proxy-v2 |
| 14701 | The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2 |
| 14702 | over any connection established to this server. The PROXY protocol informs |
| 14703 | the other end about the layer 3/4 addresses of the incoming connection, so |
| 14704 | that it can know the client's address or the public address it accessed to, |
Emmanuel Hocdet | 404d978 | 2017-10-24 10:55:14 +0200 | [diff] [blame] | 14705 | whatever the upper layer protocol. It also send ALPN information if an alpn |
| 14706 | have been negotiated. This setting must not be used if the server isn't aware |
| 14707 | of this version of the protocol. See also the "no-send-proxy-v2" option of |
| 14708 | this section and send-proxy" option of the "bind" keyword. |
David S | afb7683 | 2014-05-08 23:42:08 -0400 | [diff] [blame] | 14709 | |
Emmanuel Hocdet | f643b80 | 2018-02-01 15:20:32 +0100 | [diff] [blame] | 14710 | proxy-v2-options <option>[,<option>]* |
Tim Duesterhus | cf6e0c8 | 2020-03-13 12:34:24 +0100 | [diff] [blame] | 14711 | The "proxy-v2-options" parameter add options to send in PROXY protocol |
| 14712 | version 2 when "send-proxy-v2" is used. Options available are: |
| 14713 | |
| 14714 | - ssl : See also "send-proxy-v2-ssl". |
| 14715 | - cert-cn : See also "send-proxy-v2-ssl-cn". |
| 14716 | - ssl-cipher: Name of the used cipher. |
| 14717 | - cert-sig : Signature algorithm of the used certificate. |
| 14718 | - cert-key : Key algorithm of the used certificate |
| 14719 | - authority : Host name value passed by the client (only SNI from a TLS |
| 14720 | connection is supported). |
| 14721 | - crc32c : Checksum of the PROXYv2 header. |
| 14722 | - unique-id : Send a unique ID generated using the frontend's |
| 14723 | "unique-id-format" within the PROXYv2 header. |
| 14724 | This unique-id is primarily meant for "mode tcp". It can |
| 14725 | lead to unexpected results in "mode http", because the |
| 14726 | generated unique ID is also used for the first HTTP request |
| 14727 | within a Keep-Alive connection. |
Emmanuel Hocdet | f643b80 | 2018-02-01 15:20:32 +0100 | [diff] [blame] | 14728 | |
David S | afb7683 | 2014-05-08 23:42:08 -0400 | [diff] [blame] | 14729 | send-proxy-v2-ssl |
| 14730 | The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version |
| 14731 | 2 over any connection established to this server. The PROXY protocol informs |
| 14732 | the other end about the layer 3/4 addresses of the incoming connection, so |
| 14733 | that it can know the client's address or the public address it accessed to, |
| 14734 | whatever the upper layer protocol. In addition, the SSL information extension |
| 14735 | of the PROXY protocol is added to the PROXY protocol header. This setting |
| 14736 | must not be used if the server isn't aware of this version of the protocol. |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14737 | See also the "no-send-proxy-v2-ssl" option of this section and the |
| 14738 | "send-proxy-v2" option of the "bind" keyword. |
David S | afb7683 | 2014-05-08 23:42:08 -0400 | [diff] [blame] | 14739 | |
| 14740 | send-proxy-v2-ssl-cn |
| 14741 | The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version |
| 14742 | 2 over any connection established to this server. The PROXY protocol informs |
| 14743 | the other end about the layer 3/4 addresses of the incoming connection, so |
| 14744 | that it can know the client's address or the public address it accessed to, |
| 14745 | whatever the upper layer protocol. In addition, the SSL information extension |
| 14746 | of the PROXY protocol, along along with the Common Name from the subject of |
| 14747 | the client certificate (if any), is added to the PROXY protocol header. This |
| 14748 | setting must not be used if the server isn't aware of this version of the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14749 | protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and |
| 14750 | the "send-proxy-v2" option of the "bind" keyword. |
David S | afb7683 | 2014-05-08 23:42:08 -0400 | [diff] [blame] | 14751 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14752 | slowstart <start_time_in_ms> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14753 | The "slowstart" parameter for a server accepts a value in milliseconds which |
| 14754 | indicates after how long a server which has just come back up will run at |
| 14755 | full speed. Just as with every other time-based parameter, it can be entered |
| 14756 | in any other explicit unit among { us, ms, s, m, h, d }. The speed grows |
| 14757 | linearly from 0 to 100% during this time. The limitation applies to two |
| 14758 | parameters : |
| 14759 | |
| 14760 | - maxconn: the number of connections accepted by the server will grow from 1 |
| 14761 | to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn). |
| 14762 | |
| 14763 | - weight: when the backend uses a dynamic weighted algorithm, the weight |
| 14764 | grows linearly from 1 to 100%. In this case, the weight is updated at every |
| 14765 | health-check. For this reason, it is important that the "inter" parameter |
| 14766 | is smaller than the "slowstart", in order to maximize the number of steps. |
| 14767 | |
| 14768 | The slowstart never applies when haproxy starts, otherwise it would cause |
| 14769 | trouble to running servers. It only applies when a server has been previously |
| 14770 | seen as failed. |
| 14771 | |
Willy Tarreau | 732eac4 | 2015-07-09 11:40:25 +0200 | [diff] [blame] | 14772 | sni <expression> |
| 14773 | The "sni" parameter evaluates the sample fetch expression, converts it to a |
| 14774 | string and uses the result as the host name sent in the SNI TLS extension to |
| 14775 | the server. A typical use case is to send the SNI received from the client in |
| 14776 | a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the |
Willy Tarreau | 2ab8867 | 2017-07-05 18:23:03 +0200 | [diff] [blame] | 14777 | expression, though alternatives such as req.hdr(host) can also make sense. If |
| 14778 | "verify required" is set (which is the recommended setting), the resulting |
Willy Tarreau | ad92a9a | 2017-07-28 11:38:41 +0200 | [diff] [blame] | 14779 | name will also be matched against the server certificate's names. See the |
Jérôme Magnin | b36a6d2 | 2018-12-09 16:03:40 +0100 | [diff] [blame] | 14780 | "verify" directive for more details. If you want to set a SNI for health |
| 14781 | checks, see the "check-sni" directive for more details. |
Willy Tarreau | 732eac4 | 2015-07-09 11:40:25 +0200 | [diff] [blame] | 14782 | |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 14783 | source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
Willy Tarreau | bce7088 | 2009-09-07 11:51:47 +0200 | [diff] [blame] | 14784 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ] |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 14785 | source <addr>[:<pl>[-<ph>]] [interface <name>] ... |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14786 | The "source" parameter sets the source address which will be used when |
| 14787 | connecting to the server. It follows the exact same parameters and principle |
| 14788 | as the backend "source" keyword, except that it only applies to the server |
| 14789 | referencing it. Please consult the "source" keyword for details. |
| 14790 | |
Willy Tarreau | c6f4ce8 | 2009-06-10 11:09:37 +0200 | [diff] [blame] | 14791 | Additionally, the "source" statement on a server line allows one to specify a |
| 14792 | source port range by indicating the lower and higher bounds delimited by a |
| 14793 | dash ('-'). Some operating systems might require a valid IP address when a |
| 14794 | source port range is specified. It is permitted to have the same IP/range for |
| 14795 | several servers. Doing so makes it possible to bypass the maximum of 64k |
| 14796 | total concurrent connections. The limit will then reach 64k connections per |
| 14797 | server. |
| 14798 | |
Lukas Tribus | 7d56c6d | 2016-09-13 09:51:15 +0000 | [diff] [blame] | 14799 | Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections |
| 14800 | specifying the source address without port(s). |
| 14801 | |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14802 | ssl |
Willy Tarreau | 44f6539 | 2013-06-25 07:56:20 +0200 | [diff] [blame] | 14803 | This option enables SSL ciphering on outgoing connections to the server. It |
| 14804 | is critical to verify server certificates using "verify" when using SSL to |
| 14805 | connect to servers, otherwise the communication is prone to trivial man in |
| 14806 | the-middle attacks rendering SSL useless. When this option is used, health |
| 14807 | checks are automatically sent in SSL too unless there is a "port" or an |
| 14808 | "addr" directive indicating the check should be sent to a different location. |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14809 | See the "no-ssl" to disable "ssl" option and "check-ssl" option to force |
| 14810 | SSL health checks. |
Willy Tarreau | 763a95b | 2012-10-04 23:15:39 +0200 | [diff] [blame] | 14811 | |
Emmanuel Hocdet | e1c722b | 2017-03-31 15:02:54 +0200 | [diff] [blame] | 14812 | ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ] |
| 14813 | This option enforces use of <version> or lower when SSL is used to communicate |
| 14814 | with the server. This option is also available on global statement |
| 14815 | "ssl-default-server-options". See also "ssl-min-ver". |
| 14816 | |
| 14817 | ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ] |
| 14818 | This option enforces use of <version> or upper when SSL is used to communicate |
| 14819 | with the server. This option is also available on global statement |
| 14820 | "ssl-default-server-options". See also "ssl-max-ver". |
| 14821 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14822 | ssl-reuse |
| 14823 | This option may be used as "server" setting to reset any "no-ssl-reuse" |
| 14824 | setting which would have been inherited from "default-server" directive as |
| 14825 | default value. |
| 14826 | It may also be used as "default-server" setting to reset any previous |
| 14827 | "default-server" "no-ssl-reuse" setting. |
| 14828 | |
| 14829 | stick |
| 14830 | This option may be used as "server" setting to reset any "non-stick" |
| 14831 | setting which would have been inherited from "default-server" directive as |
| 14832 | default value. |
| 14833 | It may also be used as "default-server" setting to reset any previous |
| 14834 | "default-server" "non-stick" setting. |
Willy Tarreau | a0ee1d0 | 2012-09-10 09:01:23 +0200 | [diff] [blame] | 14835 | |
Alexander Liu | 2a54bb7 | 2019-05-22 19:44:48 +0800 | [diff] [blame] | 14836 | socks4 <addr>:<port> |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 14837 | This option enables upstream socks4 tunnel for outgoing connections to the |
Alexander Liu | 2a54bb7 | 2019-05-22 19:44:48 +0800 | [diff] [blame] | 14838 | server. Using this option won't force the health check to go via socks4 by |
| 14839 | default. You will have to use the keyword "check-via-socks4" to enable it. |
| 14840 | |
Willy Tarreau | 163d462 | 2015-10-13 16:16:41 +0200 | [diff] [blame] | 14841 | tcp-ut <delay> |
| 14842 | Sets the TCP User Timeout for all outgoing connections to this server. This |
| 14843 | option is available on Linux since version 2.6.37. It allows haproxy to |
| 14844 | configure a timeout for sockets which contain data not receiving an |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14845 | acknowledgment for the configured delay. This is especially useful on |
Willy Tarreau | 163d462 | 2015-10-13 16:16:41 +0200 | [diff] [blame] | 14846 | long-lived connections experiencing long idle periods such as remote |
| 14847 | terminals or database connection pools, where the client and server timeouts |
| 14848 | must remain high to allow a long period of idle, but where it is important to |
| 14849 | detect that the server has disappeared in order to release all resources |
| 14850 | associated with its connection (and the client's session). One typical use |
| 14851 | case is also to force dead server connections to die when health checks are |
| 14852 | too slow or during a soft reload since health checks are then disabled. The |
| 14853 | argument is a delay expressed in milliseconds by default. This only works for |
| 14854 | regular TCP connections, and is ignored for other protocols. |
| 14855 | |
Willy Tarreau | 034c88c | 2017-01-23 23:36:45 +0100 | [diff] [blame] | 14856 | tfo |
| 14857 | This option enables using TCP fast open when connecting to servers, on |
| 14858 | systems that support it (currently only the Linux kernel >= 4.11). |
| 14859 | See the "tfo" bind option for more information about TCP fast open. |
| 14860 | Please note that when using tfo, you should also use the "conn-failure", |
| 14861 | "empty-response" and "response-timeout" keywords for "retry-on", or haproxy |
Frédéric Lécaille | 1b9423d | 2019-07-04 14:19:06 +0200 | [diff] [blame] | 14862 | won't be able to retry the connection on failure. See also "no-tfo". |
Willy Tarreau | 034c88c | 2017-01-23 23:36:45 +0100 | [diff] [blame] | 14863 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14864 | track [<proxy>/]<server> |
Willy Tarreau | 3209123 | 2014-05-16 13:52:00 +0200 | [diff] [blame] | 14865 | This option enables ability to set the current state of the server by tracking |
| 14866 | another one. It is possible to track a server which itself tracks another |
| 14867 | server, provided that at the end of the chain, a server has health checks |
| 14868 | enabled. If <proxy> is omitted the current one is used. If disable-on-404 is |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14869 | used, it has to be enabled on both proxies. |
| 14870 | |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14871 | tls-tickets |
| 14872 | This option may be used as "server" setting to reset any "no-tls-tickets" |
| 14873 | setting which would have been inherited from "default-server" directive as |
| 14874 | default value. |
Lukas Tribus | bdb386d | 2020-03-10 00:56:09 +0100 | [diff] [blame] | 14875 | The TLS ticket mechanism is only used up to TLS 1.2. |
| 14876 | Forward Secrecy is compromised with TLS tickets, unless ticket keys |
| 14877 | are periodically rotated (via reload or by using "tls-ticket-keys"). |
Frédéric Lécaille | d237627 | 2017-03-21 18:52:12 +0100 | [diff] [blame] | 14878 | It may also be used as "default-server" setting to reset any previous |
Bjoern Jacke | 5ab7eb6 | 2020-02-13 14:16:16 +0100 | [diff] [blame] | 14879 | "default-server" "no-tls-tickets" setting. |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14880 | |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 14881 | verify [none|required] |
| 14882 | 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] | 14883 | to 'none', server certificate is not verified. In the other case, The |
Willy Tarreau | ad92a9a | 2017-07-28 11:38:41 +0200 | [diff] [blame] | 14884 | certificate provided by the server is verified using CAs from 'ca-file' and |
| 14885 | optional CRLs from 'crl-file' after having checked that the names provided in |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14886 | the certificate's subject and subjectAlternateNames attributes match either |
Willy Tarreau | ad92a9a | 2017-07-28 11:38:41 +0200 | [diff] [blame] | 14887 | the name passed using the "sni" directive, or if not provided, the static |
| 14888 | host name passed using the "verifyhost" directive. When no name is found, the |
| 14889 | certificate's names are ignored. For this reason, without SNI it's important |
| 14890 | to use "verifyhost". On verification failure the handshake is aborted. It is |
| 14891 | critically important to verify server certificates when using SSL to connect |
| 14892 | to servers, otherwise the communication is prone to trivial man-in-the-middle |
| 14893 | attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in |
| 14894 | the global section, "verify" is set to "required" by default. |
Emeric Brun | ef42d92 | 2012-10-11 16:11:36 +0200 | [diff] [blame] | 14895 | |
Evan Broder | be55431 | 2013-06-27 00:05:25 -0700 | [diff] [blame] | 14896 | verifyhost <hostname> |
| 14897 | This setting is only available when support for OpenSSL was built in, and |
Willy Tarreau | ad92a9a | 2017-07-28 11:38:41 +0200 | [diff] [blame] | 14898 | only takes effect if 'verify required' is also specified. This directive sets |
| 14899 | a default static hostname to check the server's certificate against when no |
| 14900 | SNI was used to connect to the server. If SNI is not used, this is the only |
| 14901 | way to enable hostname verification. This static hostname, when set, will |
| 14902 | also be used for health checks (which cannot provide an SNI value). If none |
| 14903 | of the hostnames in the certificate match the specified hostname, the |
| 14904 | handshake is aborted. The hostnames in the server-provided certificate may |
| 14905 | include wildcards. See also "verify", "sni" and "no-verifyhost" options. |
Evan Broder | be55431 | 2013-06-27 00:05:25 -0700 | [diff] [blame] | 14906 | |
Krzysztof Piotr Oledzki | c53601c | 2010-01-06 10:50:42 +0100 | [diff] [blame] | 14907 | weight <weight> |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14908 | The "weight" parameter is used to adjust the server's weight relative to |
| 14909 | other servers. All servers will receive a load proportional to their weight |
| 14910 | 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] | 14911 | load. The default weight is 1, and the maximal value is 256. A value of 0 |
| 14912 | means the server will not participate in load-balancing but will still accept |
| 14913 | persistent connections. If this parameter is used to distribute the load |
| 14914 | according to server's capacity, it is recommended to start with values which |
| 14915 | can both grow and shrink, for instance between 10 and 100 to leave enough |
| 14916 | room above and below for later adjustments. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 14917 | |
| 14918 | |
Cyril Bonté | 46175dd | 2015-07-02 22:45:32 +0200 | [diff] [blame] | 14919 | 5.3. Server IP address resolution using DNS |
| 14920 | ------------------------------------------- |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14921 | |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 14922 | HAProxy allows using a host name on the server line to retrieve its IP address |
| 14923 | using name servers. By default, HAProxy resolves the name when parsing the |
Thayne McCombs | cdbcca9 | 2021-01-07 21:24:41 -0700 | [diff] [blame] | 14924 | configuration file, at startup and cache the result for the process's life. |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14925 | This is not sufficient in some cases, such as in Amazon where a server's IP |
| 14926 | can change after a reboot or an ELB Virtual IP can change based on current |
| 14927 | workload. |
| 14928 | This chapter describes how HAProxy can be configured to process server's name |
| 14929 | resolution at run time. |
| 14930 | Whether run time server name resolution has been enable or not, HAProxy will |
| 14931 | carry on doing the first resolution when parsing the configuration. |
| 14932 | |
| 14933 | |
Cyril Bonté | 46175dd | 2015-07-02 22:45:32 +0200 | [diff] [blame] | 14934 | 5.3.1. Global overview |
| 14935 | ---------------------- |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14936 | |
| 14937 | As we've seen in introduction, name resolution in HAProxy occurs at two |
| 14938 | different steps of the process life: |
| 14939 | |
| 14940 | 1. when starting up, HAProxy parses the server line definition and matches a |
| 14941 | host name. It uses libc functions to get the host name resolved. This |
| 14942 | resolution relies on /etc/resolv.conf file. |
| 14943 | |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14944 | 2. at run time, HAProxy performs periodically name resolutions for servers |
| 14945 | requiring DNS resolutions. |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14946 | |
| 14947 | A few other events can trigger a name resolution at run time: |
| 14948 | - when a server's health check ends up in a connection timeout: this may be |
| 14949 | because the server has a new IP address. So we need to trigger a name |
| 14950 | resolution to know this new IP. |
| 14951 | |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14952 | When using resolvers, the server name can either be a hostname, or a SRV label. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 14953 | HAProxy considers anything that starts with an underscore as a SRV label. If a |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14954 | SRV label is specified, then the corresponding SRV records will be retrieved |
| 14955 | from the DNS server, and the provided hostnames will be used. The SRV label |
| 14956 | will be checked periodically, and if any server are added or removed, haproxy |
| 14957 | will automatically do the same. |
Olivier Houchard | ecfa18d | 2017-08-07 17:30:03 +0200 | [diff] [blame] | 14958 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14959 | A few things important to notice: |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 14960 | - all the name servers are queried in the meantime. HAProxy will process the |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14961 | first valid response. |
| 14962 | |
| 14963 | - a resolution is considered as invalid (NX, timeout, refused), when all the |
| 14964 | servers return an error. |
| 14965 | |
| 14966 | |
Cyril Bonté | 46175dd | 2015-07-02 22:45:32 +0200 | [diff] [blame] | 14967 | 5.3.2. The resolvers section |
| 14968 | ---------------------------- |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14969 | |
| 14970 | This section is dedicated to host information related to name resolution in |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14971 | HAProxy. There can be as many as resolvers section as needed. Each section can |
| 14972 | contain many name servers. |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 14973 | |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 14974 | When multiple name servers are configured in a resolvers section, then HAProxy |
| 14975 | uses the first valid response. In case of invalid responses, only the last one |
| 14976 | is treated. Purpose is to give the chance to a slow server to deliver a valid |
| 14977 | answer after a fast faulty or outdated server. |
| 14978 | |
| 14979 | When each server returns a different error type, then only the last error is |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14980 | used by HAProxy. The following processing is applied on this error: |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 14981 | |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14982 | 1. HAProxy retries the same DNS query with a new query type. The A queries are |
| 14983 | switch to AAAA or the opposite. SRV queries are not concerned here. Timeout |
| 14984 | errors are also excluded. |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 14985 | |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14986 | 2. When the fallback on the query type was done (or not applicable), HAProxy |
| 14987 | retries the original DNS query, with the preferred query type. |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 14988 | |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14989 | 3. HAProxy retries previous steps <resolve_retires> times. If no valid |
| 14990 | response is received after that, it stops the DNS resolution and reports |
| 14991 | the error. |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 14992 | |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 14993 | For example, with 2 name servers configured in a resolvers section, the |
| 14994 | following scenarios are possible: |
| 14995 | |
| 14996 | - First response is valid and is applied directly, second response is |
| 14997 | ignored |
| 14998 | |
| 14999 | - First response is invalid and second one is valid, then second response is |
| 15000 | applied |
| 15001 | |
| 15002 | - First response is a NX domain and second one a truncated response, then |
| 15003 | HAProxy retries the query with a new type |
| 15004 | |
| 15005 | - First response is a NX domain and second one is a timeout, then HAProxy |
| 15006 | retries the query with a new type |
| 15007 | |
| 15008 | - Query timed out for both name servers, then HAProxy retries it with the |
| 15009 | same query type |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 15010 | |
Olivier Houchard | a8c6db8 | 2017-07-06 18:46:47 +0200 | [diff] [blame] | 15011 | As a DNS server may not answer all the IPs in one DNS request, haproxy keeps |
| 15012 | a cache of previous answers, an answer will be considered obsolete after |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 15013 | <hold obsolete> seconds without the IP returned. |
Olivier Houchard | a8c6db8 | 2017-07-06 18:46:47 +0200 | [diff] [blame] | 15014 | |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 15015 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15016 | resolvers <resolvers id> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15017 | Creates a new name server list labeled <resolvers id> |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15018 | |
| 15019 | A resolvers section accept the following parameters: |
| 15020 | |
Baptiste Assmann | 2af08fe | 2017-08-14 00:13:01 +0200 | [diff] [blame] | 15021 | accepted_payload_size <nb> |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15022 | Defines the maximum payload size accepted by HAProxy and announced to all the |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 15023 | name servers configured in this resolvers section. |
Baptiste Assmann | 2af08fe | 2017-08-14 00:13:01 +0200 | [diff] [blame] | 15024 | <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined |
| 15025 | by RFC 6891) |
| 15026 | |
Emeric Brun | 4c75195 | 2021-03-08 16:41:29 +0100 | [diff] [blame] | 15027 | Note: the maximum allowed value is 65535. Recommended value for UDP is |
| 15028 | 4096 and it is not recommended to exceed 8192 except if you are sure |
| 15029 | that your system and network can handle this (over 65507 makes no sense |
| 15030 | since is the maximum UDP payload size). If you are using only TCP |
| 15031 | nameservers to handle huge DNS responses, you should put this value |
| 15032 | to the max: 65535. |
Baptiste Assmann | 9d8dbbc | 2017-08-18 23:35:08 +0200 | [diff] [blame] | 15033 | |
Emeric Brun | c8f3e45 | 2021-04-07 16:04:54 +0200 | [diff] [blame] | 15034 | nameserver <name> <address>[:port] [param*] |
| 15035 | Used to configure a nameserver. <name> of the nameserver should ne unique. |
| 15036 | By default the <address> is considered of type datagram. This means if an |
| 15037 | IPv4 or IPv6 is configured without special address prefixes (paragraph 11.) |
| 15038 | the UDP protocol will be used. If an stream protocol address prefix is used, |
| 15039 | the nameserver will be considered as a stream server (TCP for instance) and |
| 15040 | "server" parameters found in 5.2 paragraph which are relevant for DNS |
| 15041 | resolving will be considered. Note: currently, in TCP mode, 4 queries are |
| 15042 | pipelined on the same connections. A batch of idle connections are removed |
| 15043 | every 5 seconds. "maxconn" can be configured to limit the amount of those |
Emeric Brun | 56fc5d9 | 2021-02-12 20:05:45 +0100 | [diff] [blame] | 15044 | concurrent connections and TLS should also usable if the server supports. |
| 15045 | |
Ben Draut | 44e609b | 2018-05-29 15:40:08 -0600 | [diff] [blame] | 15046 | parse-resolv-conf |
| 15047 | Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers |
| 15048 | list. Ordered as if each nameserver in /etc/resolv.conf was individually |
| 15049 | placed in the resolvers section in place of this directive. |
| 15050 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15051 | hold <status> <period> |
| 15052 | Defines <period> during which the last name resolution should be kept based |
| 15053 | on last resolution <status> |
Baptiste Assmann | 987e16d | 2016-11-02 22:23:31 +0100 | [diff] [blame] | 15054 | <status> : last name resolution status. Acceptable values are "nx", |
Olivier Houchard | a8c6db8 | 2017-07-06 18:46:47 +0200 | [diff] [blame] | 15055 | "other", "refused", "timeout", "valid", "obsolete". |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15056 | <period> : interval between two successive name resolution when the last |
| 15057 | answer was in <status>. It follows the HAProxy time format. |
| 15058 | <period> is in milliseconds by default. |
| 15059 | |
Baptiste Assmann | 686408b | 2017-08-18 10:15:42 +0200 | [diff] [blame] | 15060 | Default value is 10s for "valid", 0s for "obsolete" and 30s for others. |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15061 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15062 | resolve_retries <nb> |
| 15063 | Defines the number <nb> of queries to send to resolve a server name before |
| 15064 | giving up. |
| 15065 | Default value: 3 |
| 15066 | |
Baptiste Assmann | 62b75b4 | 2015-09-09 01:11:36 +0200 | [diff] [blame] | 15067 | A retry occurs on name server timeout or when the full sequence of DNS query |
| 15068 | type failover is over and we need to start up from the default ANY query |
| 15069 | type. |
| 15070 | |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15071 | timeout <event> <time> |
| 15072 | Defines timeouts related to name resolution |
| 15073 | <event> : the event on which the <time> timeout period applies to. |
| 15074 | events available are: |
Frédéric Lécaille | 93d3316 | 2019-03-06 09:35:59 +0100 | [diff] [blame] | 15075 | - resolve : default time to trigger name resolutions when no |
| 15076 | other time applied. |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 15077 | Default value: 1s |
| 15078 | - retry : time between two DNS queries, when no valid response |
Frédéric Lécaille | 93d3316 | 2019-03-06 09:35:59 +0100 | [diff] [blame] | 15079 | have been received. |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 15080 | Default value: 1s |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15081 | <time> : time related to the event. It follows the HAProxy time format. |
| 15082 | <time> is expressed in milliseconds. |
| 15083 | |
Olivier Doucet | aa1ea8a | 2016-08-05 17:15:20 +0200 | [diff] [blame] | 15084 | Example: |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15085 | |
| 15086 | resolvers mydns |
| 15087 | nameserver dns1 10.0.0.1:53 |
| 15088 | nameserver dns2 10.0.0.2:53 |
Emeric Brun | c8f3e45 | 2021-04-07 16:04:54 +0200 | [diff] [blame] | 15089 | nameserver dns3 tcp@10.0.0.3:53 |
Ben Draut | 44e609b | 2018-05-29 15:40:08 -0600 | [diff] [blame] | 15090 | parse-resolv-conf |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15091 | resolve_retries 3 |
Christopher Faulet | 67957bd | 2017-09-27 11:00:59 +0200 | [diff] [blame] | 15092 | timeout resolve 1s |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15093 | timeout retry 1s |
Baptiste Assmann | 987e16d | 2016-11-02 22:23:31 +0100 | [diff] [blame] | 15094 | hold other 30s |
| 15095 | hold refused 30s |
| 15096 | hold nx 30s |
| 15097 | hold timeout 30s |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15098 | hold valid 10s |
Olivier Houchard | a8c6db8 | 2017-07-06 18:46:47 +0200 | [diff] [blame] | 15099 | hold obsolete 30s |
Baptiste Assmann | 1fa6666 | 2015-04-14 00:28:47 +0200 | [diff] [blame] | 15100 | |
| 15101 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 15102 | 6. Cache |
| 15103 | --------- |
| 15104 | |
| 15105 | HAProxy provides a cache, which was designed to perform cache on small objects |
| 15106 | (favicon, css...). This is a minimalist low-maintenance cache which runs in |
| 15107 | RAM. |
| 15108 | |
| 15109 | The cache is based on a memory which is shared between processes and threads, |
| 15110 | this memory is split in blocks of 1k. |
| 15111 | |
| 15112 | If an object is not used anymore, it can be deleted to store a new object |
| 15113 | independently of its expiration date. The oldest objects are deleted first |
| 15114 | when we try to allocate a new one. |
| 15115 | |
| 15116 | The cache uses a hash of the host header and the URI as the key. |
| 15117 | |
| 15118 | It's possible to view the status of a cache using the Unix socket command |
| 15119 | "show cache" consult section 9.3 "Unix Socket commands" of Management Guide |
| 15120 | for more details. |
| 15121 | |
| 15122 | When an object is delivered from the cache, the server name in the log is |
| 15123 | replaced by "<CACHE>". |
| 15124 | |
| 15125 | |
| 15126 | 6.1. Limitation |
| 15127 | ---------------- |
| 15128 | |
| 15129 | The cache won't store and won't deliver objects in these cases: |
| 15130 | |
| 15131 | - If the response is not a 200 |
Remi Tricot-Le Breton | 4f73083 | 2020-11-26 15:51:50 +0100 | [diff] [blame] | 15132 | - If the response contains a Vary header and either the process-vary option is |
| 15133 | disabled, or a currently unmanaged header is specified in the Vary value (only |
| 15134 | accept-encoding and referer are managed for now) |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 15135 | - If the Content-Length + the headers size is greater than "max-object-size" |
| 15136 | - If the response is not cacheable |
Remi Tricot-Le Breton | d493bc8 | 2020-11-26 15:51:29 +0100 | [diff] [blame] | 15137 | - If the response does not have an explicit expiration time (s-maxage or max-age |
| 15138 | Cache-Control directives or Expires header) or a validator (ETag or Last-Modified |
| 15139 | headers) |
Remi Tricot-Le Breton | 5853c0c | 2020-12-10 17:58:43 +0100 | [diff] [blame] | 15140 | - If the process-vary option is enabled and there are already max-secondary-entries |
| 15141 | entries with the same primary key as the current response |
Remi Tricot-Le Breton | 6ca8916 | 2021-01-07 14:50:51 +0100 | [diff] [blame] | 15142 | - If the process-vary option is enabled and the response has an unknown encoding (not |
| 15143 | mentioned in https://www.iana.org/assignments/http-parameters/http-parameters.xhtml) |
| 15144 | while varying on the accept-encoding client header |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 15145 | |
| 15146 | - If the request is not a GET |
| 15147 | - If the HTTP version of the request is smaller than 1.1 |
| 15148 | - If the request contains an Authorization header |
| 15149 | |
| 15150 | |
| 15151 | 6.2. Setup |
| 15152 | ----------- |
| 15153 | |
| 15154 | To setup a cache, you must define a cache section and use it in a proxy with |
| 15155 | the corresponding http-request and response actions. |
| 15156 | |
| 15157 | |
| 15158 | 6.2.1. Cache section |
| 15159 | --------------------- |
| 15160 | |
| 15161 | cache <name> |
| 15162 | Declare a cache section, allocate a shared cache memory named <name>, the |
| 15163 | size of cache is mandatory. |
| 15164 | |
| 15165 | total-max-size <megabytes> |
| 15166 | Define the size in RAM of the cache in megabytes. This size is split in |
| 15167 | blocks of 1kB which are used by the cache entries. Its maximum value is 4095. |
| 15168 | |
| 15169 | max-object-size <bytes> |
| 15170 | Define the maximum size of the objects to be cached. Must not be greater than |
| 15171 | an half of "total-max-size". If not set, it equals to a 256th of the cache size. |
| 15172 | All objects with sizes larger than "max-object-size" will not be cached. |
| 15173 | |
| 15174 | max-age <seconds> |
Remi Tricot-Le Breton | 5853c0c | 2020-12-10 17:58:43 +0100 | [diff] [blame] | 15175 | Define the maximum expiration duration. The expiration is set as the lowest |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 15176 | value between the s-maxage or max-age (in this order) directive in the |
| 15177 | Cache-Control response header and this value. The default value is 60 |
| 15178 | seconds, which means that you can't cache an object more than 60 seconds by |
| 15179 | default. |
| 15180 | |
Remi Tricot-Le Breton | e6cc5b5 | 2020-12-23 18:13:53 +0100 | [diff] [blame] | 15181 | process-vary <on/off> |
| 15182 | Enable or disable the processing of the Vary header. When disabled, a response |
Remi Tricot-Le Breton | 754b242 | 2020-11-16 15:56:10 +0100 | [diff] [blame] | 15183 | containing such a header will never be cached. When enabled, we need to calculate |
| 15184 | a preliminary hash for a subset of request headers on all the incoming requests |
| 15185 | (which might come with a cpu cost) which will be used to build a secondary key |
Remi Tricot-Le Breton | e6cc5b5 | 2020-12-23 18:13:53 +0100 | [diff] [blame] | 15186 | for a given request (see RFC 7234#4.1). The default value is off (disabled). |
Remi Tricot-Le Breton | 754b242 | 2020-11-16 15:56:10 +0100 | [diff] [blame] | 15187 | |
Remi Tricot-Le Breton | 5853c0c | 2020-12-10 17:58:43 +0100 | [diff] [blame] | 15188 | max-secondary-entries <number> |
| 15189 | Define the maximum number of simultaneous secondary entries with the same primary |
| 15190 | key in the cache. This needs the vary support to be enabled. Its default value is 10 |
| 15191 | and should be passed a strictly positive integer. |
| 15192 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 15193 | |
| 15194 | 6.2.2. Proxy section |
| 15195 | --------------------- |
| 15196 | |
| 15197 | http-request cache-use <name> [ { if | unless } <condition> ] |
| 15198 | Try to deliver a cached object from the cache <name>. This directive is also |
| 15199 | mandatory to store the cache as it calculates the cache hash. If you want to |
| 15200 | use a condition for both storage and delivering that's a good idea to put it |
| 15201 | after this one. |
| 15202 | |
| 15203 | http-response cache-store <name> [ { if | unless } <condition> ] |
| 15204 | Store an http-response within the cache. The storage of the response headers |
| 15205 | is done at this step, which means you can use others http-response actions |
| 15206 | to modify headers before or after the storage of the response. This action |
| 15207 | is responsible for the setup of the cache storage filter. |
| 15208 | |
| 15209 | |
| 15210 | Example: |
| 15211 | |
| 15212 | backend bck1 |
| 15213 | mode http |
| 15214 | |
| 15215 | http-request cache-use foobar |
| 15216 | http-response cache-store foobar |
| 15217 | server srv1 127.0.0.1:80 |
| 15218 | |
| 15219 | cache foobar |
| 15220 | total-max-size 4 |
| 15221 | max-age 240 |
| 15222 | |
| 15223 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15224 | 7. Using ACLs and fetching samples |
| 15225 | ---------------------------------- |
| 15226 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15227 | HAProxy is capable of extracting data from request or response streams, from |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15228 | client or server information, from tables, environmental information etc... |
| 15229 | The action of extracting such data is called fetching a sample. Once retrieved, |
| 15230 | these samples may be used for various purposes such as a key to a stick-table, |
| 15231 | but most common usages consist in matching them against predefined constant |
| 15232 | data called patterns. |
| 15233 | |
| 15234 | |
| 15235 | 7.1. ACL basics |
| 15236 | --------------- |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 15237 | |
| 15238 | The use of Access Control Lists (ACL) provides a flexible solution to perform |
| 15239 | content switching and generally to take decisions based on content extracted |
| 15240 | from the request, the response or any environmental status. The principle is |
| 15241 | simple : |
| 15242 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15243 | - extract a data sample from a stream, table or the environment |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15244 | - optionally apply some format conversion to the extracted sample |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15245 | - apply one or multiple pattern matching methods on this sample |
| 15246 | - perform actions only when a pattern matches the sample |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 15247 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15248 | The actions generally consist in blocking a request, selecting a backend, or |
| 15249 | adding a header. |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 15250 | |
| 15251 | In order to define a test, the "acl" keyword is used. The syntax is : |
| 15252 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15253 | acl <aclname> <criterion> [flags] [operator] [<value>] ... |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 15254 | |
| 15255 | This creates a new ACL <aclname> or completes an existing one with new tests. |
| 15256 | Those tests apply to the portion of request/response specified in <criterion> |
| 15257 | and may be adjusted with optional flags [flags]. Some criteria also support |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15258 | an operator which may be specified before the set of values. Optionally some |
| 15259 | conversion operators may be applied to the sample, and they will be specified |
| 15260 | as a comma-delimited list of keywords just after the first keyword. The values |
| 15261 | 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] | 15262 | |
| 15263 | ACL names must be formed from upper and lower case letters, digits, '-' (dash), |
| 15264 | '_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive, |
| 15265 | which means that "my_acl" and "My_Acl" are two different ACLs. |
| 15266 | |
| 15267 | There is no enforced limit to the number of ACLs. The unused ones do not affect |
| 15268 | performance, they just consume a small amount of memory. |
| 15269 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15270 | The criterion generally is the name of a sample fetch method, or one of its ACL |
| 15271 | specific declinations. The default test method is implied by the output type of |
| 15272 | this sample fetch method. The ACL declinations can describe alternate matching |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15273 | methods of a same sample fetch method. The sample fetch methods are the only |
| 15274 | ones supporting a conversion. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15275 | |
| 15276 | Sample fetch methods return data which can be of the following types : |
| 15277 | - boolean |
| 15278 | - integer (signed or unsigned) |
| 15279 | - IPv4 or IPv6 address |
| 15280 | - string |
| 15281 | - data block |
| 15282 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15283 | Converters transform any of these data into any of these. For example, some |
| 15284 | converters might convert a string to a lower-case string while other ones |
| 15285 | would turn a string to an IPv4 address, or apply a netmask to an IP address. |
| 15286 | The resulting sample is of the type of the last converter applied to the list, |
| 15287 | which defaults to the type of the sample fetch method. |
| 15288 | |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15289 | Each sample or converter returns data of a specific type, specified with its |
| 15290 | keyword in this documentation. When an ACL is declared using a standard sample |
| 15291 | fetch method, certain types automatically involved a default matching method |
| 15292 | which are summarized in the table below : |
| 15293 | |
| 15294 | +---------------------+-----------------+ |
| 15295 | | Sample or converter | Default | |
| 15296 | | output type | matching method | |
| 15297 | +---------------------+-----------------+ |
| 15298 | | boolean | bool | |
| 15299 | +---------------------+-----------------+ |
| 15300 | | integer | int | |
| 15301 | +---------------------+-----------------+ |
| 15302 | | ip | ip | |
| 15303 | +---------------------+-----------------+ |
| 15304 | | string | str | |
| 15305 | +---------------------+-----------------+ |
| 15306 | | binary | none, use "-m" | |
| 15307 | +---------------------+-----------------+ |
| 15308 | |
| 15309 | Note that in order to match a binary samples, it is mandatory to specify a |
| 15310 | matching method, see below. |
| 15311 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15312 | The ACL engine can match these types against patterns of the following types : |
| 15313 | - boolean |
| 15314 | - integer or integer range |
| 15315 | - IP address / network |
| 15316 | - string (exact, substring, suffix, prefix, subdir, domain) |
| 15317 | - regular expression |
| 15318 | - hex block |
| 15319 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 15320 | The following ACL flags are currently supported : |
| 15321 | |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 15322 | -i : ignore case during matching of all subsequent patterns. |
| 15323 | -f : load patterns from a file. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15324 | -m : use a specific pattern matching method |
Thierry FOURNIER | b7729c9 | 2014-02-11 16:24:41 +0100 | [diff] [blame] | 15325 | -n : forbid the DNS resolutions |
Thierry FOURNIER | 9860c41 | 2014-01-29 14:23:29 +0100 | [diff] [blame] | 15326 | -M : load the file pointed by -f like a map file. |
Thierry FOURNIER | 3534d88 | 2014-01-20 17:01:44 +0100 | [diff] [blame] | 15327 | -u : force the unique id of the ACL |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15328 | -- : force end of flags. Useful when a string looks like one of the flags. |
| 15329 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15330 | The "-f" flag is followed by the name of a file from which all lines will be |
| 15331 | read as individual values. It is even possible to pass multiple "-f" arguments |
| 15332 | if the patterns are to be loaded from multiple files. Empty lines as well as |
| 15333 | lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs |
| 15334 | will be stripped. If it is absolutely necessary to insert a valid pattern |
| 15335 | beginning with a sharp, just prefix it with a space so that it is not taken for |
| 15336 | a comment. Depending on the data type and match method, haproxy may load the |
| 15337 | lines into a binary tree, allowing very fast lookups. This is true for IPv4 and |
| 15338 | exact string matching. In this case, duplicates will automatically be removed. |
| 15339 | |
Thierry FOURNIER | 9860c41 | 2014-01-29 14:23:29 +0100 | [diff] [blame] | 15340 | The "-M" flag allows an ACL to use a map file. If this flag is set, the file is |
| 15341 | parsed as two column file. The first column contains the patterns used by the |
| 15342 | ACL, and the second column contain the samples. The sample can be used later by |
| 15343 | a map. This can be useful in some rare cases where an ACL would just be used to |
| 15344 | check for the existence of a pattern in a map before a mapping is applied. |
| 15345 | |
Thierry FOURNIER | 3534d88 | 2014-01-20 17:01:44 +0100 | [diff] [blame] | 15346 | The "-u" flag forces the unique id of the ACL. This unique id is used with the |
| 15347 | socket interface to identify ACL and dynamically change its values. Note that a |
| 15348 | file is always identified by its name even if an id is set. |
| 15349 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15350 | Also, note that the "-i" flag applies to subsequent entries and not to entries |
| 15351 | loaded from files preceding it. For instance : |
| 15352 | |
| 15353 | acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test |
| 15354 | |
| 15355 | In this example, each line of "exact-ua.lst" will be exactly matched against |
| 15356 | the "user-agent" header of the request. Then each line of "generic-ua" will be |
| 15357 | case-insensitively matched. Then the word "test" will be insensitively matched |
| 15358 | as well. |
| 15359 | |
| 15360 | The "-m" flag is used to select a specific pattern matching method on the input |
| 15361 | sample. All ACL-specific criteria imply a pattern matching method and generally |
| 15362 | do not need this flag. However, this flag is useful with generic sample fetch |
| 15363 | methods to describe how they're going to be matched against the patterns. This |
| 15364 | is required for sample fetches which return data type for which there is no |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15365 | obvious matching method (e.g. string or binary). When "-m" is specified and |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15366 | followed by a pattern matching method name, this method is used instead of the |
| 15367 | default one for the criterion. This makes it possible to match contents in ways |
| 15368 | that were not initially planned, or with sample fetch methods which return a |
| 15369 | string. The matching method also affects the way the patterns are parsed. |
| 15370 | |
Thierry FOURNIER | b7729c9 | 2014-02-11 16:24:41 +0100 | [diff] [blame] | 15371 | The "-n" flag forbids the dns resolutions. It is used with the load of ip files. |
| 15372 | By default, if the parser cannot parse ip address it considers that the parsed |
| 15373 | string is maybe a domain name and try dns resolution. The flag "-n" disable this |
| 15374 | resolution. It is useful for detecting malformed ip lists. Note that if the DNS |
| 15375 | server is not reachable, the haproxy configuration parsing may last many minutes |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 15376 | waiting for the timeout. During this time no error messages are displayed. The |
Thierry FOURNIER | b7729c9 | 2014-02-11 16:24:41 +0100 | [diff] [blame] | 15377 | flag "-n" disable this behavior. Note also that during the runtime, this |
| 15378 | function is disabled for the dynamic acl modifications. |
| 15379 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15380 | There are some restrictions however. Not all methods can be used with all |
| 15381 | sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must |
| 15382 | 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] | 15383 | |
| 15384 | - "found" : only check if the requested sample could be found in the stream, |
| 15385 | but do not compare it against any pattern. It is recommended not |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15386 | to pass any pattern to avoid confusion. This matching method is |
| 15387 | particularly useful to detect presence of certain contents such |
| 15388 | as headers, cookies, etc... even if they are empty and without |
| 15389 | comparing them to anything nor counting them. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15390 | |
| 15391 | - "bool" : check the value as a boolean. It can only be applied to fetches |
| 15392 | which return a boolean or integer value, and takes no pattern. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15393 | Value zero or false does not match, all other values do match. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15394 | |
| 15395 | - "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] | 15396 | boolean samples. Boolean false is integer 0, true is integer 1. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15397 | |
| 15398 | - "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] | 15399 | with IP address samples only, so it is implied and never needed. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15400 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15401 | - "bin" : match the contents against a hexadecimal string representing a |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15402 | binary sequence. This may be used with binary or string samples. |
| 15403 | |
| 15404 | - "len" : match the sample's length as an integer. This may be used with |
| 15405 | binary or string samples. |
| 15406 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15407 | - "str" : exact match : match the contents against a string. This may be |
| 15408 | used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15409 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15410 | - "sub" : substring match : check that the contents contain at least one of |
| 15411 | the provided string patterns. This may be used with binary or |
| 15412 | string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15413 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15414 | - "reg" : regex match : match the contents against a list of regular |
| 15415 | expressions. This may be used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15416 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15417 | - "beg" : prefix match : check that the contents begin like the provided |
| 15418 | string patterns. This may be used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15419 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15420 | - "end" : suffix match : check that the contents end like the provided |
| 15421 | string patterns. This may be used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15422 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15423 | - "dir" : subdir match : check that a slash-delimited portion of the |
| 15424 | contents exactly matches one of the provided string patterns. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15425 | This may be used with binary or string samples. |
| 15426 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15427 | - "dom" : domain match : check that a dot-delimited portion of the contents |
| 15428 | exactly match one of the provided string patterns. This may be |
| 15429 | used with binary or string samples. |
Willy Tarreau | 5adeda1 | 2013-03-31 22:13:34 +0200 | [diff] [blame] | 15430 | |
| 15431 | For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP |
| 15432 | request, it is possible to do : |
| 15433 | |
| 15434 | acl jsess_present cook(JSESSIONID) -m found |
| 15435 | |
| 15436 | In order to apply a regular expression on the 500 first bytes of data in the |
| 15437 | buffer, one would use the following acl : |
| 15438 | |
| 15439 | acl script_tag payload(0,500) -m reg -i <script> |
| 15440 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15441 | On systems where the regex library is much slower when using "-i", it is |
| 15442 | possible to convert the sample to lowercase before matching, like this : |
| 15443 | |
| 15444 | acl script_tag payload(0,500),lower -m reg <script> |
| 15445 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15446 | All ACL-specific criteria imply a default matching method. Most often, these |
| 15447 | criteria are composed by concatenating the name of the original sample fetch |
| 15448 | method and the matching method. For example, "hdr_beg" applies the "beg" match |
| 15449 | to samples retrieved using the "hdr" fetch method. Since all ACL-specific |
| 15450 | criteria rely on a sample fetch method, it is always possible instead to use |
| 15451 | the original sample fetch method and the explicit matching method using "-m". |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 15452 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15453 | 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] | 15454 | the matching method is simply applied to the underlying sample fetch method. |
| 15455 | For example, all ACLs below are exact equivalent : |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 15456 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15457 | acl short_form hdr_beg(host) www. |
| 15458 | acl alternate1 hdr_beg(host) -m beg www. |
| 15459 | acl alternate2 hdr_dom(host) -m beg www. |
| 15460 | acl alternate3 hdr(host) -m beg www. |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 15461 | |
Willy Tarreau | 2b5285d | 2010-05-09 23:45:24 +0200 | [diff] [blame] | 15462 | |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15463 | The table below summarizes the compatibility matrix between sample or converter |
| 15464 | types and the pattern types to fetch against. It indicates for each compatible |
| 15465 | combination the name of the matching method to be used, surrounded with angle |
| 15466 | brackets ">" and "<" when the method is the default one and will work by |
| 15467 | default without "-m". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 15468 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15469 | +-------------------------------------------------+ |
| 15470 | | Input sample type | |
| 15471 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15472 | | pattern type | boolean | integer | ip | string | binary | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15473 | +----------------------+---------+---------+---------+---------+---------+ |
| 15474 | | none (presence only) | found | found | found | found | found | |
| 15475 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15476 | | none (boolean value) |> bool <| bool | | bool | | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15477 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15478 | | integer (value) | int |> int <| int | int | | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15479 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15480 | | integer (length) | len | len | len | len | len | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15481 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15482 | | IP address | | |> ip <| ip | ip | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15483 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | 2a06e39 | 2014-05-11 15:49:55 +0200 | [diff] [blame] | 15484 | | exact string | str | str | str |> str <| str | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15485 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15486 | | prefix | beg | beg | beg | beg | beg | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15487 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15488 | | suffix | end | end | end | end | end | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15489 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15490 | | substring | sub | sub | sub | sub | sub | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15491 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15492 | | subdir | dir | dir | dir | dir | dir | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15493 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15494 | | domain | dom | dom | dom | dom | dom | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15495 | +----------------------+---------+---------+---------+---------+---------+ |
Thierry FOURNIER | e3ded59 | 2013-12-06 15:36:54 +0100 | [diff] [blame] | 15496 | | regex | reg | reg | reg | reg | reg | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15497 | +----------------------+---------+---------+---------+---------+---------+ |
| 15498 | | hex block | | | | bin | bin | |
| 15499 | +----------------------+---------+---------+---------+---------+---------+ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15500 | |
| 15501 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15502 | 7.1.1. Matching booleans |
| 15503 | ------------------------ |
| 15504 | |
| 15505 | In order to match a boolean, no value is needed and all values are ignored. |
| 15506 | Boolean matching is used by default for all fetch methods of type "boolean". |
| 15507 | When boolean matching is used, the fetched value is returned as-is, which means |
| 15508 | that a boolean "true" will always match and a boolean "false" will never match. |
| 15509 | |
| 15510 | Boolean matching may also be enforced using "-m bool" on fetch methods which |
| 15511 | return an integer value. Then, integer value 0 is converted to the boolean |
| 15512 | "false" and all other values are converted to "true". |
| 15513 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15514 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15515 | 7.1.2. Matching integers |
| 15516 | ------------------------ |
| 15517 | |
| 15518 | Integer matching applies by default to integer fetch methods. It can also be |
| 15519 | enforced on boolean fetches using "-m int". In this case, "false" is converted |
| 15520 | to the integer 0, and "true" is converted to the integer 1. |
| 15521 | |
| 15522 | Integer matching also supports integer ranges and operators. Note that integer |
| 15523 | matching only applies to positive values. A range is a value expressed with a |
| 15524 | 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] | 15525 | |
| 15526 | For instance, "1024:65535" is a valid range to represent a range of |
| 15527 | unprivileged ports, and "1024:" would also work. "0:1023" is a valid |
| 15528 | representation of privileged ports, and ":1023" would also work. |
| 15529 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 15530 | As a special case, some ACL functions support decimal numbers which are in fact |
| 15531 | two integers separated by a dot. This is used with some version checks for |
| 15532 | instance. All integer properties apply to those decimal numbers, including |
| 15533 | ranges and operators. |
| 15534 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15535 | For an easier usage, comparison operators are also supported. Note that using |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 15536 | operators with ranges does not make much sense and is strongly discouraged. |
| 15537 | Similarly, it does not make much sense to perform order comparisons with a set |
| 15538 | of values. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15539 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 15540 | Available operators for integer matching are : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15541 | |
| 15542 | eq : true if the tested value equals at least one value |
| 15543 | ge : true if the tested value is greater than or equal to at least one value |
| 15544 | gt : true if the tested value is greater than at least one value |
| 15545 | le : true if the tested value is less than or equal to at least one value |
| 15546 | lt : true if the tested value is less than at least one value |
| 15547 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 15548 | For instance, the following ACL matches any negative Content-Length header : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15549 | |
| 15550 | acl negative-length hdr_val(content-length) lt 0 |
| 15551 | |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 15552 | This one matches SSL versions between 3.0 and 3.1 (inclusive) : |
| 15553 | |
| 15554 | acl sslv3 req_ssl_ver 3:3.1 |
| 15555 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15556 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15557 | 7.1.3. Matching strings |
| 15558 | ----------------------- |
| 15559 | |
| 15560 | String matching applies to string or binary fetch methods, and exists in 6 |
| 15561 | different forms : |
| 15562 | |
| 15563 | - exact match (-m str) : the extracted string must exactly match the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15564 | patterns; |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15565 | |
| 15566 | - substring match (-m sub) : the patterns are looked up inside the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15567 | extracted string, and the ACL matches if any of them is found inside; |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15568 | |
| 15569 | - prefix match (-m beg) : the patterns are compared with the beginning of |
| 15570 | the extracted string, and the ACL matches if any of them matches. |
| 15571 | |
| 15572 | - suffix match (-m end) : the patterns are compared with the end of the |
| 15573 | extracted string, and the ACL matches if any of them matches. |
| 15574 | |
Baptiste Assmann | 33db600 | 2016-03-06 23:32:10 +0100 | [diff] [blame] | 15575 | - subdir match (-m dir) : the patterns are looked up inside the extracted |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15576 | string, delimited with slashes ("/"), and the ACL matches if any of them |
| 15577 | matches. |
| 15578 | |
| 15579 | - domain match (-m dom) : the patterns are looked up inside the extracted |
| 15580 | string, delimited with dots ("."), and the ACL matches if any of them |
| 15581 | matches. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15582 | |
| 15583 | String matching applies to verbatim strings as they are passed, with the |
| 15584 | exception of the backslash ("\") which makes it possible to escape some |
| 15585 | characters such as the space. If the "-i" flag is passed before the first |
| 15586 | string, then the matching will be performed ignoring the case. In order |
| 15587 | 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] | 15588 | before the first string. Same applies of course to match the string "--". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15589 | |
Mathias Weiersmueller | cb250fc | 2019-12-02 09:43:40 +0100 | [diff] [blame] | 15590 | Do not use string matches for binary fetches which might contain null bytes |
| 15591 | (0x00), as the comparison stops at the occurrence of the first null byte. |
| 15592 | Instead, convert the binary fetch to a hex string with the hex converter first. |
| 15593 | |
| 15594 | Example: |
| 15595 | # matches if the string <tag> is present in the binary sample |
| 15596 | acl tag_found req.payload(0,0),hex -m sub 3C7461673E |
| 15597 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15598 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15599 | 7.1.4. Matching regular expressions (regexes) |
| 15600 | --------------------------------------------- |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15601 | |
| 15602 | Just like with string matching, regex matching applies to verbatim strings as |
| 15603 | they are passed, with the exception of the backslash ("\") which makes it |
| 15604 | possible to escape some characters such as the space. If the "-i" flag is |
| 15605 | passed before the first regex, then the matching will be performed ignoring |
| 15606 | 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] | 15607 | the "--" flag before the first string. Same principle applies of course to |
| 15608 | match the string "--". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15609 | |
| 15610 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15611 | 7.1.5. Matching arbitrary data blocks |
| 15612 | ------------------------------------- |
| 15613 | |
| 15614 | It is possible to match some extracted samples against a binary block which may |
| 15615 | not safely be represented as a string. For this, the patterns must be passed as |
| 15616 | a series of hexadecimal digits in an even number, when the match method is set |
| 15617 | to binary. Each sequence of two digits will represent a byte. The hexadecimal |
| 15618 | digits may be used upper or lower case. |
| 15619 | |
| 15620 | Example : |
| 15621 | # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a) |
| 15622 | acl hello payload(0,6) -m bin 48656c6c6f0a |
| 15623 | |
| 15624 | |
| 15625 | 7.1.6. Matching IPv4 and IPv6 addresses |
| 15626 | --------------------------------------- |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15627 | |
| 15628 | IPv4 addresses values can be specified either as plain addresses or with a |
| 15629 | netmask appended, in which case the IPv4 address matches whenever it is |
| 15630 | within the network. Plain addresses may also be replaced with a resolvable |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 15631 | 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] | 15632 | difficult to read and debug configurations. If hostnames are used, you should |
| 15633 | at least ensure that they are present in /etc/hosts so that the configuration |
| 15634 | does not depend on any random DNS match at the moment the configuration is |
| 15635 | parsed. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15636 | |
Daniel Schneller | eba5634 | 2016-04-13 00:26:52 +0200 | [diff] [blame] | 15637 | The dotted IPv4 address notation is supported in both regular as well as the |
| 15638 | abbreviated form with all-0-octets omitted: |
| 15639 | |
| 15640 | +------------------+------------------+------------------+ |
| 15641 | | Example 1 | Example 2 | Example 3 | |
| 15642 | +------------------+------------------+------------------+ |
| 15643 | | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 | |
| 15644 | | 192.168.1 | 10.12 | 127.1 | |
| 15645 | | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 | |
| 15646 | | 192.168.1/22 | 10.12/8 | 127.1/8 | |
| 15647 | +------------------+------------------+------------------+ |
| 15648 | |
| 15649 | Notice that this is different from RFC 4632 CIDR address notation in which |
| 15650 | 192.168.42/24 would be equivalent to 192.168.42.0/24. |
| 15651 | |
Willy Tarreau | ceb4ac9 | 2012-04-28 00:41:46 +0200 | [diff] [blame] | 15652 | IPv6 may be entered in their usual form, with or without a netmask appended. |
| 15653 | Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of |
| 15654 | trouble with randomly resolved IP addresses, host names are never allowed in |
| 15655 | IPv6 patterns. |
| 15656 | |
| 15657 | HAProxy is also able to match IPv4 addresses with IPv6 addresses in the |
| 15658 | following situations : |
| 15659 | - tested address is IPv4, pattern address is IPv4, the match applies |
| 15660 | in IPv4 using the supplied mask if any. |
| 15661 | - tested address is IPv6, pattern address is IPv6, the match applies |
| 15662 | in IPv6 using the supplied mask if any. |
| 15663 | - tested address is IPv6, pattern address is IPv4, the match applies in IPv4 |
| 15664 | using the pattern's mask if the IPv6 address matches with 2002:IPV4::, |
| 15665 | ::IPV4 or ::ffff:IPV4, otherwise it fails. |
| 15666 | - tested address is IPv4, pattern address is IPv6, the IPv4 address is first |
| 15667 | converted to IPv6 by prefixing ::ffff: in front of it, then the match is |
| 15668 | applied in IPv6 using the supplied IPv6 mask. |
| 15669 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15670 | |
| 15671 | 7.2. Using ACLs to form conditions |
| 15672 | ---------------------------------- |
| 15673 | |
| 15674 | Some actions are only performed upon a valid condition. A condition is a |
| 15675 | combination of ACLs with operators. 3 operators are supported : |
| 15676 | |
| 15677 | - AND (implicit) |
| 15678 | - OR (explicit with the "or" keyword or the "||" operator) |
| 15679 | - Negation with the exclamation mark ("!") |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15680 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15681 | A condition is formed as a disjunctive form: |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 15682 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15683 | [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ... |
Willy Tarreau | bef91e7 | 2013-03-31 23:14:46 +0200 | [diff] [blame] | 15684 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15685 | Such conditions are generally used after an "if" or "unless" statement, |
| 15686 | indicating when the condition will trigger the action. |
Willy Tarreau | bef91e7 | 2013-03-31 23:14:46 +0200 | [diff] [blame] | 15687 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15688 | For instance, to block HTTP requests to the "*" URL with methods other than |
| 15689 | "OPTIONS", as well as POST requests without content-length, and GET or HEAD |
| 15690 | requests with a content-length greater than 0, and finally every request which |
| 15691 | is not either GET/HEAD/POST/OPTIONS ! |
| 15692 | |
| 15693 | acl missing_cl hdr_cnt(Content-length) eq 0 |
Jarno Huuskonen | 84c51ec | 2017-04-03 14:20:34 +0300 | [diff] [blame] | 15694 | http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl |
| 15695 | http-request deny if METH_GET HTTP_CONTENT |
| 15696 | http-request deny unless METH_GET or METH_POST or METH_OPTIONS |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15697 | |
| 15698 | To select a different backend for requests to static contents on the "www" site |
| 15699 | and to every request on the "img", "video", "download" and "ftp" hosts : |
| 15700 | |
| 15701 | acl url_static path_beg /static /images /img /css |
| 15702 | acl url_static path_end .gif .png .jpg .css .js |
| 15703 | acl host_www hdr_beg(host) -i www |
| 15704 | acl host_static hdr_beg(host) -i img. video. download. ftp. |
| 15705 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15706 | # now use backend "static" for all static-only hosts, and for static URLs |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15707 | # of host "www". Use backend "www" for the rest. |
| 15708 | use_backend static if host_static or host_www url_static |
| 15709 | use_backend www if host_www |
| 15710 | |
| 15711 | It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL |
| 15712 | expressions that are built on the fly without needing to be declared. They must |
| 15713 | be enclosed between braces, with a space before and after each brace (because |
| 15714 | the braces must be seen as independent words). Example : |
| 15715 | |
| 15716 | The following rule : |
| 15717 | |
| 15718 | acl missing_cl hdr_cnt(Content-length) eq 0 |
Jarno Huuskonen | 84c51ec | 2017-04-03 14:20:34 +0300 | [diff] [blame] | 15719 | http-request deny if METH_POST missing_cl |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15720 | |
| 15721 | Can also be written that way : |
| 15722 | |
Jarno Huuskonen | 84c51ec | 2017-04-03 14:20:34 +0300 | [diff] [blame] | 15723 | http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 } |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15724 | |
| 15725 | It is generally not recommended to use this construct because it's a lot easier |
| 15726 | to leave errors in the configuration when written that way. However, for very |
| 15727 | simple rules matching only one source IP address for instance, it can make more |
| 15728 | sense to use them than to declare ACLs with random names. Another example of |
| 15729 | good use is the following : |
| 15730 | |
| 15731 | With named ACLs : |
| 15732 | |
| 15733 | acl site_dead nbsrv(dynamic) lt 2 |
| 15734 | acl site_dead nbsrv(static) lt 2 |
| 15735 | monitor fail if site_dead |
| 15736 | |
| 15737 | With anonymous ACLs : |
| 15738 | |
| 15739 | monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 } |
| 15740 | |
Jarno Huuskonen | 84c51ec | 2017-04-03 14:20:34 +0300 | [diff] [blame] | 15741 | See section 4.2 for detailed help on the "http-request deny" and "use_backend" |
| 15742 | keywords. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15743 | |
| 15744 | |
| 15745 | 7.3. Fetching samples |
| 15746 | --------------------- |
| 15747 | |
| 15748 | Historically, sample fetch methods were only used to retrieve data to match |
| 15749 | against patterns using ACLs. With the arrival of stick-tables, a new class of |
| 15750 | sample fetch methods was created, most often sharing the same syntax as their |
| 15751 | ACL counterpart. These sample fetch methods are also known as "fetches". As |
| 15752 | of now, ACLs and fetches have converged. All ACL fetch methods have been made |
| 15753 | available as fetch methods, and ACLs may use any sample fetch method as well. |
| 15754 | |
| 15755 | This section details all available sample fetch methods and their output type. |
| 15756 | Some sample fetch methods have deprecated aliases that are used to maintain |
| 15757 | compatibility with existing configurations. They are then explicitly marked as |
| 15758 | deprecated and should not be used in new setups. |
| 15759 | |
| 15760 | The ACL derivatives are also indicated when available, with their respective |
| 15761 | matching methods. These ones all have a well defined default pattern matching |
| 15762 | method, so it is never necessary (though allowed) to pass the "-m" option to |
| 15763 | indicate how the sample will be matched using ACLs. |
| 15764 | |
| 15765 | As indicated in the sample type versus matching compatibility matrix above, |
| 15766 | when using a generic sample fetch method in an ACL, the "-m" option is |
| 15767 | mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When |
| 15768 | the same keyword exists as an ACL keyword and as a standard fetch method, the |
| 15769 | ACL engine will automatically pick the ACL-only one by default. |
| 15770 | |
| 15771 | Some of these keywords support one or multiple mandatory arguments, and one or |
| 15772 | multiple optional arguments. These arguments are strongly typed and are checked |
| 15773 | when the configuration is parsed so that there is no risk of running with an |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15774 | incorrect argument (e.g. an unresolved backend name). Fetch function arguments |
| 15775 | are passed between parenthesis and are delimited by commas. When an argument |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15776 | is optional, it will be indicated below between square brackets ('[ ]'). When |
| 15777 | all arguments are optional, the parenthesis may be omitted. |
| 15778 | |
| 15779 | Thus, the syntax of a standard sample fetch method is one of the following : |
| 15780 | - name |
| 15781 | - name(arg1) |
| 15782 | - name(arg1,arg2) |
| 15783 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 15784 | |
| 15785 | 7.3.1. Converters |
| 15786 | ----------------- |
| 15787 | |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15788 | Sample fetch methods may be combined with transformations to be applied on top |
| 15789 | of the fetched sample (also called "converters"). These combinations form what |
| 15790 | is called "sample expressions" and the result is a "sample". Initially this |
| 15791 | was only supported by "stick on" and "stick store-request" directives but this |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15792 | has now be extended to all places where samples may be used (ACLs, log-format, |
Willy Tarreau | e6b11e4 | 2013-11-26 19:02:32 +0100 | [diff] [blame] | 15793 | unique-id-format, add-header, ...). |
| 15794 | |
| 15795 | These transformations are enumerated as a series of specific keywords after the |
| 15796 | sample fetch method. These keywords may equally be appended immediately after |
| 15797 | the fetch keyword's argument, delimited by a comma. These keywords can also |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15798 | support some arguments (e.g. a netmask) which must be passed in parenthesis. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 15799 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15800 | A certain category of converters are bitwise and arithmetic operators which |
| 15801 | support performing basic operations on integers. Some bitwise operations are |
| 15802 | supported (and, or, xor, cpl) and some arithmetic operations are supported |
| 15803 | (add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not, |
| 15804 | bool) which make it possible to report a match without having to write an ACL. |
| 15805 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 15806 | The currently available list of transformation keywords include : |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 15807 | |
Ben Shillito | f25e8e5 | 2016-12-02 14:25:37 +0000 | [diff] [blame] | 15808 | 51d.single(<prop>[,<prop>*]) |
| 15809 | Returns values for the properties requested as a string, where values are |
| 15810 | separated by the delimiter specified with "51degrees-property-separator". |
| 15811 | The device is identified using the User-Agent header passed to the |
| 15812 | converter. The function can be passed up to five property names, and if a |
| 15813 | property name can't be found, the value "NoData" is returned. |
| 15814 | |
| 15815 | Example : |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15816 | # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request, |
| 15817 | # containing values for the three properties requested by using the |
Ben Shillito | f25e8e5 | 2016-12-02 14:25:37 +0000 | [diff] [blame] | 15818 | # User-Agent passed to the converter. |
| 15819 | frontend http-in |
| 15820 | bind *:8081 |
| 15821 | default_backend servers |
| 15822 | http-request set-header X-51D-DeviceTypeMobileTablet \ |
| 15823 | %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)] |
| 15824 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15825 | add(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 15826 | Adds <value> to the input value of type signed integer, and returns the |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 15827 | result as a signed integer. <value> can be a numeric value or a variable |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 15828 | name. The name of the variable starts with an indication about its scope. The |
| 15829 | scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 15830 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 15831 | "sess" : the variable is shared with the whole session |
| 15832 | "txn" : the variable is shared with the transaction (request and response) |
| 15833 | "req" : the variable is shared only during request processing |
| 15834 | "res" : the variable is shared only during response processing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15835 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 15836 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15837 | |
Nenad Merdanovic | c31499d | 2019-03-23 11:00:32 +0100 | [diff] [blame] | 15838 | aes_gcm_dec(<bits>,<nonce>,<key>,<aead_tag>) |
| 15839 | Decrypts the raw byte input using the AES128-GCM, AES192-GCM or |
| 15840 | AES256-GCM algorithm, depending on the <bits> parameter. All other parameters |
| 15841 | need to be base64 encoded and the returned result is in raw byte format. |
| 15842 | If the <aead_tag> validation fails, the converter doesn't return any data. |
| 15843 | The <nonce>, <key> and <aead_tag> can either be strings or variables. This |
| 15844 | converter requires at least OpenSSL 1.0.1. |
| 15845 | |
| 15846 | Example: |
| 15847 | http-response set-header X-Decrypted-Text %[var(txn.enc),\ |
| 15848 | aes_gcm_dec(128,txn.nonce,Zm9vb2Zvb29mb29wZm9vbw==,txn.aead_tag)] |
| 15849 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15850 | and(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 15851 | Performs a bitwise "AND" between <value> and the input value of type signed |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 15852 | integer, and returns the result as an signed integer. <value> can be a |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 15853 | numeric value or a variable name. The name of the variable starts with an |
| 15854 | indication about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 15855 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 15856 | "sess" : the variable is shared with the whole session |
| 15857 | "txn" : the variable is shared with the transaction (request and response) |
| 15858 | "req" : the variable is shared only during request processing |
| 15859 | "res" : the variable is shared only during response processing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15860 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 15861 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15862 | |
Holger Just | 1bfc24b | 2017-05-06 00:56:53 +0200 | [diff] [blame] | 15863 | b64dec |
| 15864 | Converts (decodes) a base64 encoded input string to its binary |
| 15865 | representation. It performs the inverse operation of base64(). |
Moemen MHEDHBI | 92f7d43 | 2021-04-01 20:53:59 +0200 | [diff] [blame] | 15866 | For base64url("URL and Filename Safe Alphabet" (RFC 4648)) variant |
| 15867 | see "ub64dec". |
Holger Just | 1bfc24b | 2017-05-06 00:56:53 +0200 | [diff] [blame] | 15868 | |
Emeric Brun | 53d1a98 | 2014-04-30 18:21:37 +0200 | [diff] [blame] | 15869 | base64 |
| 15870 | Converts a binary input sample to a base64 string. It is used to log or |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15871 | transfer binary content in a way that can be reliably transferred (e.g. |
Moemen MHEDHBI | 92f7d43 | 2021-04-01 20:53:59 +0200 | [diff] [blame] | 15872 | an SSL ID can be copied in a header). For base64url("URL and Filename |
| 15873 | Safe Alphabet" (RFC 4648)) variant see "ub64enc". |
Emeric Brun | 53d1a98 | 2014-04-30 18:21:37 +0200 | [diff] [blame] | 15874 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15875 | bool |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 15876 | Returns a boolean TRUE if the input value of type signed integer is |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15877 | non-null, otherwise returns FALSE. Used in conjunction with and(), it can be |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15878 | used to report true/false for bit testing on input values (e.g. verify the |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15879 | presence of a flag). |
| 15880 | |
Emeric Brun | 54c4ac8 | 2014-11-03 15:32:43 +0100 | [diff] [blame] | 15881 | bytes(<offset>[,<length>]) |
| 15882 | Extracts some bytes from an input binary sample. The result is a binary |
| 15883 | sample starting at an offset (in bytes) of the original sample and |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 15884 | optionally truncated at the given length. |
Emeric Brun | 54c4ac8 | 2014-11-03 15:32:43 +0100 | [diff] [blame] | 15885 | |
Willy Tarreau | 280f42b | 2018-02-19 15:34:12 +0100 | [diff] [blame] | 15886 | concat([<start>],[<var>],[<end>]) |
| 15887 | Concatenates up to 3 fields after the current sample which is then turned to |
| 15888 | a string. The first one, <start>, is a constant string, that will be appended |
| 15889 | immediately after the existing sample. It may be omitted if not used. The |
| 15890 | second one, <var>, is a variable name. The variable will be looked up, its |
| 15891 | contents converted to a string, and it will be appended immediately after the |
| 15892 | <first> part. If the variable is not found, nothing is appended. It may be |
| 15893 | omitted as well. The third field, <end> is a constant string that will be |
| 15894 | appended after the variable. It may also be omitted. Together, these elements |
| 15895 | allow to concatenate variables with delimiters to an existing set of |
| 15896 | variables. This can be used to build new variables made of a succession of |
Willy Tarreau | ef21fac | 2020-02-14 13:37:20 +0100 | [diff] [blame] | 15897 | other variables, such as colon-delimited values. If commas or closing |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 15898 | parenthesis are needed as delimiters, they must be protected by quotes or |
Willy Tarreau | ef21fac | 2020-02-14 13:37:20 +0100 | [diff] [blame] | 15899 | backslashes, themselves protected so that they are not stripped by the first |
| 15900 | level parser. See examples below. |
Willy Tarreau | 280f42b | 2018-02-19 15:34:12 +0100 | [diff] [blame] | 15901 | |
| 15902 | Example: |
| 15903 | tcp-request session set-var(sess.src) src |
| 15904 | tcp-request session set-var(sess.dn) ssl_c_s_dn |
| 15905 | tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>) |
Willy Tarreau | ef21fac | 2020-02-14 13:37:20 +0100 | [diff] [blame] | 15906 | tcp-request session set-var(txn.ipport) "str(),concat('addr=(',sess.ip),concat(',',sess.port,')')" |
Willy Tarreau | 280f42b | 2018-02-19 15:34:12 +0100 | [diff] [blame] | 15907 | http-request set-header x-hap-sig %[var(txn.sig)] |
| 15908 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15909 | cpl |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 15910 | Takes the input value of type signed integer, applies a ones-complement |
| 15911 | (flips all bits) and returns the result as an signed integer. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15912 | |
Willy Tarreau | 8059977 | 2015-01-20 19:35:24 +0100 | [diff] [blame] | 15913 | crc32([<avalanche>]) |
| 15914 | Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32 |
| 15915 | hash function. Optionally, it is possible to apply a full avalanche hash |
| 15916 | function to the output if the optional <avalanche> argument equals 1. This |
| 15917 | converter uses the same functions as used by the various hash-based load |
| 15918 | balancing algorithms, so it will provide exactly the same results. It is |
| 15919 | provided for compatibility with other software which want a CRC32 to be |
| 15920 | computed on some input keys, so it follows the most common implementation as |
| 15921 | found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms |
| 15922 | but may provide a better or at least less predictable distribution. It must |
| 15923 | not be used for security purposes as a 32-bit hash is trivial to break. See |
Emmanuel Hocdet | 50791a7 | 2018-03-21 11:19:01 +0100 | [diff] [blame] | 15924 | also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive. |
| 15925 | |
| 15926 | crc32c([<avalanche>]) |
| 15927 | Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C |
| 15928 | hash function. Optionally, it is possible to apply a full avalanche hash |
| 15929 | function to the output if the optional <avalanche> argument equals 1. This |
| 15930 | converter uses the same functions as described in RFC4960, Appendix B [8]. |
| 15931 | It is provided for compatibility with other software which want a CRC32C to be |
| 15932 | computed on some input keys. It is slower than the other algorithms and it must |
| 15933 | not be used for security purposes as a 32-bit hash is trivial to break. See |
| 15934 | also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive. |
Willy Tarreau | 8059977 | 2015-01-20 19:35:24 +0100 | [diff] [blame] | 15935 | |
Christopher Faulet | ea159d6 | 2020-04-01 16:21:44 +0200 | [diff] [blame] | 15936 | cut_crlf |
| 15937 | Cuts the string representation of the input sample on the first carriage |
| 15938 | return ('\r') or newline ('\n') character found. Only the string length is |
| 15939 | updated. |
| 15940 | |
David Carlier | 29b3ca3 | 2015-09-25 14:09:21 +0100 | [diff] [blame] | 15941 | da-csv-conv(<prop>[,<prop>*]) |
David Carlier | 4542b10 | 2015-06-01 13:54:29 +0200 | [diff] [blame] | 15942 | Asks the DeviceAtlas converter to identify the User Agent string passed on |
| 15943 | input, and to emit a string made of the concatenation of the properties |
| 15944 | enumerated in argument, delimited by the separator defined by the global |
| 15945 | keyword "deviceatlas-property-separator", or by default the pipe character |
David Carlier | 840b024 | 2016-03-16 10:09:55 +0000 | [diff] [blame] | 15946 | ('|'). There's a limit of 12 different properties imposed by the haproxy |
David Carlier | 4542b10 | 2015-06-01 13:54:29 +0200 | [diff] [blame] | 15947 | configuration language. |
| 15948 | |
| 15949 | Example: |
| 15950 | frontend www |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 15951 | bind *:8881 |
| 15952 | default_backend servers |
David Carlier | 840b024 | 2016-03-16 10:09:55 +0000 | [diff] [blame] | 15953 | http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)] |
David Carlier | 4542b10 | 2015-06-01 13:54:29 +0200 | [diff] [blame] | 15954 | |
Willy Tarreau | 0851fd5 | 2019-12-17 10:07:25 +0100 | [diff] [blame] | 15955 | debug([<prefix][,<destination>]) |
| 15956 | This converter is used as debug tool. It takes a capture of the input sample |
| 15957 | and sends it to event sink <destination>, which may designate a ring buffer |
| 15958 | such as "buf0", as well as "stdout", or "stderr". Available sinks may be |
| 15959 | checked at run time by issuing "show events" on the CLI. When not specified, |
| 15960 | the output will be "buf0", which may be consulted via the CLI's "show events" |
| 15961 | command. An optional prefix <prefix> may be passed to help distinguish |
| 15962 | outputs from multiple expressions. It will then appear before the colon in |
| 15963 | the output message. The input sample is passed as-is on the output, so that |
| 15964 | it is safe to insert the debug converter anywhere in a chain, even with non- |
| 15965 | printable sample types. |
| 15966 | |
| 15967 | Example: |
| 15968 | tcp-request connection track-sc0 src,debug(track-sc) |
Thierry FOURNIER | 9687c77 | 2015-05-07 15:46:29 +0200 | [diff] [blame] | 15969 | |
Patrick Gansterer | 8e36651 | 2020-04-22 16:47:57 +0200 | [diff] [blame] | 15970 | digest(<algorithm>) |
| 15971 | Converts a binary input sample to a message digest. The result is a binary |
| 15972 | sample. The <algorithm> must be an OpenSSL message digest name (e.g. sha256). |
| 15973 | |
| 15974 | Please note that this converter is only available when haproxy has been |
| 15975 | compiled with USE_OPENSSL. |
| 15976 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15977 | div(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 15978 | Divides the input value of type signed integer by <value>, and returns the |
| 15979 | result as an signed integer. If <value> is null, the largest unsigned |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 15980 | integer is returned (typically 2^63-1). <value> can be a numeric value or a |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 15981 | variable name. The name of the variable starts with an indication about its |
| 15982 | scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 15983 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 15984 | "sess" : the variable is shared with the whole session |
| 15985 | "txn" : the variable is shared with the transaction (request and response) |
| 15986 | "req" : the variable is shared only during request processing |
| 15987 | "res" : the variable is shared only during response processing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 15988 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 15989 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 15990 | |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 15991 | djb2([<avalanche>]) |
| 15992 | Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2 |
| 15993 | hash function. Optionally, it is possible to apply a full avalanche hash |
| 15994 | function to the output if the optional <avalanche> argument equals 1. This |
| 15995 | converter uses the same functions as used by the various hash-based load |
| 15996 | balancing algorithms, so it will provide exactly the same results. It is |
| 15997 | mostly intended for debugging, but can be used as a stick-table entry to |
| 15998 | collect rough statistics. It must not be used for security purposes as a |
Emmanuel Hocdet | 50791a7 | 2018-03-21 11:19:01 +0100 | [diff] [blame] | 15999 | 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c", |
| 16000 | and the "hash-type" directive. |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 16001 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16002 | even |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16003 | Returns a boolean TRUE if the input value of type signed integer is even |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16004 | otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool". |
| 16005 | |
Marcin Deranek | 9631a28 | 2018-04-16 14:30:46 +0200 | [diff] [blame] | 16006 | field(<index>,<delimiters>[,<count>]) |
| 16007 | Extracts the substring at the given index counting from the beginning |
| 16008 | (positive index) or from the end (negative index) considering given delimiters |
| 16009 | from an input string. Indexes start at 1 or -1 and delimiters are a string |
| 16010 | formatted list of chars. Optionally you can specify <count> of fields to |
| 16011 | extract (default: 1). Value of 0 indicates extraction of all remaining |
| 16012 | fields. |
| 16013 | |
| 16014 | Example : |
| 16015 | str(f1_f2_f3__f5),field(5,_) # f5 |
| 16016 | str(f1_f2_f3__f5),field(2,_,0) # f2_f3__f5 |
| 16017 | str(f1_f2_f3__f5),field(2,_,2) # f2_f3 |
| 16018 | str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_ |
| 16019 | str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3 |
Emeric Brun | f399b0d | 2014-11-03 17:07:03 +0100 | [diff] [blame] | 16020 | |
Baptiste Assmann | e138dda | 2020-10-22 15:39:03 +0200 | [diff] [blame] | 16021 | fix_is_valid |
| 16022 | Parses a binary payload and performs sanity checks regarding FIX (Financial |
| 16023 | Information eXchange): |
| 16024 | |
| 16025 | - checks that all tag IDs and values are not empty and the tags IDs are well |
| 16026 | numeric |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 16027 | - checks the BeginString tag is the first tag with a valid FIX version |
Baptiste Assmann | e138dda | 2020-10-22 15:39:03 +0200 | [diff] [blame] | 16028 | - checks the BodyLength tag is the second one with the right body length |
Christopher Faulet | ed4bef7 | 2021-03-18 17:40:56 +0100 | [diff] [blame] | 16029 | - checks the MsgType tag is the third tag. |
Baptiste Assmann | e138dda | 2020-10-22 15:39:03 +0200 | [diff] [blame] | 16030 | - checks that last tag in the message is the CheckSum tag with a valid |
| 16031 | checksum |
| 16032 | |
| 16033 | Due to current HAProxy design, only the first message sent by the client and |
| 16034 | the server can be parsed. |
| 16035 | |
| 16036 | This converter returns a boolean, true if the payload contains a valid FIX |
| 16037 | message, false if not. |
| 16038 | |
| 16039 | See also the fix_tag_value converter. |
| 16040 | |
| 16041 | Example: |
| 16042 | tcp-request inspect-delay 10s |
| 16043 | tcp-request content reject unless { req.payload(0,0),fix_is_valid } |
| 16044 | |
| 16045 | fix_tag_value(<tag>) |
| 16046 | Parses a FIX (Financial Information eXchange) message and extracts the value |
| 16047 | from the tag <tag>. <tag> can be a string or an integer pointing to the |
| 16048 | desired tag. Any integer value is accepted, but only the following strings |
| 16049 | are translated into their integer equivalent: BeginString, BodyLength, |
Daniel Corbett | befef70 | 2021-03-09 23:00:34 -0500 | [diff] [blame] | 16050 | MsgType, SenderCompID, TargetCompID, CheckSum. More tag names can be easily |
Baptiste Assmann | e138dda | 2020-10-22 15:39:03 +0200 | [diff] [blame] | 16051 | added. |
| 16052 | |
| 16053 | Due to current HAProxy design, only the first message sent by the client and |
| 16054 | the server can be parsed. No message validation is performed by this |
| 16055 | converter. It is highly recommended to validate the message first using |
| 16056 | fix_is_valid converter. |
| 16057 | |
| 16058 | See also the fix_is_valid converter. |
| 16059 | |
| 16060 | Example: |
| 16061 | tcp-request inspect-delay 10s |
| 16062 | tcp-request content reject unless { req.payload(0,0),fix_is_valid } |
| 16063 | # MsgType tag ID is 35, so both lines below will return the same content |
| 16064 | tcp-request content set-var(txn.foo) req.payload(0,0),fix_tag_value(35) |
| 16065 | tcp-request content set-var(txn.bar) req.payload(0,0),fix_tag_value(MsgType) |
| 16066 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16067 | hex |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16068 | Converts a binary input sample to a hex string containing two hex digits per |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16069 | input byte. It is used to log or transfer hex dumps of some binary input data |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16070 | in a way that can be reliably transferred (e.g. an SSL ID can be copied in a |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16071 | header). |
Thierry FOURNIER | 2f49d6d | 2014-03-12 15:01:52 +0100 | [diff] [blame] | 16072 | |
Dragan Dosen | 3f957b2 | 2017-10-24 09:27:34 +0200 | [diff] [blame] | 16073 | hex2i |
| 16074 | Converts a hex string containing two hex digits per input byte to an |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 16075 | integer. If the input value cannot be converted, then zero is returned. |
Dragan Dosen | 3f957b2 | 2017-10-24 09:27:34 +0200 | [diff] [blame] | 16076 | |
Christopher Faulet | 4ccc12f | 2020-04-01 09:08:32 +0200 | [diff] [blame] | 16077 | htonl |
| 16078 | Converts the input integer value to its 32-bit binary representation in the |
| 16079 | network byte order. Because sample fetches own signed 64-bit integer, when |
| 16080 | this converter is used, the input integer value is first casted to an |
| 16081 | unsigned 32-bit integer. |
| 16082 | |
Tim Duesterhus | a308209 | 2021-01-21 17:40:49 +0100 | [diff] [blame] | 16083 | hmac(<algorithm>,<key>) |
Patrick Gansterer | 8e36651 | 2020-04-22 16:47:57 +0200 | [diff] [blame] | 16084 | Converts a binary input sample to a message authentication code with the given |
| 16085 | key. The result is a binary sample. The <algorithm> must be one of the |
| 16086 | registered OpenSSL message digest names (e.g. sha256). The <key> parameter must |
| 16087 | be base64 encoded and can either be a string or a variable. |
| 16088 | |
| 16089 | Please note that this converter is only available when haproxy has been |
| 16090 | compiled with USE_OPENSSL. |
| 16091 | |
Cyril Bonté | 6bcd182 | 2019-11-05 23:13:59 +0100 | [diff] [blame] | 16092 | http_date([<offset],[<unit>]) |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16093 | Converts an integer supposed to contain a date since epoch to a string |
| 16094 | representing this date in a format suitable for use in HTTP header fields. If |
Damien Claisse | ae6f125 | 2019-10-30 15:57:28 +0000 | [diff] [blame] | 16095 | an offset value is specified, then it is added to the date before the |
| 16096 | conversion is operated. This is particularly useful to emit Date header fields, |
| 16097 | Expires values in responses when combined with a positive offset, or |
| 16098 | Last-Modified values when the offset is negative. |
| 16099 | If a unit value is specified, then consider the timestamp as either |
| 16100 | "s" for seconds (default behavior), "ms" for milliseconds, or "us" for |
| 16101 | microseconds since epoch. Offset is assumed to have the same unit as |
| 16102 | input timestamp. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 16103 | |
Tim Duesterhus | 3943e4f | 2020-09-11 14:25:23 +0200 | [diff] [blame] | 16104 | iif(<true>,<false>) |
| 16105 | Returns the <true> string if the input value is true. Returns the <false> |
| 16106 | string otherwise. |
| 16107 | |
| 16108 | Example: |
Tim Duesterhus | 870713b | 2020-09-11 17:13:12 +0200 | [diff] [blame] | 16109 | http-request set-header x-forwarded-proto %[ssl_fc,iif(https,http)] |
Tim Duesterhus | 3943e4f | 2020-09-11 14:25:23 +0200 | [diff] [blame] | 16110 | |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16111 | in_table(<table>) |
| 16112 | Uses the string representation of the input sample to perform a look up in |
| 16113 | the specified table. If the key is not found in the table, a boolean false |
| 16114 | is returned. Otherwise a boolean true is returned. This can be used to verify |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16115 | the presence of a certain key in a table tracking some elements (e.g. whether |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16116 | or not a source IP address or an Authorization header was already seen). |
| 16117 | |
Tim Duesterhus | a308209 | 2021-01-21 17:40:49 +0100 | [diff] [blame] | 16118 | ipmask(<mask4>,[<mask6>]) |
Tim Duesterhus | 1478aa7 | 2018-01-25 16:24:51 +0100 | [diff] [blame] | 16119 | Apply a mask to an IP address, and use the result for lookups and storage. |
Willy Tarreau | ffcb2e4 | 2014-07-10 16:29:08 +0200 | [diff] [blame] | 16120 | This can be used to make all hosts within a certain mask to share the same |
Tim Duesterhus | 1478aa7 | 2018-01-25 16:24:51 +0100 | [diff] [blame] | 16121 | table entries and as such use the same server. The mask4 can be passed in |
| 16122 | dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can |
| 16123 | be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64). |
| 16124 | If no mask6 is given IPv6 addresses will fail to convert for backwards |
| 16125 | compatibility reasons. |
Willy Tarreau | ffcb2e4 | 2014-07-10 16:29:08 +0200 | [diff] [blame] | 16126 | |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16127 | json([<input-code>]) |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16128 | Escapes the input string and produces an ASCII output string ready to use as a |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16129 | JSON string. The converter tries to decode the input string according to the |
Herve COMMOWICK | 8dfe863 | 2016-08-05 12:01:20 +0200 | [diff] [blame] | 16130 | <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16131 | "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types |
| 16132 | of errors: |
| 16133 | - bad UTF-8 sequence (lone continuation byte, bad number of continuation |
| 16134 | bytes, ...) |
| 16135 | - invalid range (the decoded value is within a UTF-8 prohibited range), |
| 16136 | - code overlong (the value is encoded with more bytes than necessary). |
| 16137 | |
| 16138 | The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8 |
| 16139 | character is greater than 0xffff because the JSON string escape specification |
| 16140 | only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists |
| 16141 | in 4 variants designated by a combination of two suffix letters : "p" for |
| 16142 | "permissive" and "s" for "silently ignore". The behaviors of the decoders |
| 16143 | are : |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16144 | - "ascii" : never fails; |
| 16145 | - "utf8" : fails on any detected errors; |
| 16146 | - "utf8s" : never fails, but removes characters corresponding to errors; |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16147 | - "utf8p" : accepts and fixes the overlong errors, but fails on any other |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16148 | error; |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16149 | - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes |
| 16150 | characters corresponding to the other errors. |
| 16151 | |
| 16152 | This converter is particularly useful for building properly escaped JSON for |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16153 | logging to servers which consume JSON-formatted traffic logs. |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16154 | |
| 16155 | Example: |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16156 | capture request header Host len 15 |
Herve COMMOWICK | 8dfe863 | 2016-08-05 12:01:20 +0200 | [diff] [blame] | 16157 | capture request header user-agent len 150 |
| 16158 | log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}' |
Thierry FOURNIER | 317e1c4 | 2014-08-12 10:20:47 +0200 | [diff] [blame] | 16159 | |
| 16160 | Input request from client 127.0.0.1: |
| 16161 | GET / HTTP/1.0 |
| 16162 | User-Agent: Very "Ugly" UA 1/2 |
| 16163 | |
| 16164 | Output log: |
| 16165 | {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"} |
| 16166 | |
Alex | 51c8ad4 | 2021-04-15 16:45:15 +0200 | [diff] [blame] | 16167 | json_query(<json_path>,[<output_type>]) |
| 16168 | The json_query converter supports the JSON types string, boolean and |
| 16169 | number. Floating point numbers will be returned as a string. By |
| 16170 | specifying the output_type 'int' the value will be converted to an |
| 16171 | Integer. If conversion is not possible the json_query converter fails. |
| 16172 | |
| 16173 | <json_path> must be a valid JSON Path string as defined in |
| 16174 | https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/ |
| 16175 | |
| 16176 | Example: |
| 16177 | # get a integer value from the request body |
| 16178 | # "{"integer":4}" => 5 |
| 16179 | http-request set-var(txn.pay_int) req.body,json_query('$.integer','int'),add(1) |
| 16180 | |
| 16181 | # get a key with '.' in the name |
| 16182 | # {"my.key":"myvalue"} => myvalue |
| 16183 | http-request set-var(txn.pay_mykey) req.body,json_query('$.my\\.key') |
| 16184 | |
| 16185 | # {"boolean-false":false} => 0 |
| 16186 | http-request set-var(txn.pay_boolean_false) req.body,json_query('$.boolean-false') |
| 16187 | |
| 16188 | # get the value of the key 'iss' from a JWT Bearer token |
| 16189 | http-request set-var(txn.token_payload) req.hdr(Authorization),word(2,.),ub64dec,json_query('$.iss') |
| 16190 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16191 | language(<value>[,<default>]) |
| 16192 | Returns the value with the highest q-factor from a list as extracted from the |
| 16193 | "accept-language" header using "req.fhdr". Values with no q-factor have a |
| 16194 | q-factor of 1. Values with a q-factor of 0 are dropped. Only values which |
| 16195 | belong to the list of semi-colon delimited <values> will be considered. The |
| 16196 | argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the |
| 16197 | given list and a default value is provided, it is returned. Note that language |
| 16198 | names may have a variant after a dash ('-'). If this variant is present in the |
| 16199 | list, it will be matched, but if it is not, only the base language is checked. |
| 16200 | The match is case-sensitive, and the output string is always one of those |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16201 | provided in arguments. The ordering of arguments is meaningless, only the |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16202 | ordering of the values in the request counts, as the first value among |
| 16203 | multiple sharing the same q-factor is used. |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 16204 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16205 | Example : |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 16206 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16207 | # this configuration switches to the backend matching a |
| 16208 | # given language based on the request : |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 16209 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16210 | acl es req.fhdr(accept-language),language(es;fr;en) -m str es |
| 16211 | acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr |
| 16212 | acl en req.fhdr(accept-language),language(es;fr;en) -m str en |
| 16213 | use_backend spanish if es |
| 16214 | use_backend french if fr |
| 16215 | use_backend english if en |
| 16216 | default_backend choose_your_language |
Thierry FOURNIER | ad90351 | 2014-04-11 17:51:01 +0200 | [diff] [blame] | 16217 | |
Willy Tarreau | 60a2ee7 | 2017-12-15 07:13:48 +0100 | [diff] [blame] | 16218 | length |
Etienne Carriere | ed0d24e | 2017-12-13 13:41:34 +0100 | [diff] [blame] | 16219 | Get the length of the string. This can only be placed after a string |
| 16220 | sample fetch function or after a transformation keyword returning a string |
| 16221 | type. The result is of type integer. |
| 16222 | |
Willy Tarreau | ffcb2e4 | 2014-07-10 16:29:08 +0200 | [diff] [blame] | 16223 | lower |
| 16224 | Convert a string sample to lower case. This can only be placed after a string |
| 16225 | sample fetch function or after a transformation keyword returning a string |
| 16226 | type. The result is of type string. |
| 16227 | |
Willy Tarreau | 0dbfdba | 2014-07-10 16:37:47 +0200 | [diff] [blame] | 16228 | ltime(<format>[,<offset>]) |
| 16229 | Converts an integer supposed to contain a date since epoch to a string |
| 16230 | representing this date in local time using a format defined by the <format> |
| 16231 | string using strftime(3). The purpose is to allow any date format to be used |
| 16232 | in logs. An optional <offset> in seconds may be applied to the input date |
| 16233 | (positive or negative). See the strftime() man page for the format supported |
| 16234 | by your operating system. See also the utime converter. |
| 16235 | |
| 16236 | Example : |
| 16237 | |
| 16238 | # Emit two colons, one with the local time and another with ip:port |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16239 | # e.g. 20140710162350 127.0.0.1:57325 |
Willy Tarreau | 0dbfdba | 2014-07-10 16:37:47 +0200 | [diff] [blame] | 16240 | log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp |
| 16241 | |
Christopher Faulet | 51fc9d1 | 2020-04-01 17:24:41 +0200 | [diff] [blame] | 16242 | ltrim(<chars>) |
| 16243 | Skips any characters from <chars> from the beginning of the string |
| 16244 | representation of the input sample. |
| 16245 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16246 | map(<map_file>[,<default_value>]) |
| 16247 | map_<match_type>(<map_file>[,<default_value>]) |
| 16248 | map_<match_type>_<output_type>(<map_file>[,<default_value>]) |
| 16249 | Search the input value from <map_file> using the <match_type> matching method, |
| 16250 | and return the associated value converted to the type <output_type>. If the |
| 16251 | input value cannot be found in the <map_file>, the converter returns the |
| 16252 | <default_value>. If the <default_value> is not set, the converter fails and |
| 16253 | acts as if no input value could be fetched. If the <match_type> is not set, it |
| 16254 | defaults to "str". Likewise, if the <output_type> is not set, it defaults to |
| 16255 | "str". For convenience, the "map" keyword is an alias for "map_str" and maps a |
| 16256 | string to another string. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 16257 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16258 | It is important to avoid overlapping between the keys : IP addresses and |
| 16259 | strings are stored in trees, so the first of the finest match will be used. |
| 16260 | 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] | 16261 | |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 16262 | The following array contains the list of all map functions available sorted by |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16263 | input type, match type and output type. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 16264 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16265 | input type | match method | output type str | output type int | output type ip |
| 16266 | -----------+--------------+-----------------+-----------------+--------------- |
| 16267 | str | str | map_str | map_str_int | map_str_ip |
| 16268 | -----------+--------------+-----------------+-----------------+--------------- |
Willy Tarreau | 787a4c0 | 2014-05-10 07:55:30 +0200 | [diff] [blame] | 16269 | str | beg | map_beg | map_beg_int | map_end_ip |
| 16270 | -----------+--------------+-----------------+-----------------+--------------- |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16271 | str | sub | map_sub | map_sub_int | map_sub_ip |
| 16272 | -----------+--------------+-----------------+-----------------+--------------- |
| 16273 | str | dir | map_dir | map_dir_int | map_dir_ip |
| 16274 | -----------+--------------+-----------------+-----------------+--------------- |
| 16275 | str | dom | map_dom | map_dom_int | map_dom_ip |
| 16276 | -----------+--------------+-----------------+-----------------+--------------- |
| 16277 | str | end | map_end | map_end_int | map_end_ip |
| 16278 | -----------+--------------+-----------------+-----------------+--------------- |
Ruoshan Huang | 3c5e374 | 2016-12-02 16:25:31 +0800 | [diff] [blame] | 16279 | str | reg | map_reg | map_reg_int | map_reg_ip |
| 16280 | -----------+--------------+-----------------+-----------------+--------------- |
| 16281 | str | reg | map_regm | map_reg_int | map_reg_ip |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16282 | -----------+--------------+-----------------+-----------------+--------------- |
| 16283 | int | int | map_int | map_int_int | map_int_ip |
| 16284 | -----------+--------------+-----------------+-----------------+--------------- |
| 16285 | ip | ip | map_ip | map_ip_int | map_ip_ip |
| 16286 | -----------+--------------+-----------------+-----------------+--------------- |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 16287 | |
Thierry Fournier | 8feaa66 | 2016-02-10 22:55:20 +0100 | [diff] [blame] | 16288 | The special map called "map_regm" expect matching zone in the regular |
| 16289 | expression and modify the output replacing back reference (like "\1") by |
| 16290 | the corresponding match text. |
| 16291 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16292 | The file contains one key + value per line. Lines which start with '#' are |
| 16293 | ignored, just like empty lines. Leading tabs and spaces are stripped. The key |
| 16294 | is then the first "word" (series of non-space/tabs characters), and the value |
| 16295 | is what follows this series of space/tab till the end of the line excluding |
| 16296 | trailing spaces/tabs. |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 16297 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16298 | Example : |
| 16299 | |
| 16300 | # this is a comment and is ignored |
| 16301 | 2.22.246.0/23 United Kingdom \n |
| 16302 | <-><-----------><--><------------><----> |
| 16303 | | | | | `- trailing spaces ignored |
| 16304 | | | | `---------- value |
| 16305 | | | `-------------------- middle spaces ignored |
| 16306 | | `---------------------------- key |
| 16307 | `------------------------------------ leading spaces ignored |
| 16308 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16309 | mod(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16310 | Divides the input value of type signed integer by <value>, and returns the |
| 16311 | remainder as an signed integer. If <value> is null, then zero is returned. |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16312 | <value> can be a numeric value or a variable name. The name of the variable |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16313 | starts with an indication about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 16314 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16315 | "sess" : the variable is shared with the whole session |
| 16316 | "txn" : the variable is shared with the transaction (request and response) |
| 16317 | "req" : the variable is shared only during request processing |
| 16318 | "res" : the variable is shared only during response processing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16319 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 16320 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16321 | |
Alex | bf1bd5a | 2021-04-24 13:02:21 +0200 | [diff] [blame] | 16322 | mqtt_field_value(<packettype>,<fieldname_or_property_ID>) |
Baptiste Assmann | e279ca6 | 2020-10-27 18:10:06 +0100 | [diff] [blame] | 16323 | Returns value of <fieldname> found in input MQTT payload of type |
| 16324 | <packettype>. |
| 16325 | <packettype> can be either a string (case insensitive matching) or a numeric |
| 16326 | value corresponding to the type of packet we're supposed to extract data |
| 16327 | from. |
| 16328 | Supported string and integers can be found here: |
| 16329 | https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718021 |
| 16330 | https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901022 |
| 16331 | |
| 16332 | <fieldname> depends on <packettype> and can be any of the following below. |
| 16333 | (note that <fieldname> matching is case insensitive). |
| 16334 | <property id> can only be found in MQTT v5.0 streams. check this table: |
| 16335 | https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901029 |
| 16336 | |
| 16337 | - CONNECT (or 1): flags, protocol_name, protocol_version, client_identifier, |
| 16338 | will_topic, will_payload, username, password, keepalive |
| 16339 | OR any property ID as a numeric value (for MQTT v5.0 |
| 16340 | packets only): |
| 16341 | 17: Session Expiry Interval |
| 16342 | 33: Receive Maximum |
| 16343 | 39: Maximum Packet Size |
| 16344 | 34: Topic Alias Maximum |
| 16345 | 25: Request Response Information |
| 16346 | 23: Request Problem Information |
| 16347 | 21: Authentication Method |
| 16348 | 22: Authentication Data |
| 16349 | 18: Will Delay Interval |
| 16350 | 1: Payload Format Indicator |
| 16351 | 2: Message Expiry Interval |
| 16352 | 3: Content Type |
| 16353 | 8: Response Topic |
| 16354 | 9: Correlation Data |
| 16355 | Not supported yet: |
| 16356 | 38: User Property |
| 16357 | |
| 16358 | - CONNACK (or 2): flags, protocol_version, reason_code |
| 16359 | OR any property ID as a numeric value (for MQTT v5.0 |
| 16360 | packets only): |
| 16361 | 17: Session Expiry Interval |
| 16362 | 33: Receive Maximum |
| 16363 | 36: Maximum QoS |
| 16364 | 37: Retain Available |
| 16365 | 39: Maximum Packet Size |
| 16366 | 18: Assigned Client Identifier |
| 16367 | 34: Topic Alias Maximum |
| 16368 | 31: Reason String |
| 16369 | 40; Wildcard Subscription Available |
| 16370 | 41: Subscription Identifiers Available |
| 16371 | 42: Shared Subscription Available |
| 16372 | 19: Server Keep Alive |
| 16373 | 26: Response Information |
| 16374 | 28: Server Reference |
| 16375 | 21: Authentication Method |
| 16376 | 22: Authentication Data |
| 16377 | Not supported yet: |
| 16378 | 38: User Property |
| 16379 | |
| 16380 | Due to current HAProxy design, only the first message sent by the client and |
| 16381 | the server can be parsed. Thus this converter can extract data only from |
| 16382 | CONNECT and CONNACK packet types. CONNECT is the first message sent by the |
| 16383 | client and CONNACK is the first response sent by the server. |
| 16384 | |
| 16385 | Example: |
| 16386 | |
| 16387 | acl data_in_buffer req.len ge 4 |
| 16388 | tcp-request content set-var(txn.username) \ |
| 16389 | req.payload(0,0),mqtt_field_value(connect,protocol_name) \ |
| 16390 | if data_in_buffer |
| 16391 | # do the same as above |
| 16392 | tcp-request content set-var(txn.username) \ |
| 16393 | req.payload(0,0),mqtt_field_value(1,protocol_name) \ |
| 16394 | if data_in_buffer |
| 16395 | |
| 16396 | mqtt_is_valid |
| 16397 | Checks that the binary input is a valid MQTT packet. It returns a boolean. |
| 16398 | |
| 16399 | Due to current HAProxy design, only the first message sent by the client and |
| 16400 | the server can be parsed. Thus this converter can extract data only from |
| 16401 | CONNECT and CONNACK packet types. CONNECT is the first message sent by the |
| 16402 | client and CONNACK is the first response sent by the server. |
| 16403 | |
| 16404 | Example: |
| 16405 | |
| 16406 | acl data_in_buffer req.len ge 4 |
| 16407 | tcp-request content reject unless req.payload(0,0),mqtt_is_valid |
| 16408 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16409 | mul(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16410 | Multiplies the input value of type signed integer by <value>, and returns |
Thierry FOURNIER | 00c005c | 2015-07-08 01:10:21 +0200 | [diff] [blame] | 16411 | the product as an signed integer. In case of overflow, the largest possible |
| 16412 | value for the sign is returned so that the operation doesn't wrap around. |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16413 | <value> can be a numeric value or a variable name. The name of the variable |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16414 | starts with an indication about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 16415 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16416 | "sess" : the variable is shared with the whole session |
| 16417 | "txn" : the variable is shared with the transaction (request and response) |
| 16418 | "req" : the variable is shared only during request processing |
| 16419 | "res" : the variable is shared only during response processing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16420 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 16421 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16422 | |
Nenad Merdanovic | b7e7c47 | 2017-03-12 21:56:55 +0100 | [diff] [blame] | 16423 | nbsrv |
| 16424 | Takes an input value of type string, interprets it as a backend name and |
| 16425 | returns the number of usable servers in that backend. Can be used in places |
| 16426 | where we want to look up a backend from a dynamic name, like a result of a |
| 16427 | map lookup. |
| 16428 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16429 | neg |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16430 | Takes the input value of type signed integer, computes the opposite value, |
| 16431 | and returns the remainder as an signed integer. 0 is identity. This operator |
| 16432 | is provided for reversed subtracts : in order to subtract the input from a |
| 16433 | constant, simply perform a "neg,add(value)". |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16434 | |
| 16435 | not |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16436 | Returns a boolean FALSE if the input value of type signed integer is |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16437 | non-null, otherwise returns TRUE. Used in conjunction with and(), it can be |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16438 | used to report true/false for bit testing on input values (e.g. verify the |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16439 | absence of a flag). |
| 16440 | |
| 16441 | odd |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16442 | Returns a boolean TRUE if the input value of type signed integer is odd |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16443 | otherwise returns FALSE. It is functionally equivalent to "and(1),bool". |
| 16444 | |
| 16445 | or(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16446 | Performs a bitwise "OR" between <value> and the input value of type signed |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16447 | integer, and returns the result as an signed integer. <value> can be a |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16448 | numeric value or a variable name. The name of the variable starts with an |
| 16449 | indication about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 16450 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16451 | "sess" : the variable is shared with the whole session |
| 16452 | "txn" : the variable is shared with the transaction (request and response) |
| 16453 | "req" : the variable is shared only during request processing |
| 16454 | "res" : the variable is shared only during response processing |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16455 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 16456 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16457 | |
Frédéric Lécaille | bfe6138 | 2019-03-06 14:34:36 +0100 | [diff] [blame] | 16458 | protobuf(<field_number>,[<field_type>]) |
| 16459 | This extracts the protocol buffers message field in raw mode of an input binary |
| 16460 | sample representation of a protocol buffer message with <field_number> as field |
| 16461 | number (dotted notation) if <field_type> is not present, or as an integer sample |
| 16462 | if this field is present (see also "ungrpc" below). |
| 16463 | The list of the authorized types is the following one: "int32", "int64", "uint32", |
| 16464 | "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0 |
| 16465 | "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32", |
| 16466 | "float" for the wire type 5. Note that "string" is considered as a length-delimited |
| 16467 | type, so it does not require any <field_type> argument to be extracted. |
| 16468 | More information may be found here about the protocol buffers message field types: |
| 16469 | https://developers.google.com/protocol-buffers/docs/encoding |
| 16470 | |
Willy Tarreau | c4dc350 | 2015-01-23 20:39:28 +0100 | [diff] [blame] | 16471 | regsub(<regex>,<subst>[,<flags>]) |
Willy Tarreau | 7eda849 | 2015-01-20 19:47:06 +0100 | [diff] [blame] | 16472 | Applies a regex-based substitution to the input string. It does the same |
| 16473 | operation as the well-known "sed" utility with "s/<regex>/<subst>/". By |
| 16474 | default it will replace in the input string the first occurrence of the |
| 16475 | largest part matching the regular expression <regex> with the substitution |
| 16476 | string <subst>. It is possible to replace all occurrences instead by adding |
| 16477 | the flag "g" in the third argument <flags>. It is also possible to make the |
| 16478 | regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a |
| 16479 | string, it is made up from the concatenation of all desired flags. Thus if |
| 16480 | both "i" and "g" are desired, using "gi" or "ig" will have the same effect. |
Willy Tarreau | ef21fac | 2020-02-14 13:37:20 +0100 | [diff] [blame] | 16481 | The first use of this converter is to replace certain characters or sequence |
| 16482 | of characters with other ones. |
| 16483 | |
| 16484 | It is highly recommended to enclose the regex part using protected quotes to |
| 16485 | improve clarity and never have a closing parenthesis from the regex mixed up |
| 16486 | with the parenthesis from the function. Just like in Bourne shell, the first |
| 16487 | level of quotes is processed when delimiting word groups on the line, a |
| 16488 | second level is usable for argument. It is recommended to use single quotes |
| 16489 | outside since these ones do not try to resolve backslashes nor dollar signs. |
Willy Tarreau | 7eda849 | 2015-01-20 19:47:06 +0100 | [diff] [blame] | 16490 | |
Willy Tarreau | cd0d2ed | 2020-02-14 17:33:06 +0100 | [diff] [blame] | 16491 | Examples: |
Willy Tarreau | 7eda849 | 2015-01-20 19:47:06 +0100 | [diff] [blame] | 16492 | |
| 16493 | # de-duplicate "/" in header "x-path". |
| 16494 | # input: x-path: /////a///b/c/xzxyz/ |
| 16495 | # output: x-path: /a/b/c/xzxyz/ |
Willy Tarreau | ef21fac | 2020-02-14 13:37:20 +0100 | [diff] [blame] | 16496 | http-request set-header x-path "%[hdr(x-path),regsub('/+','/','g')]" |
Willy Tarreau | 7eda849 | 2015-01-20 19:47:06 +0100 | [diff] [blame] | 16497 | |
Willy Tarreau | cd0d2ed | 2020-02-14 17:33:06 +0100 | [diff] [blame] | 16498 | # copy query string to x-query and drop all leading '?', ';' and '&' |
| 16499 | http-request set-header x-query "%[query,regsub([?;&]*,'')]" |
| 16500 | |
Jerome Magnin | 07e1e3c | 2020-02-16 19:20:19 +0100 | [diff] [blame] | 16501 | # capture groups and backreferences |
| 16502 | # both lines do the same. |
Willy Tarreau | 465dc7d | 2020-10-08 18:05:56 +0200 | [diff] [blame] | 16503 | http-request redirect location %[url,'regsub("(foo|bar)([0-9]+)?","\2\1",i)'] |
Jerome Magnin | 07e1e3c | 2020-02-16 19:20:19 +0100 | [diff] [blame] | 16504 | http-request redirect location %[url,regsub(\"(foo|bar)([0-9]+)?\",\"\2\1\",i)] |
| 16505 | |
Thierry FOURNIER | 35ab275 | 2015-05-28 13:22:03 +0200 | [diff] [blame] | 16506 | capture-req(<id>) |
| 16507 | Capture the string entry in the request slot <id> and returns the entry as |
| 16508 | is. If the slot doesn't exist, the capture fails silently. |
| 16509 | |
| 16510 | See also: "declare capture", "http-request capture", |
Baptiste Assmann | 5ac425c | 2015-10-21 23:13:46 +0200 | [diff] [blame] | 16511 | "http-response capture", "capture.req.hdr" and |
| 16512 | "capture.res.hdr" (sample fetches). |
Thierry FOURNIER | 35ab275 | 2015-05-28 13:22:03 +0200 | [diff] [blame] | 16513 | |
| 16514 | capture-res(<id>) |
| 16515 | Capture the string entry in the response slot <id> and returns the entry as |
| 16516 | is. If the slot doesn't exist, the capture fails silently. |
| 16517 | |
| 16518 | See also: "declare capture", "http-request capture", |
Baptiste Assmann | 5ac425c | 2015-10-21 23:13:46 +0200 | [diff] [blame] | 16519 | "http-response capture", "capture.req.hdr" and |
| 16520 | "capture.res.hdr" (sample fetches). |
Thierry FOURNIER | 35ab275 | 2015-05-28 13:22:03 +0200 | [diff] [blame] | 16521 | |
Christopher Faulet | 568415a | 2020-04-01 17:24:47 +0200 | [diff] [blame] | 16522 | rtrim(<chars>) |
| 16523 | Skips any characters from <chars> from the end of the string representation |
| 16524 | of the input sample. |
| 16525 | |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 16526 | sdbm([<avalanche>]) |
| 16527 | Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM |
| 16528 | hash function. Optionally, it is possible to apply a full avalanche hash |
| 16529 | function to the output if the optional <avalanche> argument equals 1. This |
| 16530 | converter uses the same functions as used by the various hash-based load |
| 16531 | balancing algorithms, so it will provide exactly the same results. It is |
| 16532 | mostly intended for debugging, but can be used as a stick-table entry to |
| 16533 | collect rough statistics. It must not be used for security purposes as a |
Emmanuel Hocdet | 50791a7 | 2018-03-21 11:19:01 +0100 | [diff] [blame] | 16534 | 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c", |
| 16535 | and the "hash-type" directive. |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 16536 | |
Tim Duesterhus | f38175c | 2020-06-09 11:48:42 +0200 | [diff] [blame] | 16537 | secure_memcmp(<var>) |
| 16538 | Compares the contents of <var> with the input value. Both values are treated |
| 16539 | as a binary string. Returns a boolean indicating whether both binary strings |
| 16540 | match. |
| 16541 | |
| 16542 | If both binary strings have the same length then the comparison will be |
| 16543 | performed in constant time. |
| 16544 | |
| 16545 | Please note that this converter is only available when haproxy has been |
| 16546 | compiled with USE_OPENSSL. |
| 16547 | |
| 16548 | Example : |
| 16549 | |
| 16550 | http-request set-var(txn.token) hdr(token) |
| 16551 | # Check whether the token sent by the client matches the secret token |
| 16552 | # value, without leaking the contents using a timing attack. |
| 16553 | acl token_given str(my_secret_token),secure_memcmp(txn.token) |
| 16554 | |
Tim Duesterhus | ef4e45c | 2021-01-21 17:40:50 +0100 | [diff] [blame] | 16555 | set-var(<var>) |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16556 | Sets a variable with the input content and returns the content on the output |
| 16557 | as-is. The variable keeps the value and the associated input type. The name of |
| 16558 | the variable starts with an indication about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 16559 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16560 | "sess" : the variable is shared with the whole session |
| 16561 | "txn" : the variable is shared with the transaction (request and |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 16562 | response), |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16563 | "req" : the variable is shared only during request processing, |
| 16564 | "res" : the variable is shared only during response processing. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 16565 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 16566 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 16567 | |
Dragan Dosen | 6e5a9ca | 2017-10-24 09:18:23 +0200 | [diff] [blame] | 16568 | sha1 |
Tim Duesterhus | d437630 | 2019-06-17 12:41:44 +0200 | [diff] [blame] | 16569 | Converts a binary input sample to a SHA-1 digest. The result is a binary |
Dragan Dosen | 6e5a9ca | 2017-10-24 09:18:23 +0200 | [diff] [blame] | 16570 | sample with length of 20 bytes. |
| 16571 | |
Tim Duesterhus | d437630 | 2019-06-17 12:41:44 +0200 | [diff] [blame] | 16572 | sha2([<bits>]) |
| 16573 | Converts a binary input sample to a digest in the SHA-2 family. The result |
| 16574 | is a binary sample with length of <bits>/8 bytes. |
| 16575 | |
| 16576 | Valid values for <bits> are 224, 256, 384, 512, each corresponding to |
| 16577 | SHA-<bits>. The default value is 256. |
| 16578 | |
| 16579 | Please note that this converter is only available when haproxy has been |
| 16580 | compiled with USE_OPENSSL. |
| 16581 | |
Nenad Merdanovic | 177adc9 | 2019-08-27 01:58:13 +0200 | [diff] [blame] | 16582 | srv_queue |
| 16583 | Takes an input value of type string, either a server name or <backend>/<server> |
| 16584 | format and returns the number of queued sessions on that server. Can be used |
| 16585 | in places where we want to look up queued sessions from a dynamic name, like a |
| 16586 | cookie value (e.g. req.cook(SRVID),srv_queue) and then make a decision to break |
| 16587 | persistence or direct a request elsewhere. |
| 16588 | |
Tim Duesterhus | ca097c1 | 2018-04-27 21:18:45 +0200 | [diff] [blame] | 16589 | strcmp(<var>) |
| 16590 | Compares the contents of <var> with the input value of type string. Returns |
| 16591 | the result as a signed integer compatible with strcmp(3): 0 if both strings |
| 16592 | are identical. A value less than 0 if the left string is lexicographically |
| 16593 | smaller than the right string or if the left string is shorter. A value greater |
| 16594 | than 0 otherwise (right string greater than left string or the right string is |
| 16595 | shorter). |
| 16596 | |
Tim Duesterhus | f38175c | 2020-06-09 11:48:42 +0200 | [diff] [blame] | 16597 | See also the secure_memcmp converter if you need to compare two binary |
| 16598 | strings in constant time. |
| 16599 | |
Tim Duesterhus | ca097c1 | 2018-04-27 21:18:45 +0200 | [diff] [blame] | 16600 | Example : |
| 16601 | |
| 16602 | http-request set-var(txn.host) hdr(host) |
| 16603 | # Check whether the client is attempting domain fronting. |
| 16604 | acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0 |
| 16605 | |
| 16606 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16607 | sub(<value>) |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16608 | Subtracts <value> from the input value of type signed integer, and returns |
| 16609 | the result as an signed integer. Note: in order to subtract the input from |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16610 | a constant, simply perform a "neg,add(value)". <value> can be a numeric value |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16611 | or a variable name. The name of the variable starts with an indication about |
| 16612 | its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 16613 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16614 | "sess" : the variable is shared with the whole session |
| 16615 | "txn" : the variable is shared with the transaction (request and |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16616 | response), |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16617 | "req" : the variable is shared only during request processing, |
| 16618 | "res" : the variable is shared only during response processing. |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16619 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 16620 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16621 | |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16622 | table_bytes_in_rate(<table>) |
| 16623 | Uses the string representation of the input sample to perform a look up in |
| 16624 | the specified table. If the key is not found in the table, integer value zero |
| 16625 | is returned. Otherwise the converter returns the average client-to-server |
| 16626 | bytes rate associated with the input sample in the designated table, measured |
| 16627 | in amount of bytes over the period configured in the table. See also the |
| 16628 | sc_bytes_in_rate sample fetch keyword. |
| 16629 | |
| 16630 | |
| 16631 | table_bytes_out_rate(<table>) |
| 16632 | Uses the string representation of the input sample to perform a look up in |
| 16633 | the specified table. If the key is not found in the table, integer value zero |
| 16634 | is returned. Otherwise the converter returns the average server-to-client |
| 16635 | bytes rate associated with the input sample in the designated table, measured |
| 16636 | in amount of bytes over the period configured in the table. See also the |
| 16637 | sc_bytes_out_rate sample fetch keyword. |
| 16638 | |
| 16639 | table_conn_cnt(<table>) |
| 16640 | Uses the string representation of the input sample to perform a look up in |
| 16641 | the specified table. If the key is not found in the table, integer value zero |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16642 | is returned. Otherwise the converter returns the cumulative number of incoming |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16643 | connections associated with the input sample in the designated table. See |
| 16644 | also the sc_conn_cnt sample fetch keyword. |
| 16645 | |
| 16646 | table_conn_cur(<table>) |
| 16647 | Uses the string representation of the input sample to perform a look up in |
| 16648 | the specified table. If the key is not found in the table, integer value zero |
| 16649 | is returned. Otherwise the converter returns the current amount of concurrent |
| 16650 | tracked connections associated with the input sample in the designated table. |
| 16651 | See also the sc_conn_cur sample fetch keyword. |
| 16652 | |
| 16653 | table_conn_rate(<table>) |
| 16654 | Uses the string representation of the input sample to perform a look up in |
| 16655 | the specified table. If the key is not found in the table, integer value zero |
| 16656 | is returned. Otherwise the converter returns the average incoming connection |
| 16657 | rate associated with the input sample in the designated table. See also the |
| 16658 | sc_conn_rate sample fetch keyword. |
| 16659 | |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 16660 | table_gpt0(<table>) |
| 16661 | Uses the string representation of the input sample to perform a look up in |
| 16662 | the specified table. If the key is not found in the table, boolean value zero |
| 16663 | is returned. Otherwise the converter returns the current value of the first |
| 16664 | general purpose tag associated with the input sample in the designated table. |
| 16665 | See also the sc_get_gpt0 sample fetch keyword. |
| 16666 | |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16667 | table_gpc0(<table>) |
| 16668 | Uses the string representation of the input sample to perform a look up in |
| 16669 | the specified table. If the key is not found in the table, integer value zero |
| 16670 | is returned. Otherwise the converter returns the current value of the first |
| 16671 | general purpose counter associated with the input sample in the designated |
| 16672 | table. See also the sc_get_gpc0 sample fetch keyword. |
| 16673 | |
| 16674 | table_gpc0_rate(<table>) |
| 16675 | Uses the string representation of the input sample to perform a look up in |
| 16676 | the specified table. If the key is not found in the table, integer value zero |
| 16677 | is returned. Otherwise the converter returns the frequency which the gpc0 |
| 16678 | counter was incremented over the configured period in the table, associated |
| 16679 | with the input sample in the designated table. See also the sc_get_gpc0_rate |
| 16680 | sample fetch keyword. |
| 16681 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 16682 | table_gpc1(<table>) |
| 16683 | Uses the string representation of the input sample to perform a look up in |
| 16684 | the specified table. If the key is not found in the table, integer value zero |
| 16685 | is returned. Otherwise the converter returns the current value of the second |
| 16686 | general purpose counter associated with the input sample in the designated |
| 16687 | table. See also the sc_get_gpc1 sample fetch keyword. |
| 16688 | |
| 16689 | table_gpc1_rate(<table>) |
| 16690 | Uses the string representation of the input sample to perform a look up in |
| 16691 | the specified table. If the key is not found in the table, integer value zero |
| 16692 | is returned. Otherwise the converter returns the frequency which the gpc1 |
| 16693 | counter was incremented over the configured period in the table, associated |
| 16694 | with the input sample in the designated table. See also the sc_get_gpc1_rate |
| 16695 | sample fetch keyword. |
| 16696 | |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16697 | table_http_err_cnt(<table>) |
| 16698 | Uses the string representation of the input sample to perform a look up in |
| 16699 | the specified table. If the key is not found in the table, integer value zero |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16700 | is returned. Otherwise the converter returns the cumulative number of HTTP |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16701 | errors associated with the input sample in the designated table. See also the |
| 16702 | sc_http_err_cnt sample fetch keyword. |
| 16703 | |
| 16704 | table_http_err_rate(<table>) |
| 16705 | Uses the string representation of the input sample to perform a look up in |
| 16706 | the specified table. If the key is not found in the table, integer value zero |
| 16707 | is returned. Otherwise the average rate of HTTP errors associated with the |
| 16708 | input sample in the designated table, measured in amount of errors over the |
| 16709 | period configured in the table. See also the sc_http_err_rate sample fetch |
| 16710 | keyword. |
| 16711 | |
Willy Tarreau | 826f3ab | 2021-02-10 12:07:15 +0100 | [diff] [blame] | 16712 | table_http_fail_cnt(<table>) |
| 16713 | Uses the string representation of the input sample to perform a look up in |
| 16714 | the specified table. If the key is not found in the table, integer value zero |
| 16715 | is returned. Otherwise the converter returns the cumulative number of HTTP |
| 16716 | failures associated with the input sample in the designated table. See also |
| 16717 | the sc_http_fail_cnt sample fetch keyword. |
| 16718 | |
| 16719 | table_http_fail_rate(<table>) |
| 16720 | Uses the string representation of the input sample to perform a look up in |
| 16721 | the specified table. If the key is not found in the table, integer value zero |
| 16722 | is returned. Otherwise the average rate of HTTP failures associated with the |
| 16723 | input sample in the designated table, measured in amount of failures over the |
| 16724 | period configured in the table. See also the sc_http_fail_rate sample fetch |
| 16725 | keyword. |
| 16726 | |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16727 | table_http_req_cnt(<table>) |
| 16728 | Uses the string representation of the input sample to perform a look up in |
| 16729 | the specified table. If the key is not found in the table, integer value zero |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16730 | is returned. Otherwise the converter returns the cumulative number of HTTP |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16731 | requests associated with the input sample in the designated table. See also |
| 16732 | the sc_http_req_cnt sample fetch keyword. |
| 16733 | |
| 16734 | table_http_req_rate(<table>) |
| 16735 | Uses the string representation of the input sample to perform a look up in |
| 16736 | the specified table. If the key is not found in the table, integer value zero |
| 16737 | is returned. Otherwise the average rate of HTTP requests associated with the |
| 16738 | input sample in the designated table, measured in amount of requests over the |
| 16739 | period configured in the table. See also the sc_http_req_rate sample fetch |
| 16740 | keyword. |
| 16741 | |
| 16742 | table_kbytes_in(<table>) |
| 16743 | Uses the string representation of the input sample to perform a look up in |
| 16744 | the specified table. If the key is not found in the table, integer value zero |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16745 | is returned. Otherwise the converter returns the cumulative number of client- |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16746 | to-server data associated with the input sample in the designated table, |
| 16747 | measured in kilobytes. The test is currently performed on 32-bit integers, |
| 16748 | which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch |
| 16749 | keyword. |
| 16750 | |
| 16751 | table_kbytes_out(<table>) |
| 16752 | Uses the string representation of the input sample to perform a look up in |
| 16753 | the specified table. If the key is not found in the table, integer value zero |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16754 | is returned. Otherwise the converter returns the cumulative number of server- |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16755 | to-client data associated with the input sample in the designated table, |
| 16756 | measured in kilobytes. The test is currently performed on 32-bit integers, |
| 16757 | which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch |
| 16758 | keyword. |
| 16759 | |
| 16760 | table_server_id(<table>) |
| 16761 | Uses the string representation of the input sample to perform a look up in |
| 16762 | the specified table. If the key is not found in the table, integer value zero |
| 16763 | is returned. Otherwise the converter returns the server ID associated with |
| 16764 | the input sample in the designated table. A server ID is associated to a |
| 16765 | sample by a "stick" rule when a connection to a server succeeds. A server ID |
| 16766 | zero means that no server is associated with this key. |
| 16767 | |
| 16768 | table_sess_cnt(<table>) |
| 16769 | Uses the string representation of the input sample to perform a look up in |
| 16770 | the specified table. If the key is not found in the table, integer value zero |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16771 | is returned. Otherwise the converter returns the cumulative number of incoming |
Willy Tarreau | d9f316a | 2014-07-10 14:03:38 +0200 | [diff] [blame] | 16772 | sessions associated with the input sample in the designated table. Note that |
| 16773 | a session here refers to an incoming connection being accepted by the |
| 16774 | "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch |
| 16775 | keyword. |
| 16776 | |
| 16777 | table_sess_rate(<table>) |
| 16778 | Uses the string representation of the input sample to perform a look up in |
| 16779 | the specified table. If the key is not found in the table, integer value zero |
| 16780 | is returned. Otherwise the converter returns the average incoming session |
| 16781 | rate associated with the input sample in the designated table. Note that a |
| 16782 | session here refers to an incoming connection being accepted by the |
| 16783 | "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch |
| 16784 | keyword. |
| 16785 | |
| 16786 | table_trackers(<table>) |
| 16787 | Uses the string representation of the input sample to perform a look up in |
| 16788 | the specified table. If the key is not found in the table, integer value zero |
| 16789 | is returned. Otherwise the converter returns the current amount of concurrent |
| 16790 | connections tracking the same key as the input sample in the designated |
| 16791 | table. It differs from table_conn_cur in that it does not rely on any stored |
| 16792 | information but on the table's reference count (the "use" value which is |
| 16793 | returned by "show table" on the CLI). This may sometimes be more suited for |
| 16794 | layer7 tracking. It can be used to tell a server how many concurrent |
| 16795 | connections there are from a given address for example. See also the |
| 16796 | sc_trackers sample fetch keyword. |
| 16797 | |
Moemen MHEDHBI | 92f7d43 | 2021-04-01 20:53:59 +0200 | [diff] [blame] | 16798 | ub64dec |
| 16799 | This converter is the base64url variant of b64dec converter. base64url |
| 16800 | encoding is the "URL and Filename Safe Alphabet" variant of base64 encoding. |
| 16801 | It is also the encoding used in JWT (JSON Web Token) standard. |
| 16802 | |
| 16803 | Example: |
| 16804 | # Decoding a JWT payload: |
| 16805 | http-request set-var(txn.token_payload) req.hdr(Authorization),word(2,.),ub64dec |
| 16806 | |
| 16807 | ub64enc |
| 16808 | This converter is the base64url variant of base64 converter. |
| 16809 | |
Willy Tarreau | ffcb2e4 | 2014-07-10 16:29:08 +0200 | [diff] [blame] | 16810 | upper |
| 16811 | Convert a string sample to upper case. This can only be placed after a string |
| 16812 | sample fetch function or after a transformation keyword returning a string |
| 16813 | type. The result is of type string. |
| 16814 | |
Willy Tarreau | 62ba9ba | 2020-04-23 17:54:47 +0200 | [diff] [blame] | 16815 | url_dec([<in_form>]) |
| 16816 | Takes an url-encoded string provided as input and returns the decoded version |
| 16817 | as output. The input and the output are of type string. If the <in_form> |
| 16818 | argument is set to a non-zero integer value, the input string is assumed to |
| 16819 | be part of a form or query string and the '+' character will be turned into a |
| 16820 | space (' '). Otherwise this will only happen after a question mark indicating |
| 16821 | a query string ('?'). |
Thierry FOURNIER | 82ff3c9 | 2015-05-07 15:46:20 +0200 | [diff] [blame] | 16822 | |
William Dauchy | 888b0ae | 2021-01-06 23:39:50 +0100 | [diff] [blame] | 16823 | url_enc([<enc_type>]) |
| 16824 | Takes a string provided as input and returns the encoded version as output. |
| 16825 | The input and the output are of type string. By default the type of encoding |
| 16826 | is meant for `query` type. There is no other type supported for now but the |
| 16827 | optional argument is here for future changes. |
| 16828 | |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16829 | ungrpc(<field_number>,[<field_type>]) |
Frédéric Lécaille | 50290fb | 2019-02-27 14:34:51 +0100 | [diff] [blame] | 16830 | This extracts the protocol buffers message field in raw mode of an input binary |
Frédéric Lécaille | bfe6138 | 2019-03-06 14:34:36 +0100 | [diff] [blame] | 16831 | sample representation of a gRPC message with <field_number> as field number |
| 16832 | (dotted notation) if <field_type> is not present, or as an integer sample if this |
| 16833 | field is present. |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16834 | The list of the authorized types is the following one: "int32", "int64", "uint32", |
| 16835 | "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0 |
| 16836 | "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32", |
| 16837 | "float" for the wire type 5. Note that "string" is considered as a length-delimited |
Frédéric Lécaille | 93d3316 | 2019-03-06 09:35:59 +0100 | [diff] [blame] | 16838 | type, so it does not require any <field_type> argument to be extracted. |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16839 | More information may be found here about the protocol buffers message field types: |
| 16840 | https://developers.google.com/protocol-buffers/docs/encoding |
Frédéric Lécaille | 50290fb | 2019-02-27 14:34:51 +0100 | [diff] [blame] | 16841 | |
| 16842 | Example: |
| 16843 | // with such a protocol buffer .proto file content adapted from |
| 16844 | // https://github.com/grpc/grpc/blob/master/examples/protos/route_guide.proto |
| 16845 | |
| 16846 | message Point { |
| 16847 | int32 latitude = 1; |
| 16848 | int32 longitude = 2; |
| 16849 | } |
| 16850 | |
| 16851 | message PPoint { |
| 16852 | Point point = 59; |
| 16853 | } |
| 16854 | |
| 16855 | message Rectangle { |
| 16856 | // One corner of the rectangle. |
| 16857 | PPoint lo = 48; |
| 16858 | // The other corner of the rectangle. |
| 16859 | PPoint hi = 49; |
| 16860 | } |
| 16861 | |
Peter Gervai | df4c9d2 | 2020-06-11 18:05:11 +0200 | [diff] [blame] | 16862 | let's say a body request is made of a "Rectangle" object value (two PPoint |
| 16863 | protocol buffers messages), the four protocol buffers fields could be |
| 16864 | extracted with these "ungrpc" directives: |
Frédéric Lécaille | 50290fb | 2019-02-27 14:34:51 +0100 | [diff] [blame] | 16865 | |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16866 | req.body,ungrpc(48.59.1,int32) # "latitude" of "lo" first PPoint |
| 16867 | req.body,ungrpc(48.59.2,int32) # "longitude" of "lo" first PPoint |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 16868 | req.body,ungrpc(49.59.1,int32) # "latitude" of "hi" second PPoint |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16869 | req.body,ungrpc(49.59.2,int32) # "longitude" of "hi" second PPoint |
| 16870 | |
Peter Gervai | df4c9d2 | 2020-06-11 18:05:11 +0200 | [diff] [blame] | 16871 | We could also extract the intermediary 48.59 field as a binary sample as follows: |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16872 | |
Frédéric Lécaille | 93d3316 | 2019-03-06 09:35:59 +0100 | [diff] [blame] | 16873 | req.body,ungrpc(48.59) |
Frédéric Lécaille | 756d97f | 2019-03-04 19:03:48 +0100 | [diff] [blame] | 16874 | |
Peter Gervai | df4c9d2 | 2020-06-11 18:05:11 +0200 | [diff] [blame] | 16875 | As a gRPC message is always made of a gRPC header followed by protocol buffers |
| 16876 | messages, in the previous example the "latitude" of "lo" first PPoint |
| 16877 | could be extracted with these equivalent directives: |
Frédéric Lécaille | bfe6138 | 2019-03-06 14:34:36 +0100 | [diff] [blame] | 16878 | |
| 16879 | req.body,ungrpc(48.59),protobuf(1,int32) |
| 16880 | req.body,ungrpc(48),protobuf(59.1,int32) |
| 16881 | req.body,ungrpc(48),protobuf(59),protobuf(1,int32) |
| 16882 | |
Peter Gervai | df4c9d2 | 2020-06-11 18:05:11 +0200 | [diff] [blame] | 16883 | Note that the first convert must be "ungrpc", the remaining ones must be |
| 16884 | "protobuf" and only the last one may have or not a second argument to |
| 16885 | interpret the previous binary sample. |
Frédéric Lécaille | bfe6138 | 2019-03-06 14:34:36 +0100 | [diff] [blame] | 16886 | |
Frédéric Lécaille | 50290fb | 2019-02-27 14:34:51 +0100 | [diff] [blame] | 16887 | |
Tim Duesterhus | ef4e45c | 2021-01-21 17:40:50 +0100 | [diff] [blame] | 16888 | unset-var(<var>) |
Christopher Faulet | 85d79c9 | 2016-11-09 16:54:56 +0100 | [diff] [blame] | 16889 | Unsets a variable if the input content is defined. The name of the variable |
| 16890 | starts with an indication about its scope. The scopes allowed are: |
| 16891 | "proc" : the variable is shared with the whole process |
| 16892 | "sess" : the variable is shared with the whole session |
| 16893 | "txn" : the variable is shared with the transaction (request and |
| 16894 | response), |
| 16895 | "req" : the variable is shared only during request processing, |
| 16896 | "res" : the variable is shared only during response processing. |
| 16897 | This prefix is followed by a name. The separator is a '.'. The name may only |
| 16898 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
| 16899 | |
Willy Tarreau | 0dbfdba | 2014-07-10 16:37:47 +0200 | [diff] [blame] | 16900 | utime(<format>[,<offset>]) |
| 16901 | Converts an integer supposed to contain a date since epoch to a string |
| 16902 | representing this date in UTC time using a format defined by the <format> |
| 16903 | string using strftime(3). The purpose is to allow any date format to be used |
| 16904 | in logs. An optional <offset> in seconds may be applied to the input date |
| 16905 | (positive or negative). See the strftime() man page for the format supported |
| 16906 | by your operating system. See also the ltime converter. |
| 16907 | |
| 16908 | Example : |
| 16909 | |
| 16910 | # Emit two colons, one with the UTC time and another with ip:port |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 16911 | # e.g. 20140710162350 127.0.0.1:57325 |
Willy Tarreau | 0dbfdba | 2014-07-10 16:37:47 +0200 | [diff] [blame] | 16912 | log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp |
| 16913 | |
Marcin Deranek | 9631a28 | 2018-04-16 14:30:46 +0200 | [diff] [blame] | 16914 | word(<index>,<delimiters>[,<count>]) |
| 16915 | Extracts the nth word counting from the beginning (positive index) or from |
| 16916 | the end (negative index) considering given delimiters from an input string. |
| 16917 | Indexes start at 1 or -1 and delimiters are a string formatted list of chars. |
Jerome Magnin | 8820932 | 2020-01-28 13:33:44 +0100 | [diff] [blame] | 16918 | Delimiters at the beginning or end of the input string are ignored. |
Marcin Deranek | 9631a28 | 2018-04-16 14:30:46 +0200 | [diff] [blame] | 16919 | Optionally you can specify <count> of words to extract (default: 1). |
| 16920 | Value of 0 indicates extraction of all remaining words. |
| 16921 | |
| 16922 | Example : |
| 16923 | str(f1_f2_f3__f5),word(4,_) # f5 |
| 16924 | str(f1_f2_f3__f5),word(2,_,0) # f2_f3__f5 |
| 16925 | str(f1_f2_f3__f5),word(3,_,2) # f3__f5 |
| 16926 | str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3 |
| 16927 | str(f1_f2_f3__f5),word(-3,_,0) # f1_f2 |
Jerome Magnin | 8820932 | 2020-01-28 13:33:44 +0100 | [diff] [blame] | 16928 | str(/f1/f2/f3/f4),word(1,/) # f1 |
Emeric Brun | c9a0f6d | 2014-11-25 14:09:01 +0100 | [diff] [blame] | 16929 | |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 16930 | wt6([<avalanche>]) |
| 16931 | Hashes a binary input sample into an unsigned 32-bit quantity using the WT6 |
| 16932 | hash function. Optionally, it is possible to apply a full avalanche hash |
| 16933 | function to the output if the optional <avalanche> argument equals 1. This |
| 16934 | converter uses the same functions as used by the various hash-based load |
| 16935 | balancing algorithms, so it will provide exactly the same results. It is |
| 16936 | mostly intended for debugging, but can be used as a stick-table entry to |
| 16937 | collect rough statistics. It must not be used for security purposes as a |
Emmanuel Hocdet | 50791a7 | 2018-03-21 11:19:01 +0100 | [diff] [blame] | 16938 | 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c", |
| 16939 | and the "hash-type" directive. |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 16940 | |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16941 | xor(<value>) |
| 16942 | Performs a bitwise "XOR" (exclusive OR) between <value> and the input value |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 16943 | of type signed integer, and returns the result as an signed integer. |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16944 | <value> can be a numeric value or a variable name. The name of the variable |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16945 | starts with an indication about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 16946 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16947 | "sess" : the variable is shared with the whole session |
| 16948 | "txn" : the variable is shared with the transaction (request and |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16949 | response), |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 16950 | "req" : the variable is shared only during request processing, |
| 16951 | "res" : the variable is shared only during response processing. |
Thierry FOURNIER | 5d86fae | 2015-07-07 21:10:16 +0200 | [diff] [blame] | 16952 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 16953 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Willy Tarreau | 9770787 | 2015-01-27 15:12:13 +0100 | [diff] [blame] | 16954 | |
Dragan Dosen | 04bf0cc | 2020-12-22 21:44:33 +0100 | [diff] [blame] | 16955 | xxh3([<seed>]) |
| 16956 | Hashes a binary input sample into a signed 64-bit quantity using the XXH3 |
| 16957 | 64-bit variant of the XXhash hash function. This hash supports a seed which |
| 16958 | defaults to zero but a different value maybe passed as the <seed> argument. |
| 16959 | This hash is known to be very good and very fast so it can be used to hash |
| 16960 | URLs and/or URL parameters for use as stick-table keys to collect statistics |
| 16961 | with a low collision rate, though care must be taken as the algorithm is not |
| 16962 | considered as cryptographically secure. |
| 16963 | |
Thierry FOURNIER | 01e0974 | 2016-12-26 11:46:11 +0100 | [diff] [blame] | 16964 | xxh32([<seed>]) |
| 16965 | Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit |
| 16966 | variant of the XXHash hash function. This hash supports a seed which defaults |
| 16967 | to zero but a different value maybe passed as the <seed> argument. This hash |
| 16968 | is known to be very good and very fast so it can be used to hash URLs and/or |
| 16969 | URL parameters for use as stick-table keys to collect statistics with a low |
| 16970 | collision rate, though care must be taken as the algorithm is not considered |
| 16971 | as cryptographically secure. |
| 16972 | |
| 16973 | xxh64([<seed>]) |
| 16974 | Hashes a binary input sample into a signed 64-bit quantity using the 64-bit |
| 16975 | variant of the XXHash hash function. This hash supports a seed which defaults |
| 16976 | to zero but a different value maybe passed as the <seed> argument. This hash |
| 16977 | is known to be very good and very fast so it can be used to hash URLs and/or |
| 16978 | URL parameters for use as stick-table keys to collect statistics with a low |
| 16979 | collision rate, though care must be taken as the algorithm is not considered |
| 16980 | as cryptographically secure. |
| 16981 | |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 16982 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 16983 | 7.3.2. Fetching samples from internal states |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 16984 | -------------------------------------------- |
| 16985 | |
| 16986 | A first set of sample fetch methods applies to internal information which does |
| 16987 | not even relate to any client information. These ones are sometimes used with |
| 16988 | "monitor-fail" directives to report an internal status to external watchers. |
| 16989 | The sample fetch methods described in this section are usable anywhere. |
| 16990 | |
| 16991 | always_false : boolean |
| 16992 | Always returns the boolean "false" value. It may be used with ACLs as a |
| 16993 | temporary replacement for another one when adjusting configurations. |
| 16994 | |
| 16995 | always_true : boolean |
| 16996 | Always returns the boolean "true" value. It may be used with ACLs as a |
| 16997 | temporary replacement for another one when adjusting configurations. |
| 16998 | |
| 16999 | avg_queue([<backend>]) : integer |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17000 | Returns the total number of queued connections of the designated backend |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17001 | divided by the number of active servers. The current backend is used if no |
| 17002 | backend is specified. This is very similar to "queue" except that the size of |
| 17003 | the farm is considered, in order to give a more accurate measurement of the |
| 17004 | time it may take for a new connection to be processed. The main usage is with |
| 17005 | ACL to return a sorry page to new users when it becomes certain they will get |
| 17006 | a degraded service, or to pass to the backend servers in a header so that |
| 17007 | they decide to work in degraded mode or to disable some functions to speed up |
| 17008 | the processing a bit. Note that in the event there would not be any active |
| 17009 | server anymore, twice the number of queued connections would be considered as |
| 17010 | the measured value. This is a fair estimate, as we expect one server to get |
| 17011 | back soon anyway, but we still prefer to send new traffic to another backend |
| 17012 | if in better shape. See also the "queue", "be_conn", and "be_sess_rate" |
| 17013 | sample fetches. |
Krzysztof Piotr Oledzki | 346f76d | 2010-01-12 21:59:30 +0100 | [diff] [blame] | 17014 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17015 | be_conn([<backend>]) : integer |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 17016 | Applies to the number of currently established connections on the backend, |
| 17017 | possibly including the connection being evaluated. If no backend name is |
| 17018 | specified, the current one is used. But it is also possible to check another |
| 17019 | backend. It can be used to use a specific farm when the nominal one is full. |
Patrick Hemmer | 4cdf3ab | 2018-06-14 17:10:27 -0400 | [diff] [blame] | 17020 | See also the "fe_conn", "queue", "be_conn_free", and "be_sess_rate" criteria. |
| 17021 | |
| 17022 | be_conn_free([<backend>]) : integer |
| 17023 | Returns an integer value corresponding to the number of available connections |
| 17024 | across available servers in the backend. Queue slots are not included. Backup |
| 17025 | servers are also not included, unless all other servers are down. If no |
| 17026 | backend name is specified, the current one is used. But it is also possible |
| 17027 | to check another backend. It can be used to use a specific farm when the |
Patrick Hemmer | 155e93e | 2018-06-14 18:01:35 -0400 | [diff] [blame] | 17028 | nominal one is full. See also the "be_conn", "connslots", and "srv_conn_free" |
| 17029 | criteria. |
Patrick Hemmer | 4cdf3ab | 2018-06-14 17:10:27 -0400 | [diff] [blame] | 17030 | |
| 17031 | OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0 |
| 17032 | (meaning unlimited), then this fetch clearly does not make sense, in which |
| 17033 | case the value returned will be -1. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 17034 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17035 | be_sess_rate([<backend>]) : integer |
| 17036 | Returns an integer value corresponding to the sessions creation rate on the |
| 17037 | backend, in number of new sessions per second. This is used with ACLs to |
| 17038 | switch to an alternate backend when an expensive or fragile one reaches too |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17039 | high a session rate, or to limit abuse of service (e.g. prevent sucking of an |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17040 | online dictionary). It can also be useful to add this element to logs using a |
| 17041 | log-format directive. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17042 | |
| 17043 | Example : |
| 17044 | # Redirect to an error page if the dictionary is requested too often |
| 17045 | backend dynamic |
| 17046 | mode http |
| 17047 | acl being_scanned be_sess_rate gt 100 |
| 17048 | redirect location /denied.html if being_scanned |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 17049 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17050 | bin(<hex>) : bin |
Thierry FOURNIER | cc10329 | 2015-06-06 19:30:17 +0200 | [diff] [blame] | 17051 | Returns a binary chain. The input is the hexadecimal representation |
| 17052 | of the string. |
| 17053 | |
| 17054 | bool(<bool>) : bool |
| 17055 | Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'. |
| 17056 | 'false' and '0' are the same. 'true' and '1' are the same. |
| 17057 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17058 | connslots([<backend>]) : integer |
| 17059 | Returns an integer value corresponding to the number of connection slots |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 17060 | still available in the backend, by totaling the maximum amount of |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17061 | connections on all servers and the maximum queue size. This is probably only |
| 17062 | used with ACLs. |
Tait Clarridge | 7896d52 | 2012-12-05 21:39:31 -0500 | [diff] [blame] | 17063 | |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 17064 | 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] | 17065 | still available (connection + queue), so that anything beyond that (intended |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 17066 | usage; see "use_backend" keyword) can be redirected to a different backend. |
| 17067 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 17068 | 'connslots' = number of available server connection slots, + number of |
| 17069 | available server queue slots. |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 17070 | |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 17071 | Note that while "fe_conn" may be used, "connslots" comes in especially |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 17072 | 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] | 17073 | multiple backends (perhaps using ACLs to do name-based load balancing) and |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 17074 | you want to be able to differentiate between different backends, and their |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17075 | available "connslots". Also, whereas "nbsrv" only measures servers that are |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17076 | 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] | 17077 | available connection slots as well. See also "queue" and "avg_queue". |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 17078 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 17079 | OTHER CAVEATS AND NOTES: at this point in time, the code does not take care |
| 17080 | 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] | 17081 | 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] | 17082 | will be -1. |
Jeffrey 'jf' Lim | 5051d7b | 2008-09-04 01:03:03 +0800 | [diff] [blame] | 17083 | |
Willy Tarreau | 70fe944 | 2018-11-22 16:07:39 +0100 | [diff] [blame] | 17084 | cpu_calls : integer |
| 17085 | Returns the number of calls to the task processing the stream or current |
| 17086 | request since it was allocated. This number is reset for each new request on |
| 17087 | the same connections in case of HTTP keep-alive. This value should usually be |
| 17088 | low and stable (around 2 calls for a typically simple request) but may become |
| 17089 | high if some processing (compression, caching or analysis) is performed. This |
| 17090 | is purely for performance monitoring purposes. |
| 17091 | |
| 17092 | cpu_ns_avg : integer |
| 17093 | Returns the average number of nanoseconds spent in each call to the task |
| 17094 | processing the stream or current request. This number is reset for each new |
| 17095 | request on the same connections in case of HTTP keep-alive. This value |
| 17096 | indicates the overall cost of processing the request or the connection for |
| 17097 | each call. There is no good nor bad value but the time spent in a call |
| 17098 | automatically causes latency for other processing (see lat_ns_avg below), |
| 17099 | and may affect other connection's apparent response time. Certain operations |
| 17100 | like compression, complex regex matching or heavy Lua operations may directly |
| 17101 | affect this value, and having it in the logs will make it easier to spot the |
| 17102 | faulty processing that needs to be fixed to recover decent performance. |
| 17103 | Note: this value is exactly cpu_ns_tot divided by cpu_calls. |
| 17104 | |
| 17105 | cpu_ns_tot : integer |
| 17106 | Returns the total number of nanoseconds spent in each call to the task |
| 17107 | processing the stream or current request. This number is reset for each new |
| 17108 | request on the same connections in case of HTTP keep-alive. This value |
| 17109 | indicates the overall cost of processing the request or the connection for |
| 17110 | each call. There is no good nor bad value but the time spent in a call |
| 17111 | automatically causes latency for other processing (see lat_ns_avg below), |
| 17112 | induces CPU costs on the machine, and may affect other connection's apparent |
| 17113 | response time. Certain operations like compression, complex regex matching or |
| 17114 | heavy Lua operations may directly affect this value, and having it in the |
| 17115 | logs will make it easier to spot the faulty processing that needs to be fixed |
| 17116 | to recover decent performance. The value may be artificially high due to a |
| 17117 | high cpu_calls count, for example when processing many HTTP chunks, and for |
| 17118 | this reason it is often preferred to log cpu_ns_avg instead. |
| 17119 | |
Cyril Bonté | 6bcd182 | 2019-11-05 23:13:59 +0100 | [diff] [blame] | 17120 | date([<offset>],[<unit>]) : integer |
Willy Tarreau | 6236d3a | 2013-07-25 14:28:25 +0200 | [diff] [blame] | 17121 | Returns the current date as the epoch (number of seconds since 01/01/1970). |
Damien Claisse | ae6f125 | 2019-10-30 15:57:28 +0000 | [diff] [blame] | 17122 | |
| 17123 | If an offset value is specified, then it is added to the current date before |
| 17124 | returning the value. This is particularly useful to compute relative dates, |
| 17125 | as both positive and negative offsets are allowed. |
Willy Tarreau | 276fae9 | 2013-07-25 14:36:01 +0200 | [diff] [blame] | 17126 | It is useful combined with the http_date converter. |
| 17127 | |
Damien Claisse | ae6f125 | 2019-10-30 15:57:28 +0000 | [diff] [blame] | 17128 | <unit> is facultative, and can be set to "s" for seconds (default behavior), |
| 17129 | "ms" for milliseconds or "us" for microseconds. |
| 17130 | If unit is set, return value is an integer reflecting either seconds, |
| 17131 | milliseconds or microseconds since epoch, plus offset. |
| 17132 | It is useful when a time resolution of less than a second is needed. |
| 17133 | |
Willy Tarreau | 276fae9 | 2013-07-25 14:36:01 +0200 | [diff] [blame] | 17134 | Example : |
| 17135 | |
| 17136 | # set an expires header to now+1 hour in every response |
| 17137 | http-response set-header Expires %[date(3600),http_date] |
Willy Tarreau | 6236d3a | 2013-07-25 14:28:25 +0200 | [diff] [blame] | 17138 | |
Damien Claisse | ae6f125 | 2019-10-30 15:57:28 +0000 | [diff] [blame] | 17139 | # set an expires header to now+1 hour in every response, with |
| 17140 | # millisecond granularity |
| 17141 | http-response set-header Expires %[date(3600000,ms),http_date(0,ms)] |
| 17142 | |
Etienne Carriere | a792a0a | 2018-01-17 13:43:24 +0100 | [diff] [blame] | 17143 | date_us : integer |
| 17144 | Return the microseconds part of the date (the "second" part is returned by |
| 17145 | date sample). This sample is coherent with the date sample as it is comes |
| 17146 | from the same timeval structure. |
| 17147 | |
Willy Tarreau | d716f9b | 2017-10-13 11:03:15 +0200 | [diff] [blame] | 17148 | distcc_body(<token>[,<occ>]) : binary |
| 17149 | Parses a distcc message and returns the body associated to occurrence #<occ> |
| 17150 | of the token <token>. Occurrences start at 1, and when unspecified, any may |
| 17151 | match though in practice only the first one is checked for now. This can be |
| 17152 | used to extract file names or arguments in files built using distcc through |
| 17153 | haproxy. Please refer to distcc's protocol documentation for the complete |
| 17154 | list of supported tokens. |
| 17155 | |
| 17156 | distcc_param(<token>[,<occ>]) : integer |
| 17157 | Parses a distcc message and returns the parameter associated to occurrence |
| 17158 | #<occ> of the token <token>. Occurrences start at 1, and when unspecified, |
| 17159 | any may match though in practice only the first one is checked for now. This |
| 17160 | can be used to extract certain information such as the protocol version, the |
| 17161 | file size or the argument in files built using distcc through haproxy. |
| 17162 | Another use case consists in waiting for the start of the preprocessed file |
| 17163 | contents before connecting to the server to avoid keeping idle connections. |
| 17164 | Please refer to distcc's protocol documentation for the complete list of |
| 17165 | supported tokens. |
| 17166 | |
| 17167 | Example : |
| 17168 | # wait up to 20s for the pre-processed file to be uploaded |
| 17169 | tcp-request inspect-delay 20s |
| 17170 | tcp-request content accept if { distcc_param(DOTI) -m found } |
| 17171 | # send large files to the big farm |
| 17172 | use_backend big_farm if { distcc_param(DOTI) gt 1000000 } |
| 17173 | |
Willy Tarreau | 595ec54 | 2013-06-12 21:34:28 +0200 | [diff] [blame] | 17174 | env(<name>) : string |
| 17175 | Returns a string containing the value of environment variable <name>. As a |
| 17176 | reminder, environment variables are per-process and are sampled when the |
| 17177 | process starts. This can be useful to pass some information to a next hop |
| 17178 | server, or with ACLs to take specific action when the process is started a |
| 17179 | certain way. |
| 17180 | |
| 17181 | Examples : |
| 17182 | # Pass the Via header to next hop with the local hostname in it |
| 17183 | http-request add-header Via 1.1\ %[env(HOSTNAME)] |
| 17184 | |
| 17185 | # reject cookie-less requests when the STOP environment variable is set |
| 17186 | http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found } |
| 17187 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17188 | fe_conn([<frontend>]) : integer |
| 17189 | Returns the number of currently established connections on the frontend, |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17190 | possibly including the connection being evaluated. If no frontend name is |
| 17191 | 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] | 17192 | frontend. It can be used to return a sorry page before hard-blocking, or to |
| 17193 | use a specific backend to drain new requests when the farm is considered |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17194 | full. This is mostly used with ACLs but can also be used to pass some |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17195 | statistics to servers in HTTP headers. See also the "dst_conn", "be_conn", |
| 17196 | "fe_sess_rate" fetches. |
Willy Tarreau | a36af91 | 2009-10-10 12:02:45 +0200 | [diff] [blame] | 17197 | |
Nenad Merdanovic | ad9a7e9 | 2016-10-03 04:57:37 +0200 | [diff] [blame] | 17198 | fe_req_rate([<frontend>]) : integer |
| 17199 | Returns an integer value corresponding to the number of HTTP requests per |
| 17200 | second sent to a frontend. This number can differ from "fe_sess_rate" in |
| 17201 | situations where client-side keep-alive is enabled. |
| 17202 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17203 | fe_sess_rate([<frontend>]) : integer |
| 17204 | Returns an integer value corresponding to the sessions creation rate on the |
| 17205 | frontend, in number of new sessions per second. This is used with ACLs to |
| 17206 | limit the incoming session rate to an acceptable range in order to prevent |
| 17207 | abuse of service at the earliest moment, for example when combined with other |
| 17208 | layer 4 ACLs in order to force the clients to wait a bit for the rate to go |
| 17209 | down below the limit. It can also be useful to add this element to logs using |
| 17210 | a log-format directive. See also the "rate-limit sessions" directive for use |
| 17211 | in frontends. |
Willy Tarreau | 079ff0a | 2009-03-05 21:34:28 +0100 | [diff] [blame] | 17212 | |
| 17213 | Example : |
| 17214 | # This frontend limits incoming mails to 10/s with a max of 100 |
| 17215 | # concurrent connections. We accept any connection below 10/s, and |
| 17216 | # force excess clients to wait for 100 ms. Since clients are limited to |
| 17217 | # 100 max, there cannot be more than 10 incoming mails per second. |
| 17218 | frontend mail |
| 17219 | bind :25 |
| 17220 | mode tcp |
| 17221 | maxconn 100 |
| 17222 | acl too_fast fe_sess_rate ge 10 |
| 17223 | tcp-request inspect-delay 100ms |
| 17224 | tcp-request content accept if ! too_fast |
| 17225 | tcp-request content accept if WAIT_END |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 17226 | |
Nenad Merdanovic | 807a6e7 | 2017-03-12 22:00:00 +0100 | [diff] [blame] | 17227 | hostname : string |
| 17228 | Returns the system hostname. |
| 17229 | |
Thierry FOURNIER | 07ee64e | 2015-07-06 23:43:03 +0200 | [diff] [blame] | 17230 | int(<integer>) : signed integer |
| 17231 | Returns a signed integer. |
| 17232 | |
Thierry FOURNIER | cc10329 | 2015-06-06 19:30:17 +0200 | [diff] [blame] | 17233 | ipv4(<ipv4>) : ipv4 |
| 17234 | Returns an ipv4. |
| 17235 | |
| 17236 | ipv6(<ipv6>) : ipv6 |
| 17237 | Returns an ipv6. |
| 17238 | |
Willy Tarreau | 70fe944 | 2018-11-22 16:07:39 +0100 | [diff] [blame] | 17239 | lat_ns_avg : integer |
| 17240 | Returns the average number of nanoseconds spent between the moment the task |
| 17241 | handling the stream is woken up and the moment it is effectively called. This |
| 17242 | number is reset for each new request on the same connections in case of HTTP |
| 17243 | keep-alive. This value indicates the overall latency inflicted to the current |
| 17244 | request by all other requests being processed in parallel, and is a direct |
| 17245 | indicator of perceived performance due to noisy neighbours. In order to keep |
| 17246 | the value low, it is possible to reduce the scheduler's run queue depth using |
| 17247 | "tune.runqueue-depth", to reduce the number of concurrent events processed at |
| 17248 | once using "tune.maxpollevents", to decrease the stream's nice value using |
Willy Tarreau | e7723bd | 2020-06-24 11:11:02 +0200 | [diff] [blame] | 17249 | the "nice" option on the "bind" lines or in the frontend, to enable low |
| 17250 | latency scheduling using "tune.sched.low-latency", or to look for other heavy |
| 17251 | requests in logs (those exhibiting large values of "cpu_ns_avg"), whose |
| 17252 | processing needs to be adjusted or fixed. Compression of large buffers could |
| 17253 | be a culprit, like heavy regex or long lists of regex. Note: this value is |
| 17254 | exactly lat_ns_tot divided by cpu_calls. |
Willy Tarreau | 70fe944 | 2018-11-22 16:07:39 +0100 | [diff] [blame] | 17255 | |
| 17256 | lat_ns_tot : integer |
| 17257 | Returns the total number of nanoseconds spent between the moment the task |
| 17258 | handling the stream is woken up and the moment it is effectively called. This |
| 17259 | number is reset for each new request on the same connections in case of HTTP |
| 17260 | keep-alive. This value indicates the overall latency inflicted to the current |
| 17261 | request by all other requests being processed in parallel, and is a direct |
| 17262 | indicator of perceived performance due to noisy neighbours. In order to keep |
| 17263 | the value low, it is possible to reduce the scheduler's run queue depth using |
| 17264 | "tune.runqueue-depth", to reduce the number of concurrent events processed at |
| 17265 | once using "tune.maxpollevents", to decrease the stream's nice value using |
Willy Tarreau | e7723bd | 2020-06-24 11:11:02 +0200 | [diff] [blame] | 17266 | the "nice" option on the "bind" lines or in the frontend, to enable low |
| 17267 | latency scheduling using "tune.sched.low-latency", or to look for other heavy |
| 17268 | requests in logs (those exhibiting large values of "cpu_ns_avg"), whose |
| 17269 | processing needs to be adjusted or fixed. Compression of large buffers could |
| 17270 | be a culprit, like heavy regex or long lists of regex. Note: while it |
Willy Tarreau | 70fe944 | 2018-11-22 16:07:39 +0100 | [diff] [blame] | 17271 | may intuitively seem that the total latency adds to a transfer time, it is |
| 17272 | almost never true because while a task waits for the CPU, network buffers |
| 17273 | continue to fill up and the next call will process more at once. The value |
| 17274 | may be artificially high due to a high cpu_calls count, for example when |
| 17275 | processing many HTTP chunks, and for this reason it is often preferred to log |
| 17276 | lat_ns_avg instead, which is a more relevant performance indicator. |
| 17277 | |
Thierry FOURNIER | cc10329 | 2015-06-06 19:30:17 +0200 | [diff] [blame] | 17278 | meth(<method>) : method |
| 17279 | Returns a method. |
| 17280 | |
Willy Tarreau | 0f30d26 | 2014-11-24 16:02:05 +0100 | [diff] [blame] | 17281 | nbproc : integer |
| 17282 | Returns an integer value corresponding to the number of processes that were |
| 17283 | started (it equals the global "nbproc" setting). This is useful for logging |
| 17284 | and debugging purposes. |
| 17285 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17286 | nbsrv([<backend>]) : integer |
| 17287 | Returns an integer value corresponding to the number of usable servers of |
| 17288 | either the current backend or the named backend. This is mostly used with |
| 17289 | 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] | 17290 | switch to an alternate backend when the number of servers is too low to |
| 17291 | to handle some load. It is useful to report a failure when combined with |
| 17292 | "monitor fail". |
Willy Tarreau | 079ff0a | 2009-03-05 21:34:28 +0100 | [diff] [blame] | 17293 | |
Patrick Hemmer | fabb24f | 2018-08-13 14:07:57 -0400 | [diff] [blame] | 17294 | prio_class : integer |
| 17295 | Returns the priority class of the current session for http mode or connection |
| 17296 | for tcp mode. The value will be that set by the last call to "http-request |
| 17297 | set-priority-class" or "tcp-request content set-priority-class". |
| 17298 | |
| 17299 | prio_offset : integer |
| 17300 | Returns the priority offset of the current session for http mode or |
| 17301 | connection for tcp mode. The value will be that set by the last call to |
| 17302 | "http-request set-priority-offset" or "tcp-request content |
| 17303 | set-priority-offset". |
| 17304 | |
Willy Tarreau | 0f30d26 | 2014-11-24 16:02:05 +0100 | [diff] [blame] | 17305 | proc : integer |
| 17306 | Returns an integer value corresponding to the position of the process calling |
| 17307 | the function, between 1 and global.nbproc. This is useful for logging and |
| 17308 | debugging purposes. |
| 17309 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17310 | queue([<backend>]) : integer |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17311 | Returns the total number of queued connections of the designated backend, |
| 17312 | including all the connections in server queues. If no backend name is |
| 17313 | 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] | 17314 | one. This is useful with ACLs or to pass statistics to backend servers. This |
| 17315 | can be used to take actions when queuing goes above a known level, generally |
| 17316 | indicating a surge of traffic or a massive slowdown on the servers. One |
| 17317 | possible action could be to reject new users but still accept old ones. See |
| 17318 | also the "avg_queue", "be_conn", and "be_sess_rate" fetches. |
| 17319 | |
Willy Tarreau | 84310e2 | 2014-02-14 11:59:04 +0100 | [diff] [blame] | 17320 | rand([<range>]) : integer |
| 17321 | Returns a random integer value within a range of <range> possible values, |
| 17322 | starting at zero. If the range is not specified, it defaults to 2^32, which |
| 17323 | gives numbers between 0 and 4294967295. It can be useful to pass some values |
| 17324 | needed to take some routing decisions for example, or just for debugging |
| 17325 | purposes. This random must not be used for security purposes. |
| 17326 | |
Luca Schimweg | 8a694b8 | 2019-09-10 15:42:52 +0200 | [diff] [blame] | 17327 | uuid([<version>]) : string |
| 17328 | Returns a UUID following the RFC4122 standard. If the version is not |
| 17329 | specified, a UUID version 4 (fully random) is returned. |
| 17330 | Currently, only version 4 is supported. |
| 17331 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17332 | srv_conn([<backend>/]<server>) : integer |
| 17333 | Returns an integer value corresponding to the number of currently established |
| 17334 | connections on the designated server, possibly including the connection being |
| 17335 | evaluated. If <backend> is omitted, then the server is looked up in the |
| 17336 | current backend. It can be used to use a specific farm when one server is |
| 17337 | full, or to inform the server about our view of the number of active |
Patrick Hemmer | 155e93e | 2018-06-14 18:01:35 -0400 | [diff] [blame] | 17338 | connections with it. See also the "fe_conn", "be_conn", "queue", and |
| 17339 | "srv_conn_free" fetch methods. |
| 17340 | |
| 17341 | srv_conn_free([<backend>/]<server>) : integer |
| 17342 | Returns an integer value corresponding to the number of available connections |
| 17343 | on the designated server, possibly including the connection being evaluated. |
| 17344 | The value does not include queue slots. If <backend> is omitted, then the |
| 17345 | server is looked up in the current backend. It can be used to use a specific |
| 17346 | farm when one server is full, or to inform the server about our view of the |
| 17347 | number of active connections with it. See also the "be_conn_free" and |
| 17348 | "srv_conn" fetch methods. |
| 17349 | |
| 17350 | OTHER CAVEATS AND NOTES: If the server maxconn is 0, then this fetch clearly |
| 17351 | does not make sense, in which case the value returned will be -1. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17352 | |
| 17353 | srv_is_up([<backend>/]<server>) : boolean |
| 17354 | Returns true when the designated server is UP, and false when it is either |
| 17355 | DOWN or in maintenance mode. If <backend> is omitted, then the server is |
| 17356 | looked up in the current backend. It is mainly used to take action based on |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17357 | an external status reported via a health check (e.g. a geographical site's |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17358 | availability). Another possible use which is more of a hack consists in |
| 17359 | using dummy servers as boolean variables that can be enabled or disabled from |
| 17360 | the CLI, so that rules depending on those ACLs can be tweaked in realtime. |
| 17361 | |
Willy Tarreau | ff2b7af | 2017-10-13 11:46:26 +0200 | [diff] [blame] | 17362 | srv_queue([<backend>/]<server>) : integer |
| 17363 | Returns an integer value corresponding to the number of connections currently |
| 17364 | pending in the designated server's queue. If <backend> is omitted, then the |
| 17365 | server is looked up in the current backend. It can sometimes be used together |
| 17366 | with the "use-server" directive to force to use a known faster server when it |
| 17367 | is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample |
| 17368 | fetch methods. |
| 17369 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17370 | srv_sess_rate([<backend>/]<server>) : integer |
| 17371 | Returns an integer corresponding to the sessions creation rate on the |
| 17372 | designated server, in number of new sessions per second. If <backend> is |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 17373 | 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] | 17374 | used with ACLs but can make sense with logs too. This is used to switch to an |
| 17375 | alternate backend when an expensive or fragile one reaches too high a session |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17376 | rate, or to limit abuse of service (e.g. prevent latent requests from |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17377 | overloading servers). |
| 17378 | |
| 17379 | Example : |
| 17380 | # Redirect to a separate back |
| 17381 | acl srv1_full srv_sess_rate(be1/srv1) gt 50 |
| 17382 | acl srv2_full srv_sess_rate(be1/srv2) gt 50 |
| 17383 | use_backend be2 if srv1_full or srv2_full |
| 17384 | |
Alex | bf1bd5a | 2021-04-24 13:02:21 +0200 | [diff] [blame] | 17385 | srv_iweight([<backend>/]<server>) : integer |
Christopher Faulet | 1bea865 | 2020-07-10 16:03:45 +0200 | [diff] [blame] | 17386 | Returns an integer corresponding to the server's initial weight. If <backend> |
| 17387 | is omitted, then the server is looked up in the current backend. See also |
| 17388 | "srv_weight" and "srv_uweight". |
| 17389 | |
Alex | bf1bd5a | 2021-04-24 13:02:21 +0200 | [diff] [blame] | 17390 | srv_uweight([<backend>/]<server>) : integer |
Christopher Faulet | 1bea865 | 2020-07-10 16:03:45 +0200 | [diff] [blame] | 17391 | Returns an integer corresponding to the user visible server's weight. If |
| 17392 | <backend> is omitted, then the server is looked up in the current |
| 17393 | backend. See also "srv_weight" and "srv_iweight". |
| 17394 | |
Alex | bf1bd5a | 2021-04-24 13:02:21 +0200 | [diff] [blame] | 17395 | srv_weight([<backend>/]<server>) : integer |
Christopher Faulet | 1bea865 | 2020-07-10 16:03:45 +0200 | [diff] [blame] | 17396 | Returns an integer corresponding to the current (or effective) server's |
| 17397 | weight. If <backend> is omitted, then the server is looked up in the current |
| 17398 | backend. See also "srv_iweight" and "srv_uweight". |
| 17399 | |
Willy Tarreau | 0f30d26 | 2014-11-24 16:02:05 +0100 | [diff] [blame] | 17400 | stopping : boolean |
| 17401 | Returns TRUE if the process calling the function is currently stopping. This |
| 17402 | can be useful for logging, or for relaxing certain checks or helping close |
| 17403 | certain connections upon graceful shutdown. |
| 17404 | |
Thierry FOURNIER | cc10329 | 2015-06-06 19:30:17 +0200 | [diff] [blame] | 17405 | str(<string>) : string |
| 17406 | Returns a string. |
| 17407 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17408 | table_avl([<table>]) : integer |
| 17409 | Returns the total number of available entries in the current proxy's |
| 17410 | stick-table or in the designated stick-table. See also table_cnt. |
| 17411 | |
| 17412 | table_cnt([<table>]) : integer |
| 17413 | Returns the total number of entries currently in use in the current proxy's |
| 17414 | stick-table or in the designated stick-table. See also src_conn_cnt and |
| 17415 | table_avl for other entry counting methods. |
| 17416 | |
Christopher Faulet | 34adb2a | 2017-11-21 21:45:38 +0100 | [diff] [blame] | 17417 | thread : integer |
| 17418 | Returns an integer value corresponding to the position of the thread calling |
| 17419 | the function, between 0 and (global.nbthread-1). This is useful for logging |
| 17420 | and debugging purposes. |
| 17421 | |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 17422 | var(<var-name>) : undefined |
| 17423 | Returns a variable with the stored type. If the variable is not set, the |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 17424 | sample fetch fails. The name of the variable starts with an indication |
| 17425 | about its scope. The scopes allowed are: |
Christopher Faulet | ff2613e | 2016-11-09 11:36:17 +0100 | [diff] [blame] | 17426 | "proc" : the variable is shared with the whole process |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 17427 | "sess" : the variable is shared with the whole session |
| 17428 | "txn" : the variable is shared with the transaction (request and |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 17429 | response), |
Daniel Schneller | 0b54705 | 2016-03-21 20:46:57 +0100 | [diff] [blame] | 17430 | "req" : the variable is shared only during request processing, |
| 17431 | "res" : the variable is shared only during response processing. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 17432 | This prefix is followed by a name. The separator is a '.'. The name may only |
Christopher Faulet | b71557a | 2016-10-31 10:49:03 +0100 | [diff] [blame] | 17433 | contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. |
Thierry FOURNIER | 4834bc7 | 2015-06-06 19:29:07 +0200 | [diff] [blame] | 17434 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 17435 | 7.3.3. Fetching samples at Layer 4 |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17436 | ---------------------------------- |
| 17437 | |
| 17438 | The layer 4 usually describes just the transport layer which in haproxy is |
| 17439 | closest to the connection, where no content is yet made available. The fetch |
| 17440 | methods described here are usable as low as the "tcp-request connection" rule |
| 17441 | sets unless they require some future information. Those generally include |
| 17442 | 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] | 17443 | the incoming connection. For retrieving a value from a sticky counters, the |
| 17444 | counter number can be explicitly set as 0, 1, or 2 using the pre-defined |
Moemen MHEDHBI | 9cf4634 | 2018-09-25 17:50:53 +0200 | [diff] [blame] | 17445 | "sc0_", "sc1_", or "sc2_" prefix. These three pre-defined prefixes can only be |
| 17446 | used if MAX_SESS_STKCTR value does not exceed 3, otherwise the counter number |
| 17447 | can be specified as the first integer argument when using the "sc_" prefix. |
| 17448 | Starting from "sc_0" to "sc_N" where N is (MAX_SESS_STKCTR-1). An optional |
| 17449 | table may be specified with the "sc*" form, in which case the currently |
| 17450 | tracked key will be looked up into this alternate table instead of the table |
| 17451 | currently being tracked. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17452 | |
Christopher Faulet | 7d081f0 | 2021-04-15 09:38:37 +0200 | [diff] [blame] | 17453 | bc_dst : ip |
| 17454 | This is the destination ip address of the connection on the server side, |
| 17455 | which is the server address HAProxy connected to. It is of type IP and works |
| 17456 | on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 address is mapped to its |
| 17457 | IPv6 equivalent, according to RFC 4291. |
| 17458 | |
| 17459 | bc_dst_port : integer |
| 17460 | Returns an integer value corresponding to the destination TCP port of the |
| 17461 | connection on the server side, which is the port HAproxy connected to. |
| 17462 | |
Jérôme Magnin | 35e53a6 | 2019-01-16 14:38:37 +0100 | [diff] [blame] | 17463 | bc_http_major : integer |
Jérôme Magnin | 8657742 | 2018-12-07 09:03:11 +0100 | [diff] [blame] | 17464 | Returns the backend connection's HTTP major version encoding, which may be 1 |
| 17465 | for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire |
| 17466 | encoding and not the version present in the request header. |
| 17467 | |
Christopher Faulet | 7d081f0 | 2021-04-15 09:38:37 +0200 | [diff] [blame] | 17468 | bc_src : ip |
| 17469 | This is the source ip address of the connection on the server side, which is |
| 17470 | the server address haproxy connected from. It is of type IP and works on both |
| 17471 | IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are mapped to their IPv6 |
| 17472 | equivalent, according to RFC 4291. |
| 17473 | |
| 17474 | bc_src_port : integer |
| 17475 | Returns an integer value corresponding to the TCP source port of the |
| 17476 | connection on the server side, which is the port HAproxy connected from. |
| 17477 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17478 | be_id : integer |
| 17479 | Returns an integer containing the current backend's id. It can be used in |
Christopher Faulet | d1b4464 | 2020-04-30 09:51:15 +0200 | [diff] [blame] | 17480 | frontends with responses to check which backend processed the request. It can |
| 17481 | also be used in a tcp-check or an http-check ruleset. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17482 | |
Marcin Deranek | d2471c2 | 2016-12-12 14:08:05 +0100 | [diff] [blame] | 17483 | be_name : string |
| 17484 | Returns a string containing the current backend's name. It can be used in |
Christopher Faulet | d1b4464 | 2020-04-30 09:51:15 +0200 | [diff] [blame] | 17485 | frontends with responses to check which backend processed the request. It can |
| 17486 | also be used in a tcp-check or an http-check ruleset. |
Marcin Deranek | d2471c2 | 2016-12-12 14:08:05 +0100 | [diff] [blame] | 17487 | |
Amaury Denoyelle | d91d779 | 2020-12-10 13:43:56 +0100 | [diff] [blame] | 17488 | be_server_timeout : integer |
| 17489 | Returns the configuration value in millisecond for the server timeout of the |
| 17490 | current backend. This timeout can be overwritten by a "set-timeout" rule. See |
| 17491 | also the "cur_server_timeout". |
| 17492 | |
| 17493 | be_tunnel_timeout : integer |
| 17494 | Returns the configuration value in millisecond for the tunnel timeout of the |
| 17495 | current backend. This timeout can be overwritten by a "set-timeout" rule. See |
| 17496 | also the "cur_tunnel_timeout". |
| 17497 | |
Amaury Denoyelle | f7719a2 | 2020-12-10 13:43:58 +0100 | [diff] [blame] | 17498 | cur_server_timeout : integer |
| 17499 | Returns the currently applied server timeout in millisecond for the stream. |
| 17500 | In the default case, this will be equal to be_server_timeout unless a |
| 17501 | "set-timeout" rule has been applied. See also "be_server_timeout". |
| 17502 | |
| 17503 | cur_tunnel_timeout : integer |
| 17504 | Returns the currently applied tunnel timeout in millisecond for the stream. |
| 17505 | In the default case, this will be equal to be_tunnel_timeout unless a |
| 17506 | "set-timeout" rule has been applied. See also "be_tunnel_timeout". |
| 17507 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17508 | dst : ip |
| 17509 | This is the destination IPv4 address of the connection on the client side, |
| 17510 | which is the address the client connected to. It can be useful when running |
| 17511 | in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables. |
| 17512 | On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to |
Willy Tarreau | 64ded3d | 2019-01-23 10:02:15 +0100 | [diff] [blame] | 17513 | RFC 4291. When the incoming connection passed through address translation or |
| 17514 | redirection involving connection tracking, the original destination address |
| 17515 | before the redirection will be reported. On Linux systems, the source and |
| 17516 | destination may seldom appear reversed if the nf_conntrack_tcp_loose sysctl |
| 17517 | is set, because a late response may reopen a timed out connection and switch |
| 17518 | what is believed to be the source and the destination. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17519 | |
| 17520 | dst_conn : integer |
| 17521 | Returns an integer value corresponding to the number of currently established |
| 17522 | connections on the same socket including the one being evaluated. It is |
| 17523 | normally used with ACLs but can as well be used to pass the information to |
| 17524 | servers in an HTTP header or in logs. It can be used to either return a sorry |
| 17525 | page before hard-blocking, or to use a specific backend to drain new requests |
| 17526 | when the socket is considered saturated. This offers the ability to assign |
| 17527 | different limits to different listening ports or addresses. See also the |
| 17528 | "fe_conn" and "be_conn" fetches. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17529 | |
Willy Tarreau | 16e0156 | 2016-08-09 16:46:18 +0200 | [diff] [blame] | 17530 | dst_is_local : boolean |
| 17531 | Returns true if the destination address of the incoming connection is local |
| 17532 | to the system, or false if the address doesn't exist on the system, meaning |
| 17533 | that it was intercepted in transparent mode. It can be useful to apply |
| 17534 | certain rules by default to forwarded traffic and other rules to the traffic |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17535 | targeting the real address of the machine. For example the stats page could |
Willy Tarreau | 16e0156 | 2016-08-09 16:46:18 +0200 | [diff] [blame] | 17536 | be delivered only on this address, or SSH access could be locally redirected. |
| 17537 | Please note that the check involves a few system calls, so it's better to do |
| 17538 | it only once per connection. |
| 17539 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17540 | dst_port : integer |
| 17541 | Returns an integer value corresponding to the destination TCP port of the |
| 17542 | connection on the client side, which is the port the client connected to. |
| 17543 | This might be used when running in transparent mode, when assigning dynamic |
| 17544 | ports to some clients for a whole application session, to stick all users to |
| 17545 | a same server, or to pass the destination port information to a server using |
| 17546 | an HTTP header. |
| 17547 | |
Willy Tarreau | 60ca10a | 2017-08-18 15:26:54 +0200 | [diff] [blame] | 17548 | fc_http_major : integer |
| 17549 | Reports the front connection's HTTP major version encoding, which may be 1 |
| 17550 | for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire |
| 17551 | encoding and not on the version present in the request header. |
| 17552 | |
Geoff Simmons | 7185b78 | 2019-08-27 18:31:16 +0200 | [diff] [blame] | 17553 | fc_pp_authority : string |
| 17554 | Returns the authority TLV sent by the client in the PROXY protocol header, |
| 17555 | if any. |
| 17556 | |
Tim Duesterhus | d1b15b6 | 2020-03-13 12:34:23 +0100 | [diff] [blame] | 17557 | fc_pp_unique_id : string |
| 17558 | Returns the unique ID TLV sent by the client in the PROXY protocol header, |
| 17559 | if any. |
| 17560 | |
Emeric Brun | 4f60301 | 2017-01-05 15:11:44 +0100 | [diff] [blame] | 17561 | fc_rcvd_proxy : boolean |
| 17562 | Returns true if the client initiated the connection with a PROXY protocol |
| 17563 | header. |
| 17564 | |
Thierry Fournier / OZON.IO | 6310bef | 2016-07-24 20:16:50 +0200 | [diff] [blame] | 17565 | fc_rtt(<unit>) : integer |
| 17566 | Returns the Round Trip Time (RTT) measured by the kernel for the client |
| 17567 | connection. <unit> is facultative, by default the unit is milliseconds. <unit> |
| 17568 | can be set to "ms" for milliseconds or "us" for microseconds. If the server |
| 17569 | connection is not established, if the connection is not TCP or if the |
| 17570 | operating system does not support TCP_INFO, for example Linux kernels before |
| 17571 | 2.4, the sample fetch fails. |
| 17572 | |
| 17573 | fc_rttvar(<unit>) : integer |
| 17574 | Returns the Round Trip Time (RTT) variance measured by the kernel for the |
| 17575 | client connection. <unit> is facultative, by default the unit is milliseconds. |
| 17576 | <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the |
| 17577 | server connection is not established, if the connection is not TCP or if the |
| 17578 | operating system does not support TCP_INFO, for example Linux kernels before |
| 17579 | 2.4, the sample fetch fails. |
| 17580 | |
Christopher Faulet | ba0c53e | 2019-10-17 14:40:48 +0200 | [diff] [blame] | 17581 | fc_unacked : integer |
Joe Williams | 30fcd39 | 2016-08-10 07:06:44 -0700 | [diff] [blame] | 17582 | Returns the unacked counter measured by the kernel for the client connection. |
| 17583 | If the server connection is not established, if the connection is not TCP or |
| 17584 | if the operating system does not support TCP_INFO, for example Linux kernels |
| 17585 | before 2.4, the sample fetch fails. |
| 17586 | |
Christopher Faulet | ba0c53e | 2019-10-17 14:40:48 +0200 | [diff] [blame] | 17587 | fc_sacked : integer |
Joe Williams | 30fcd39 | 2016-08-10 07:06:44 -0700 | [diff] [blame] | 17588 | Returns the sacked counter measured by the kernel for the client connection. |
| 17589 | If the server connection is not established, if the connection is not TCP or |
| 17590 | if the operating system does not support TCP_INFO, for example Linux kernels |
| 17591 | before 2.4, the sample fetch fails. |
| 17592 | |
Christopher Faulet | ba0c53e | 2019-10-17 14:40:48 +0200 | [diff] [blame] | 17593 | fc_retrans : integer |
Joe Williams | 30fcd39 | 2016-08-10 07:06:44 -0700 | [diff] [blame] | 17594 | Returns the retransmits counter measured by the kernel for the client |
| 17595 | connection. If the server connection is not established, if the connection is |
| 17596 | not TCP or if the operating system does not support TCP_INFO, for example |
| 17597 | Linux kernels before 2.4, the sample fetch fails. |
| 17598 | |
Christopher Faulet | ba0c53e | 2019-10-17 14:40:48 +0200 | [diff] [blame] | 17599 | fc_fackets : integer |
Joe Williams | 30fcd39 | 2016-08-10 07:06:44 -0700 | [diff] [blame] | 17600 | Returns the fack counter measured by the kernel for the client |
| 17601 | connection. If the server connection is not established, if the connection is |
| 17602 | not TCP or if the operating system does not support TCP_INFO, for example |
| 17603 | Linux kernels before 2.4, the sample fetch fails. |
| 17604 | |
Christopher Faulet | ba0c53e | 2019-10-17 14:40:48 +0200 | [diff] [blame] | 17605 | fc_lost : integer |
Joe Williams | 30fcd39 | 2016-08-10 07:06:44 -0700 | [diff] [blame] | 17606 | Returns the lost counter measured by the kernel for the client |
| 17607 | connection. If the server connection is not established, if the connection is |
| 17608 | not TCP or if the operating system does not support TCP_INFO, for example |
| 17609 | Linux kernels before 2.4, the sample fetch fails. |
| 17610 | |
Christopher Faulet | ba0c53e | 2019-10-17 14:40:48 +0200 | [diff] [blame] | 17611 | fc_reordering : integer |
Joe Williams | 30fcd39 | 2016-08-10 07:06:44 -0700 | [diff] [blame] | 17612 | Returns the reordering counter measured by the kernel for the client |
| 17613 | connection. If the server connection is not established, if the connection is |
| 17614 | not TCP or if the operating system does not support TCP_INFO, for example |
| 17615 | Linux kernels before 2.4, the sample fetch fails. |
| 17616 | |
Marcin Deranek | 9a66dfb | 2018-04-13 14:37:50 +0200 | [diff] [blame] | 17617 | fe_defbe : string |
| 17618 | Returns a string containing the frontend's default backend name. It can be |
| 17619 | used in frontends to check which backend will handle requests by default. |
| 17620 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17621 | fe_id : integer |
| 17622 | Returns an integer containing the current frontend's id. It can be used in |
Marcin Deranek | 6e413ed | 2016-12-13 12:40:01 +0100 | [diff] [blame] | 17623 | backends to check from which frontend it was called, or to stick all users |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17624 | coming via a same frontend to the same server. |
| 17625 | |
Marcin Deranek | d2471c2 | 2016-12-12 14:08:05 +0100 | [diff] [blame] | 17626 | fe_name : string |
| 17627 | Returns a string containing the current frontend's name. It can be used in |
| 17628 | backends to check from which frontend it was called, or to stick all users |
| 17629 | coming via a same frontend to the same server. |
| 17630 | |
Amaury Denoyelle | da184d5 | 2020-12-10 13:43:55 +0100 | [diff] [blame] | 17631 | fe_client_timeout : integer |
| 17632 | Returns the configuration value in millisecond for the client timeout of the |
| 17633 | current frontend. |
| 17634 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17635 | sc_bytes_in_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17636 | sc0_bytes_in_rate([<table>]) : integer |
| 17637 | sc1_bytes_in_rate([<table>]) : integer |
| 17638 | sc2_bytes_in_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17639 | Returns the average client-to-server bytes rate from the currently tracked |
| 17640 | counters, measured in amount of bytes over the period configured in the |
| 17641 | table. See also src_bytes_in_rate. |
| 17642 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17643 | sc_bytes_out_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17644 | sc0_bytes_out_rate([<table>]) : integer |
| 17645 | sc1_bytes_out_rate([<table>]) : integer |
| 17646 | sc2_bytes_out_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17647 | Returns the average server-to-client bytes rate from the currently tracked |
| 17648 | counters, measured in amount of bytes over the period configured in the |
| 17649 | table. See also src_bytes_out_rate. |
| 17650 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17651 | sc_clr_gpc0(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17652 | sc0_clr_gpc0([<table>]) : integer |
| 17653 | sc1_clr_gpc0([<table>]) : integer |
| 17654 | sc2_clr_gpc0([<table>]) : integer |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17655 | Clears the first General Purpose Counter associated to the currently tracked |
| 17656 | counters, and returns its previous value. Before the first invocation, the |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 17657 | stored value is zero, so first invocation will always return zero. This is |
| 17658 | typically used as a second ACL in an expression in order to mark a connection |
| 17659 | when a first ACL was verified : |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17660 | |
Jarno Huuskonen | 676f622 | 2017-03-30 09:19:45 +0300 | [diff] [blame] | 17661 | Example: |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17662 | # block if 5 consecutive requests continue to come faster than 10 sess |
| 17663 | # 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] | 17664 | acl abuse sc0_http_req_rate gt 10 |
| 17665 | acl kill sc0_inc_gpc0 gt 5 |
| 17666 | acl save sc0_clr_gpc0 ge 0 |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17667 | tcp-request connection accept if !abuse save |
| 17668 | tcp-request connection reject if abuse kill |
| 17669 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17670 | sc_clr_gpc1(<ctr>[,<table>]) : integer |
| 17671 | sc0_clr_gpc1([<table>]) : integer |
| 17672 | sc1_clr_gpc1([<table>]) : integer |
| 17673 | sc2_clr_gpc1([<table>]) : integer |
| 17674 | Clears the second General Purpose Counter associated to the currently tracked |
| 17675 | counters, and returns its previous value. Before the first invocation, the |
| 17676 | stored value is zero, so first invocation will always return zero. This is |
| 17677 | typically used as a second ACL in an expression in order to mark a connection |
| 17678 | when a first ACL was verified. |
| 17679 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17680 | sc_conn_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17681 | sc0_conn_cnt([<table>]) : integer |
| 17682 | sc1_conn_cnt([<table>]) : integer |
| 17683 | sc2_conn_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17684 | Returns the cumulative number of incoming connections from currently tracked |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17685 | counters. See also src_conn_cnt. |
| 17686 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17687 | sc_conn_cur(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17688 | sc0_conn_cur([<table>]) : integer |
| 17689 | sc1_conn_cur([<table>]) : integer |
| 17690 | sc2_conn_cur([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17691 | Returns the current amount of concurrent connections tracking the same |
| 17692 | tracked counters. This number is automatically incremented when tracking |
| 17693 | begins and decremented when tracking stops. See also src_conn_cur. |
| 17694 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17695 | sc_conn_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17696 | sc0_conn_rate([<table>]) : integer |
| 17697 | sc1_conn_rate([<table>]) : integer |
| 17698 | sc2_conn_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17699 | Returns the average connection rate from the currently tracked counters, |
| 17700 | measured in amount of connections over the period configured in the table. |
| 17701 | See also src_conn_rate. |
| 17702 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17703 | sc_get_gpc0(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17704 | sc0_get_gpc0([<table>]) : integer |
| 17705 | sc1_get_gpc0([<table>]) : integer |
| 17706 | sc2_get_gpc0([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17707 | Returns the value of the first General Purpose Counter associated to the |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 17708 | 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] | 17709 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17710 | sc_get_gpc1(<ctr>[,<table>]) : integer |
| 17711 | sc0_get_gpc1([<table>]) : integer |
| 17712 | sc1_get_gpc1([<table>]) : integer |
| 17713 | sc2_get_gpc1([<table>]) : integer |
| 17714 | Returns the value of the second General Purpose Counter associated to the |
| 17715 | currently tracked counters. See also src_get_gpc1 and sc/sc0/sc1/sc2_inc_gpc1. |
| 17716 | |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 17717 | sc_get_gpt0(<ctr>[,<table>]) : integer |
| 17718 | sc0_get_gpt0([<table>]) : integer |
| 17719 | sc1_get_gpt0([<table>]) : integer |
| 17720 | sc2_get_gpt0([<table>]) : integer |
| 17721 | Returns the value of the first General Purpose Tag associated to the |
| 17722 | currently tracked counters. See also src_get_gpt0. |
| 17723 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17724 | sc_gpc0_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17725 | sc0_gpc0_rate([<table>]) : integer |
| 17726 | sc1_gpc0_rate([<table>]) : integer |
| 17727 | sc2_gpc0_rate([<table>]) : integer |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 17728 | Returns the average increment rate of the first General Purpose Counter |
| 17729 | associated to the currently tracked counters. It reports the frequency |
| 17730 | which the gpc0 counter was incremented over the configured period. See also |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 17731 | src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note |
| 17732 | that the "gpc0_rate" counter must be stored in the stick-table for a value to |
| 17733 | be returned, as "gpc0" only holds the event count. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17734 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17735 | sc_gpc1_rate(<ctr>[,<table>]) : integer |
| 17736 | sc0_gpc1_rate([<table>]) : integer |
| 17737 | sc1_gpc1_rate([<table>]) : integer |
| 17738 | sc2_gpc1_rate([<table>]) : integer |
| 17739 | Returns the average increment rate of the second General Purpose Counter |
| 17740 | associated to the currently tracked counters. It reports the frequency |
| 17741 | which the gpc1 counter was incremented over the configured period. See also |
| 17742 | src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note |
| 17743 | that the "gpc1_rate" counter must be stored in the stick-table for a value to |
| 17744 | be returned, as "gpc1" only holds the event count. |
| 17745 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17746 | sc_http_err_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17747 | sc0_http_err_cnt([<table>]) : integer |
| 17748 | sc1_http_err_cnt([<table>]) : integer |
| 17749 | sc2_http_err_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17750 | Returns the cumulative number of HTTP errors from the currently tracked |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17751 | counters. This includes the both request errors and 4xx error responses. |
| 17752 | See also src_http_err_cnt. |
| 17753 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17754 | sc_http_err_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17755 | sc0_http_err_rate([<table>]) : integer |
| 17756 | sc1_http_err_rate([<table>]) : integer |
| 17757 | sc2_http_err_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17758 | Returns the average rate of HTTP errors from the currently tracked counters, |
| 17759 | measured in amount of errors over the period configured in the table. This |
| 17760 | includes the both request errors and 4xx error responses. See also |
| 17761 | src_http_err_rate. |
| 17762 | |
Willy Tarreau | 826f3ab | 2021-02-10 12:07:15 +0100 | [diff] [blame] | 17763 | sc_http_fail_cnt(<ctr>[,<table>]) : integer |
| 17764 | sc0_http_fail_cnt([<table>]) : integer |
| 17765 | sc1_http_fail_cnt([<table>]) : integer |
| 17766 | sc2_http_fail_cnt([<table>]) : integer |
| 17767 | Returns the cumulative number of HTTP response failures from the currently |
| 17768 | tracked counters. This includes the both response errors and 5xx status codes |
| 17769 | other than 501 and 505. See also src_http_fail_cnt. |
| 17770 | |
| 17771 | sc_http_fail_rate(<ctr>[,<table>]) : integer |
| 17772 | sc0_http_fail_rate([<table>]) : integer |
| 17773 | sc1_http_fail_rate([<table>]) : integer |
| 17774 | sc2_http_fail_rate([<table>]) : integer |
| 17775 | Returns the average rate of HTTP response failures from the currently tracked |
| 17776 | counters, measured in amount of failures over the period configured in the |
| 17777 | table. This includes the both response errors and 5xx status codes other than |
| 17778 | 501 and 505. See also src_http_fail_rate. |
| 17779 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17780 | sc_http_req_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17781 | sc0_http_req_cnt([<table>]) : integer |
| 17782 | sc1_http_req_cnt([<table>]) : integer |
| 17783 | sc2_http_req_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17784 | Returns the cumulative number of HTTP requests from the currently tracked |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17785 | counters. This includes every started request, valid or not. See also |
| 17786 | src_http_req_cnt. |
| 17787 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17788 | sc_http_req_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17789 | sc0_http_req_rate([<table>]) : integer |
| 17790 | sc1_http_req_rate([<table>]) : integer |
| 17791 | sc2_http_req_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17792 | Returns the average rate of HTTP requests from the currently tracked |
| 17793 | counters, measured in amount of requests over the period configured in |
| 17794 | the table. This includes every started request, valid or not. See also |
| 17795 | src_http_req_rate. |
| 17796 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17797 | sc_inc_gpc0(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17798 | sc0_inc_gpc0([<table>]) : integer |
| 17799 | sc1_inc_gpc0([<table>]) : integer |
| 17800 | sc2_inc_gpc0([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17801 | Increments the first General Purpose Counter associated to the currently |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 17802 | tracked counters, and returns its new value. Before the first invocation, |
| 17803 | the stored value is zero, so first invocation will increase it to 1 and will |
| 17804 | return 1. This is typically used as a second ACL in an expression in order |
| 17805 | to mark a connection when a first ACL was verified : |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17806 | |
Jarno Huuskonen | 676f622 | 2017-03-30 09:19:45 +0300 | [diff] [blame] | 17807 | Example: |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 17808 | acl abuse sc0_http_req_rate gt 10 |
| 17809 | acl kill sc0_inc_gpc0 gt 0 |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17810 | tcp-request connection reject if abuse kill |
| 17811 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17812 | sc_inc_gpc1(<ctr>[,<table>]) : integer |
| 17813 | sc0_inc_gpc1([<table>]) : integer |
| 17814 | sc1_inc_gpc1([<table>]) : integer |
| 17815 | sc2_inc_gpc1([<table>]) : integer |
| 17816 | Increments the second General Purpose Counter associated to the currently |
| 17817 | tracked counters, and returns its new value. Before the first invocation, |
| 17818 | the stored value is zero, so first invocation will increase it to 1 and will |
| 17819 | return 1. This is typically used as a second ACL in an expression in order |
| 17820 | to mark a connection when a first ACL was verified. |
| 17821 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17822 | sc_kbytes_in(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17823 | sc0_kbytes_in([<table>]) : integer |
| 17824 | sc1_kbytes_in([<table>]) : integer |
| 17825 | sc2_kbytes_in([<table>]) : integer |
Willy Tarreau | a01b974 | 2014-07-10 15:29:24 +0200 | [diff] [blame] | 17826 | Returns the total amount of client-to-server data from the currently tracked |
| 17827 | counters, measured in kilobytes. The test is currently performed on 32-bit |
| 17828 | integers, which limits values to 4 terabytes. See also src_kbytes_in. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17829 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17830 | sc_kbytes_out(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17831 | sc0_kbytes_out([<table>]) : integer |
| 17832 | sc1_kbytes_out([<table>]) : integer |
| 17833 | sc2_kbytes_out([<table>]) : integer |
Willy Tarreau | a01b974 | 2014-07-10 15:29:24 +0200 | [diff] [blame] | 17834 | Returns the total amount of server-to-client data from the currently tracked |
| 17835 | counters, measured in kilobytes. The test is currently performed on 32-bit |
| 17836 | integers, which limits values to 4 terabytes. See also src_kbytes_out. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17837 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17838 | sc_sess_cnt(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17839 | sc0_sess_cnt([<table>]) : integer |
| 17840 | sc1_sess_cnt([<table>]) : integer |
| 17841 | sc2_sess_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17842 | Returns the cumulative number of incoming connections that were transformed |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17843 | into sessions, which means that they were accepted by a "tcp-request |
| 17844 | connection" rule, from the currently tracked counters. A backend may count |
| 17845 | more sessions than connections because each connection could result in many |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 17846 | backend sessions if some HTTP keep-alive is performed over the connection |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17847 | with the client. See also src_sess_cnt. |
| 17848 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17849 | sc_sess_rate(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17850 | sc0_sess_rate([<table>]) : integer |
| 17851 | sc1_sess_rate([<table>]) : integer |
| 17852 | sc2_sess_rate([<table>]) : integer |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17853 | Returns the average session rate from the currently tracked counters, |
| 17854 | measured in amount of sessions over the period configured in the table. A |
| 17855 | session is a connection that got past the early "tcp-request connection" |
| 17856 | rules. A backend may count more sessions than connections because each |
| 17857 | 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] | 17858 | performed over the connection with the client. See also src_sess_rate. |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 17859 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17860 | sc_tracked(<ctr>[,<table>]) : boolean |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17861 | sc0_tracked([<table>]) : boolean |
| 17862 | sc1_tracked([<table>]) : boolean |
| 17863 | sc2_tracked([<table>]) : boolean |
Willy Tarreau | 6f1615f | 2013-06-03 15:15:22 +0200 | [diff] [blame] | 17864 | Returns true if the designated session counter is currently being tracked by |
| 17865 | the current session. This can be useful when deciding whether or not we want |
| 17866 | to set some values in a header passed to the server. |
| 17867 | |
Cyril Bonté | 62ba870 | 2014-04-22 23:52:25 +0200 | [diff] [blame] | 17868 | sc_trackers(<ctr>[,<table>]) : integer |
Willy Tarreau | 0f791d4 | 2013-07-23 19:56:43 +0200 | [diff] [blame] | 17869 | sc0_trackers([<table>]) : integer |
| 17870 | sc1_trackers([<table>]) : integer |
| 17871 | sc2_trackers([<table>]) : integer |
Willy Tarreau | 2406db4 | 2012-12-09 12:16:43 +0100 | [diff] [blame] | 17872 | Returns the current amount of concurrent connections tracking the same |
| 17873 | tracked counters. This number is automatically incremented when tracking |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 17874 | 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] | 17875 | that it does not rely on any stored information but on the table's reference |
| 17876 | 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] | 17877 | may sometimes be more suited for layer7 tracking. It can be used to tell a |
| 17878 | server how many concurrent connections there are from a given address for |
| 17879 | example. |
Willy Tarreau | 2406db4 | 2012-12-09 12:16:43 +0100 | [diff] [blame] | 17880 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17881 | so_id : integer |
| 17882 | Returns an integer containing the current listening socket's id. It is useful |
| 17883 | in frontends involving many "bind" lines, or to stick all users coming via a |
| 17884 | same socket to the same server. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17885 | |
Jerome Magnin | eb421b2 | 2020-03-27 22:08:40 +0100 | [diff] [blame] | 17886 | so_name : string |
| 17887 | Returns a string containing the current listening socket's name, as defined |
| 17888 | with name on a "bind" line. It can serve the same purposes as so_id but with |
| 17889 | strings instead of integers. |
| 17890 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17891 | src : ip |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17892 | This is the source IPv4 address of the client of the session. It is of type |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17893 | IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are |
| 17894 | mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the |
| 17895 | TCP-level source address which is used, and not the address of a client |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 17896 | behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind |
| 17897 | directive is used, it can be the address of a client behind another |
| 17898 | PROXY-protocol compatible component for all rule sets except |
Willy Tarreau | 64ded3d | 2019-01-23 10:02:15 +0100 | [diff] [blame] | 17899 | "tcp-request connection" which sees the real address. When the incoming |
| 17900 | connection passed through address translation or redirection involving |
| 17901 | connection tracking, the original destination address before the redirection |
| 17902 | will be reported. On Linux systems, the source and destination may seldom |
| 17903 | appear reversed if the nf_conntrack_tcp_loose sysctl is set, because a late |
| 17904 | response may reopen a timed out connection and switch what is believed to be |
| 17905 | the source and the destination. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 17906 | |
Thierry FOURNIER | d5f624d | 2013-11-26 11:52:33 +0100 | [diff] [blame] | 17907 | Example: |
| 17908 | # add an HTTP header in requests with the originating address' country |
| 17909 | http-request set-header X-Country %[src,map_ip(geoip.lst)] |
| 17910 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17911 | src_bytes_in_rate([<table>]) : integer |
| 17912 | Returns the average bytes rate from the incoming connection's source address |
| 17913 | in the current proxy's stick-table or in the designated stick-table, measured |
| 17914 | 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] | 17915 | 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] | 17916 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17917 | src_bytes_out_rate([<table>]) : integer |
| 17918 | Returns the average bytes rate to the incoming connection's source address in |
| 17919 | 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] | 17920 | 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] | 17921 | 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] | 17922 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17923 | src_clr_gpc0([<table>]) : integer |
| 17924 | Clears the first General Purpose Counter associated to the incoming |
| 17925 | connection's source address in the current proxy's stick-table or in the |
| 17926 | designated stick-table, and returns its previous value. If the address is not |
| 17927 | found, an entry is created and 0 is returned. This is typically used as a |
| 17928 | second ACL in an expression in order to mark a connection when a first ACL |
| 17929 | was verified : |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17930 | |
Jarno Huuskonen | 676f622 | 2017-03-30 09:19:45 +0300 | [diff] [blame] | 17931 | Example: |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17932 | # block if 5 consecutive requests continue to come faster than 10 sess |
| 17933 | # per second, and reset the counter as soon as the traffic slows down. |
| 17934 | acl abuse src_http_req_rate gt 10 |
| 17935 | acl kill src_inc_gpc0 gt 5 |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 17936 | acl save src_clr_gpc0 ge 0 |
Willy Tarreau | f73cd11 | 2011-08-13 01:45:16 +0200 | [diff] [blame] | 17937 | tcp-request connection accept if !abuse save |
| 17938 | tcp-request connection reject if abuse kill |
| 17939 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17940 | src_clr_gpc1([<table>]) : integer |
| 17941 | Clears the second General Purpose Counter associated to the incoming |
| 17942 | connection's source address in the current proxy's stick-table or in the |
| 17943 | designated stick-table, and returns its previous value. If the address is not |
| 17944 | found, an entry is created and 0 is returned. This is typically used as a |
| 17945 | second ACL in an expression in order to mark a connection when a first ACL |
| 17946 | was verified. |
| 17947 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17948 | src_conn_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 17949 | Returns the cumulative number of connections initiated from the current |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17950 | 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] | 17951 | 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] | 17952 | See also sc/sc0/sc1/sc2_conn_cnt. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 17953 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17954 | src_conn_cur([<table>]) : integer |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 17955 | Returns the current amount of concurrent connections initiated from the |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17956 | current incoming connection's source address in the current proxy's |
| 17957 | 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] | 17958 | zero is returned. See also sc/sc0/sc1/sc2_conn_cur. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 17959 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17960 | src_conn_rate([<table>]) : integer |
| 17961 | Returns the average connection rate from the incoming connection's source |
| 17962 | address in the current proxy's stick-table or in the designated stick-table, |
| 17963 | 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] | 17964 | 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] | 17965 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17966 | src_get_gpc0([<table>]) : integer |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 17967 | Returns the value of the first General Purpose Counter associated to the |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17968 | 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] | 17969 | 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] | 17970 | See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 17971 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17972 | src_get_gpc1([<table>]) : integer |
| 17973 | Returns the value of the second General Purpose Counter associated to the |
| 17974 | incoming connection's source address in the current proxy's stick-table or in |
| 17975 | the designated stick-table. If the address is not found, zero is returned. |
| 17976 | See also sc/sc0/sc1/sc2_get_gpc1 and src_inc_gpc1. |
| 17977 | |
Thierry FOURNIER | 236657b | 2015-08-19 08:25:14 +0200 | [diff] [blame] | 17978 | src_get_gpt0([<table>]) : integer |
| 17979 | Returns the value of the first General Purpose Tag associated to the |
| 17980 | incoming connection's source address in the current proxy's stick-table or in |
| 17981 | the designated stick-table. If the address is not found, zero is returned. |
| 17982 | See also sc/sc0/sc1/sc2_get_gpt0. |
| 17983 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17984 | src_gpc0_rate([<table>]) : integer |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 17985 | Returns the average increment rate of the first General Purpose Counter |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 17986 | 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] | 17987 | stick-table or in the designated stick-table. It reports the frequency |
| 17988 | which the gpc0 counter was incremented over the configured period. See also |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 17989 | sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note |
| 17990 | that the "gpc0_rate" counter must be stored in the stick-table for a value to |
| 17991 | be returned, as "gpc0" only holds the event count. |
Willy Tarreau | ba2ffd1 | 2013-05-29 15:54:14 +0200 | [diff] [blame] | 17992 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 17993 | src_gpc1_rate([<table>]) : integer |
| 17994 | Returns the average increment rate of the second General Purpose Counter |
| 17995 | associated to the incoming connection's source address in the current proxy's |
| 17996 | stick-table or in the designated stick-table. It reports the frequency |
| 17997 | which the gpc1 counter was incremented over the configured period. See also |
| 17998 | sc/sc0/sc1/sc2_gpc1_rate, src_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note |
| 17999 | that the "gpc1_rate" counter must be stored in the stick-table for a value to |
| 18000 | be returned, as "gpc1" only holds the event count. |
| 18001 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18002 | src_http_err_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18003 | Returns the cumulative number of HTTP errors from the incoming connection's |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18004 | 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] | 18005 | stick-table. This includes the both request errors and 4xx error responses. |
Willy Tarreau | 4d4149c | 2013-07-23 19:33:46 +0200 | [diff] [blame] | 18006 | 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] | 18007 | returned. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18008 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18009 | src_http_err_rate([<table>]) : integer |
| 18010 | Returns the average rate of HTTP errors from the incoming connection's source |
| 18011 | address in the current proxy's stick-table or in the designated stick-table, |
| 18012 | measured in amount of errors over the period configured in the table. This |
| 18013 | 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] | 18014 | 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] | 18015 | |
Willy Tarreau | 826f3ab | 2021-02-10 12:07:15 +0100 | [diff] [blame] | 18016 | src_http_fail_cnt([<table>]) : integer |
| 18017 | Returns the cumulative number of HTTP response failures triggered by the |
| 18018 | incoming connection's source address in the current proxy's stick-table or in |
Ilya Shipitsin | 0de36ad | 2021-02-20 00:23:36 +0500 | [diff] [blame] | 18019 | the designated stick-table. This includes the both response errors and 5xx |
Willy Tarreau | 826f3ab | 2021-02-10 12:07:15 +0100 | [diff] [blame] | 18020 | status codes other than 501 and 505. See also sc/sc0/sc1/sc2_http_fail_cnt. |
| 18021 | If the address is not found, zero is returned. |
| 18022 | |
| 18023 | src_http_fail_rate([<table>]) : integer |
| 18024 | Returns the average rate of HTTP response failures triggered by the incoming |
| 18025 | connection's source address in the current proxy's stick-table or in the |
| 18026 | designated stick-table, measured in amount of failures over the period |
| 18027 | configured in the table. This includes the both response errors and 5xx |
| 18028 | status codes other than 501 and 505. If the address is not found, zero is |
| 18029 | returned. See also sc/sc0/sc1/sc2_http_fail_rate. |
| 18030 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18031 | src_http_req_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18032 | Returns the cumulative number of HTTP requests from the incoming connection's |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18033 | source address in the current proxy's stick-table or in the designated stick- |
| 18034 | 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] | 18035 | 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] | 18036 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18037 | src_http_req_rate([<table>]) : integer |
| 18038 | Returns the average rate of HTTP requests from the incoming connection's |
| 18039 | source address in the current proxy's stick-table or in the designated stick- |
| 18040 | table, measured in amount of requests over the period configured in the |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18041 | 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] | 18042 | 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] | 18043 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18044 | src_inc_gpc0([<table>]) : integer |
| 18045 | Increments the first General Purpose Counter associated to the incoming |
| 18046 | connection's source address in the current proxy's stick-table or in the |
| 18047 | 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] | 18048 | 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] | 18049 | This is typically used as a second ACL in an expression in order to mark a |
| 18050 | connection when a first ACL was verified : |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18051 | |
Jarno Huuskonen | 676f622 | 2017-03-30 09:19:45 +0300 | [diff] [blame] | 18052 | Example: |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18053 | acl abuse src_http_req_rate gt 10 |
Willy Tarreau | 869948b | 2013-01-04 14:14:57 +0100 | [diff] [blame] | 18054 | acl kill src_inc_gpc0 gt 0 |
Willy Tarreau | e965652 | 2010-08-17 15:40:09 +0200 | [diff] [blame] | 18055 | tcp-request connection reject if abuse kill |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18056 | |
Frédéric Lécaille | 6778b27 | 2018-01-29 15:22:53 +0100 | [diff] [blame] | 18057 | src_inc_gpc1([<table>]) : integer |
| 18058 | Increments the second General Purpose Counter associated to the incoming |
| 18059 | connection's source address in the current proxy's stick-table or in the |
| 18060 | designated stick-table, and returns its new value. If the address is not |
| 18061 | found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc1. |
| 18062 | This is typically used as a second ACL in an expression in order to mark a |
| 18063 | connection when a first ACL was verified. |
| 18064 | |
Willy Tarreau | 16e0156 | 2016-08-09 16:46:18 +0200 | [diff] [blame] | 18065 | src_is_local : boolean |
| 18066 | Returns true if the source address of the incoming connection is local to the |
| 18067 | system, or false if the address doesn't exist on the system, meaning that it |
| 18068 | comes from a remote machine. Note that UNIX addresses are considered local. |
| 18069 | It can be useful to apply certain access restrictions based on where the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18070 | client comes from (e.g. require auth or https for remote machines). Please |
Willy Tarreau | 16e0156 | 2016-08-09 16:46:18 +0200 | [diff] [blame] | 18071 | note that the check involves a few system calls, so it's better to do it only |
| 18072 | once per connection. |
| 18073 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18074 | src_kbytes_in([<table>]) : integer |
Willy Tarreau | a01b974 | 2014-07-10 15:29:24 +0200 | [diff] [blame] | 18075 | Returns the total amount of data received from the incoming connection's |
| 18076 | source address in the current proxy's stick-table or in the designated |
| 18077 | stick-table, measured in kilobytes. If the address is not found, zero is |
| 18078 | returned. The test is currently performed on 32-bit integers, which limits |
| 18079 | values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18080 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18081 | src_kbytes_out([<table>]) : integer |
Willy Tarreau | a01b974 | 2014-07-10 15:29:24 +0200 | [diff] [blame] | 18082 | Returns the total amount of data sent to the incoming connection's source |
| 18083 | address in the current proxy's stick-table or in the designated stick-table, |
| 18084 | measured in kilobytes. If the address is not found, zero is returned. The |
| 18085 | test is currently performed on 32-bit integers, which limits values to 4 |
| 18086 | terabytes. See also sc/sc0/sc1/sc2_kbytes_out. |
Willy Tarreau | a975b8f | 2010-06-05 19:13:27 +0200 | [diff] [blame] | 18087 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18088 | src_port : integer |
| 18089 | Returns an integer value corresponding to the TCP source port of the |
| 18090 | connection on the client side, which is the port the client connected from. |
| 18091 | Usage of this function is very limited as modern protocols do not care much |
| 18092 | about source ports nowadays. |
Willy Tarreau | 079ff0a | 2009-03-05 21:34:28 +0100 | [diff] [blame] | 18093 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18094 | src_sess_cnt([<table>]) : integer |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18095 | Returns the cumulative number of connections initiated from the incoming |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18096 | connection's source IPv4 address in the current proxy's stick-table or in the |
| 18097 | designated stick-table, that were transformed into sessions, which means that |
| 18098 | 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] | 18099 | is returned. See also sc/sc0/sc1/sc2_sess_cnt. |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18100 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18101 | src_sess_rate([<table>]) : integer |
| 18102 | Returns the average session rate from the incoming connection's source |
| 18103 | address in the current proxy's stick-table or in the designated stick-table, |
| 18104 | measured in amount of sessions over the period configured in the table. A |
| 18105 | 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] | 18106 | 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] | 18107 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18108 | src_updt_conn_cnt([<table>]) : integer |
| 18109 | Creates or updates the entry associated to the incoming connection's source |
| 18110 | address in the current proxy's stick-table or in the designated stick-table. |
| 18111 | This table must be configured to store the "conn_cnt" data type, otherwise |
| 18112 | the match will be ignored. The current count is incremented by one, and the |
| 18113 | expiration timer refreshed. The updated count is returned, so this match |
| 18114 | can't return zero. This was used to reject service abusers based on their |
| 18115 | source address. Note: it is recommended to use the more complete "track-sc*" |
| 18116 | actions in "tcp-request" rules instead. |
Willy Tarreau | a975b8f | 2010-06-05 19:13:27 +0200 | [diff] [blame] | 18117 | |
| 18118 | Example : |
| 18119 | # This frontend limits incoming SSH connections to 3 per 10 second for |
| 18120 | # each source address, and rejects excess connections until a 10 second |
| 18121 | # silence is observed. At most 20 addresses are tracked. |
| 18122 | listen ssh |
| 18123 | bind :22 |
| 18124 | mode tcp |
| 18125 | maxconn 100 |
Willy Tarreau | c9705a1 | 2010-07-27 20:05:50 +0200 | [diff] [blame] | 18126 | stick-table type ip size 20 expire 10s store conn_cnt |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18127 | tcp-request content reject if { src_updt_conn_cnt gt 3 } |
Willy Tarreau | a975b8f | 2010-06-05 19:13:27 +0200 | [diff] [blame] | 18128 | server local 127.0.0.1:22 |
| 18129 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18130 | srv_id : integer |
| 18131 | Returns an integer containing the server's id when processing the response. |
| 18132 | While it's almost only used with ACLs, it may be used for logging or |
Christopher Faulet | d1b4464 | 2020-04-30 09:51:15 +0200 | [diff] [blame] | 18133 | debugging. It can also be used in a tcp-check or an http-check ruleset. |
Hervé COMMOWICK | daa824e | 2011-08-05 12:09:44 +0200 | [diff] [blame] | 18134 | |
vkill | 1dfd165 | 2019-10-30 16:58:14 +0800 | [diff] [blame] | 18135 | srv_name : string |
| 18136 | Returns a string containing the server's name when processing the response. |
| 18137 | While it's almost only used with ACLs, it may be used for logging or |
Christopher Faulet | d1b4464 | 2020-04-30 09:51:15 +0200 | [diff] [blame] | 18138 | debugging. It can also be used in a tcp-check or an http-check ruleset. |
vkill | 1dfd165 | 2019-10-30 16:58:14 +0800 | [diff] [blame] | 18139 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 18140 | 7.3.4. Fetching samples at Layer 5 |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18141 | ---------------------------------- |
Willy Tarreau | 0b1cd94 | 2010-05-16 22:18:27 +0200 | [diff] [blame] | 18142 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18143 | The layer 5 usually describes just the session layer which in haproxy is |
| 18144 | closest to the session once all the connection handshakes are finished, but |
| 18145 | when no content is yet made available. The fetch methods described here are |
| 18146 | 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] | 18147 | future information. Those generally include the results of SSL negotiations. |
Willy Tarreau | c735a07 | 2011-03-29 00:57:02 +0200 | [diff] [blame] | 18148 | |
Ben Shillito | f25e8e5 | 2016-12-02 14:25:37 +0000 | [diff] [blame] | 18149 | 51d.all(<prop>[,<prop>*]) : string |
| 18150 | Returns values for the properties requested as a string, where values are |
| 18151 | separated by the delimiter specified with "51degrees-property-separator". |
| 18152 | The device is identified using all the important HTTP headers from the |
| 18153 | request. The function can be passed up to five property names, and if a |
| 18154 | property name can't be found, the value "NoData" is returned. |
| 18155 | |
| 18156 | Example : |
| 18157 | # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request |
| 18158 | # containing the three properties requested using all relevant headers from |
| 18159 | # the request. |
| 18160 | frontend http-in |
| 18161 | bind *:8081 |
| 18162 | default_backend servers |
| 18163 | http-request set-header X-51D-DeviceTypeMobileTablet \ |
| 18164 | %[51d.all(DeviceType,IsMobile,IsTablet)] |
| 18165 | |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18166 | ssl_bc : boolean |
| 18167 | Returns true when the back connection was made via an SSL/TLS transport |
| 18168 | layer and is locally deciphered. This means the outgoing connection was made |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18169 | other a server with the "ssl" option. It can be used in a tcp-check or an |
| 18170 | http-check ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18171 | |
| 18172 | ssl_bc_alg_keysize : integer |
| 18173 | Returns the symmetric cipher key size supported in bits when the outgoing |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18174 | connection was made over an SSL/TLS transport layer. It can be used in a |
| 18175 | tcp-check or an http-check ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18176 | |
Olivier Houchard | 6b77f49 | 2018-11-22 18:18:29 +0100 | [diff] [blame] | 18177 | ssl_bc_alpn : string |
| 18178 | This extracts the Application Layer Protocol Negotiation field from an |
| 18179 | outgoing connection made via a TLS transport layer. |
Michael Prokop | 4438c60 | 2019-05-24 10:25:45 +0200 | [diff] [blame] | 18180 | The result is a string containing the protocol name negotiated with the |
Olivier Houchard | 6b77f49 | 2018-11-22 18:18:29 +0100 | [diff] [blame] | 18181 | server. The SSL library must have been built with support for TLS |
| 18182 | extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is |
| 18183 | not advertised unless the "alpn" keyword on the "server" line specifies a |
| 18184 | protocol list. Also, nothing forces the server to pick a protocol from this |
| 18185 | list, any other one may be requested. The TLS ALPN extension is meant to |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18186 | replace the TLS NPN extension. See also "ssl_bc_npn". It can be used in a |
| 18187 | tcp-check or an http-check ruleset. |
Olivier Houchard | 6b77f49 | 2018-11-22 18:18:29 +0100 | [diff] [blame] | 18188 | |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18189 | ssl_bc_cipher : string |
| 18190 | Returns the name of the used cipher when the outgoing connection was made |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18191 | over an SSL/TLS transport layer. It can be used in a tcp-check or an |
| 18192 | http-check ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18193 | |
Patrick Hemmer | 6567466 | 2019-06-04 08:13:03 -0400 | [diff] [blame] | 18194 | ssl_bc_client_random : binary |
| 18195 | Returns the client random of the back connection when the incoming connection |
| 18196 | was made over an SSL/TLS transport layer. It is useful to to decrypt traffic |
| 18197 | sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL. |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18198 | It can be used in a tcp-check or an http-check ruleset. |
Patrick Hemmer | 6567466 | 2019-06-04 08:13:03 -0400 | [diff] [blame] | 18199 | |
Emeric Brun | 74f7ffa | 2018-02-19 16:14:12 +0100 | [diff] [blame] | 18200 | ssl_bc_is_resumed : boolean |
| 18201 | Returns true when the back connection was made over an SSL/TLS transport |
| 18202 | layer and the newly created SSL session was resumed using a cached |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18203 | session or a TLS ticket. It can be used in a tcp-check or an http-check |
| 18204 | ruleset. |
Emeric Brun | 74f7ffa | 2018-02-19 16:14:12 +0100 | [diff] [blame] | 18205 | |
Olivier Houchard | 6b77f49 | 2018-11-22 18:18:29 +0100 | [diff] [blame] | 18206 | ssl_bc_npn : string |
| 18207 | This extracts the Next Protocol Negotiation field from an outgoing connection |
| 18208 | made via a TLS transport layer. The result is a string containing the |
Michael Prokop | 4438c60 | 2019-05-24 10:25:45 +0200 | [diff] [blame] | 18209 | protocol name negotiated with the server . The SSL library must have been |
Olivier Houchard | 6b77f49 | 2018-11-22 18:18:29 +0100 | [diff] [blame] | 18210 | built with support for TLS extensions enabled (check haproxy -vv). Note that |
| 18211 | the TLS NPN extension is not advertised unless the "npn" keyword on the |
| 18212 | "server" line specifies a protocol list. Also, nothing forces the server to |
| 18213 | pick a protocol from this list, any other one may be used. Please note that |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18214 | the TLS NPN extension was replaced with ALPN. It can be used in a tcp-check |
| 18215 | or an http-check ruleset. |
Olivier Houchard | 6b77f49 | 2018-11-22 18:18:29 +0100 | [diff] [blame] | 18216 | |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18217 | ssl_bc_protocol : string |
| 18218 | Returns the name of the used protocol when the outgoing connection was made |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18219 | over an SSL/TLS transport layer. It can be used in a tcp-check or an |
| 18220 | http-check ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18221 | |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 18222 | ssl_bc_unique_id : binary |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18223 | When the outgoing connection was made over an SSL/TLS transport layer, |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 18224 | returns the TLS unique ID as defined in RFC5929 section 3. The unique id |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18225 | can be encoded to base64 using the converter: "ssl_bc_unique_id,base64". It |
| 18226 | can be used in a tcp-check or an http-check ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18227 | |
Patrick Hemmer | 6567466 | 2019-06-04 08:13:03 -0400 | [diff] [blame] | 18228 | ssl_bc_server_random : binary |
| 18229 | Returns the server random of the back connection when the incoming connection |
| 18230 | was made over an SSL/TLS transport layer. It is useful to to decrypt traffic |
| 18231 | sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL. |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18232 | It can be used in a tcp-check or an http-check ruleset. |
Patrick Hemmer | 6567466 | 2019-06-04 08:13:03 -0400 | [diff] [blame] | 18233 | |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18234 | ssl_bc_session_id : binary |
| 18235 | Returns the SSL ID of the back connection when the outgoing connection was |
| 18236 | made over an SSL/TLS transport layer. It is useful to log if we want to know |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18237 | if session was reused or not. It can be used in a tcp-check or an http-check |
| 18238 | ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18239 | |
Patrick Hemmer | e027547 | 2018-04-28 19:15:51 -0400 | [diff] [blame] | 18240 | ssl_bc_session_key : binary |
| 18241 | Returns the SSL session master key of the back connection when the outgoing |
| 18242 | connection was made over an SSL/TLS transport layer. It is useful to decrypt |
| 18243 | traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18244 | BoringSSL. It can be used in a tcp-check or an http-check ruleset. |
Patrick Hemmer | e027547 | 2018-04-28 19:15:51 -0400 | [diff] [blame] | 18245 | |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18246 | ssl_bc_use_keysize : integer |
| 18247 | Returns the symmetric cipher key size used in bits when the outgoing |
Christopher Faulet | d92ea7f | 2020-04-30 10:03:55 +0200 | [diff] [blame] | 18248 | connection was made over an SSL/TLS transport layer. It can be used in a |
| 18249 | tcp-check or an http-check ruleset. |
Emeric Brun | 645ae79 | 2014-04-30 14:21:06 +0200 | [diff] [blame] | 18250 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18251 | ssl_c_ca_err : integer |
| 18252 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18253 | returns the ID of the first error detected during verification of the client |
| 18254 | certificate at depth > 0, or 0 if no error was encountered during this |
| 18255 | verification process. Please refer to your SSL library's documentation to |
| 18256 | find the exhaustive list of error codes. |
Willy Tarreau | c735a07 | 2011-03-29 00:57:02 +0200 | [diff] [blame] | 18257 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18258 | ssl_c_ca_err_depth : integer |
| 18259 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18260 | returns the depth in the CA chain of the first error detected during the |
| 18261 | verification of the client certificate. If no error is encountered, 0 is |
| 18262 | returned. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 18263 | |
Christopher Faulet | 70d10d1 | 2020-11-06 12:10:33 +0100 | [diff] [blame] | 18264 | ssl_c_chain_der : binary |
William Dauchy | a598b50 | 2020-08-06 18:11:38 +0200 | [diff] [blame] | 18265 | Returns the DER formatted chain certificate presented by the client when the |
| 18266 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 18267 | an ACL, the value(s) to match against can be passed in hexadecimal form. One |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 18268 | can parse the result with any lib accepting ASN.1 DER data. It currently |
William Dauchy | a598b50 | 2020-08-06 18:11:38 +0200 | [diff] [blame] | 18269 | does not support resumed sessions. |
| 18270 | |
Christopher Faulet | 70d10d1 | 2020-11-06 12:10:33 +0100 | [diff] [blame] | 18271 | ssl_c_der : binary |
| 18272 | Returns the DER formatted certificate presented by the client when the |
| 18273 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 18274 | an ACL, the value(s) to match against can be passed in hexadecimal form. |
| 18275 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18276 | ssl_c_err : integer |
| 18277 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18278 | returns the ID of the first error detected during verification at depth 0, or |
| 18279 | 0 if no error was encountered during this verification process. Please refer |
| 18280 | to your SSL library's documentation to find the exhaustive list of error |
| 18281 | codes. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 18282 | |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18283 | ssl_c_i_dn([<entry>[,<occ>[,<format>]]]) : string |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18284 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18285 | returns the full distinguished name of the issuer of the certificate |
| 18286 | presented by the client when no <entry> is specified, or the value of the |
| 18287 | first given entry found from the beginning of the DN. If a positive/negative |
| 18288 | occurrence number is specified as the optional second argument, it returns |
| 18289 | the value of the nth given entry value from the beginning/end of the DN. |
| 18290 | For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and |
| 18291 | "ssl_c_i_dn(CN)" retrieves the common name. |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18292 | The <format> parameter allows you to receive the DN suitable for |
| 18293 | consumption by different protocols. Currently supported is rfc2253 for |
| 18294 | LDAP v3. |
| 18295 | If you'd like to modify the format only you can specify an empty string |
| 18296 | and zero for the first two parameters. Example: ssl_c_i_dn(,0,rfc2253) |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 18297 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18298 | ssl_c_key_alg : string |
| 18299 | Returns the name of the algorithm used to generate the key of the certificate |
| 18300 | presented by the client when the incoming connection was made over an SSL/TLS |
| 18301 | transport layer. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 18302 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18303 | ssl_c_notafter : string |
| 18304 | Returns the end date presented by the client as a formatted string |
| 18305 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 18306 | transport layer. |
Emeric Brun | bede3d0 | 2009-06-30 17:54:00 +0200 | [diff] [blame] | 18307 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18308 | ssl_c_notbefore : string |
| 18309 | Returns the start date presented by the client as a formatted string |
| 18310 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 18311 | transport layer. |
Willy Tarreau | b6672b5 | 2011-12-12 17:23:41 +0100 | [diff] [blame] | 18312 | |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18313 | ssl_c_s_dn([<entry>[,<occ>[,<format>]]]) : string |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18314 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18315 | returns the full distinguished name of the subject of the certificate |
| 18316 | presented by the client when no <entry> is specified, or the value of the |
| 18317 | first given entry found from the beginning of the DN. If a positive/negative |
| 18318 | occurrence number is specified as the optional second argument, it returns |
| 18319 | the value of the nth given entry value from the beginning/end of the DN. |
| 18320 | For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and |
| 18321 | "ssl_c_s_dn(CN)" retrieves the common name. |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18322 | The <format> parameter allows you to receive the DN suitable for |
| 18323 | consumption by different protocols. Currently supported is rfc2253 for |
| 18324 | LDAP v3. |
| 18325 | If you'd like to modify the format only you can specify an empty string |
| 18326 | and zero for the first two parameters. Example: ssl_c_s_dn(,0,rfc2253) |
Willy Tarreau | b6672b5 | 2011-12-12 17:23:41 +0100 | [diff] [blame] | 18327 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18328 | ssl_c_serial : binary |
| 18329 | Returns the serial of the certificate presented by the client when the |
| 18330 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 18331 | 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] | 18332 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18333 | ssl_c_sha1 : binary |
| 18334 | Returns the SHA-1 fingerprint of the certificate presented by the client when |
| 18335 | the incoming connection was made over an SSL/TLS transport layer. This can be |
| 18336 | used to stick a client to a server, or to pass this information to a server. |
Willy Tarreau | 2d0caa3 | 2014-07-02 19:01:22 +0200 | [diff] [blame] | 18337 | Note that the output is binary, so if you want to pass that signature to the |
| 18338 | server, you need to encode it in hex or base64, such as in the example below: |
| 18339 | |
Jarno Huuskonen | 676f622 | 2017-03-30 09:19:45 +0300 | [diff] [blame] | 18340 | Example: |
Willy Tarreau | 2d0caa3 | 2014-07-02 19:01:22 +0200 | [diff] [blame] | 18341 | http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex] |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 18342 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18343 | ssl_c_sig_alg : string |
| 18344 | Returns the name of the algorithm used to sign the certificate presented by |
| 18345 | the client when the incoming connection was made over an SSL/TLS transport |
| 18346 | layer. |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 18347 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18348 | ssl_c_used : boolean |
| 18349 | Returns true if current SSL session uses a client certificate even if current |
| 18350 | connection uses SSL session resumption. See also "ssl_fc_has_crt". |
Emeric Brun | 7f56e74 | 2012-10-19 18:15:40 +0200 | [diff] [blame] | 18351 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18352 | ssl_c_verify : integer |
| 18353 | Returns the verify result error ID when the incoming connection was made over |
| 18354 | an SSL/TLS transport layer, otherwise zero if no error is encountered. Please |
| 18355 | refer to your SSL library's documentation for an exhaustive list of error |
| 18356 | codes. |
Emeric Brun | ce5ad80 | 2012-10-22 14:11:22 +0200 | [diff] [blame] | 18357 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18358 | ssl_c_version : integer |
| 18359 | Returns the version of the certificate presented by the client when the |
| 18360 | incoming connection was made over an SSL/TLS transport layer. |
Emeric Brun | ce5ad80 | 2012-10-22 14:11:22 +0200 | [diff] [blame] | 18361 | |
Emeric Brun | 43e7958 | 2014-10-29 19:03:26 +0100 | [diff] [blame] | 18362 | ssl_f_der : binary |
| 18363 | Returns the DER formatted certificate presented by the frontend when the |
| 18364 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 18365 | an ACL, the value(s) to match against can be passed in hexadecimal form. |
| 18366 | |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18367 | ssl_f_i_dn([<entry>[,<occ>[,<format>]]]) : string |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18368 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18369 | returns the full distinguished name of the issuer of the certificate |
| 18370 | presented by the frontend when no <entry> is specified, or the value of the |
| 18371 | 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] | 18372 | occurrence number is specified as the optional second argument, it returns |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18373 | the value of the nth given entry value from the beginning/end of the DN. |
| 18374 | For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and |
| 18375 | "ssl_f_i_dn(CN)" retrieves the common name. |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18376 | The <format> parameter allows you to receive the DN suitable for |
| 18377 | consumption by different protocols. Currently supported is rfc2253 for |
| 18378 | LDAP v3. |
| 18379 | If you'd like to modify the format only you can specify an empty string |
| 18380 | and zero for the first two parameters. Example: ssl_f_i_dn(,0,rfc2253) |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 18381 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18382 | ssl_f_key_alg : string |
| 18383 | Returns the name of the algorithm used to generate the key of the certificate |
| 18384 | presented by the frontend when the incoming connection was made over an |
| 18385 | SSL/TLS transport layer. |
Emeric Brun | 7f56e74 | 2012-10-19 18:15:40 +0200 | [diff] [blame] | 18386 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18387 | ssl_f_notafter : string |
| 18388 | Returns the end date presented by the frontend as a formatted string |
| 18389 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 18390 | transport layer. |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 18391 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18392 | ssl_f_notbefore : string |
| 18393 | Returns the start date presented by the frontend as a formatted string |
| 18394 | YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS |
| 18395 | transport layer. |
Emeric Brun | 8785589 | 2012-10-17 17:39:35 +0200 | [diff] [blame] | 18396 | |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18397 | ssl_f_s_dn([<entry>[,<occ>[,<format>]]]) : string |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18398 | When the incoming connection was made over an SSL/TLS transport layer, |
| 18399 | returns the full distinguished name of the subject of the certificate |
| 18400 | presented by the frontend when no <entry> is specified, or the value of the |
| 18401 | first given entry found from the beginning of the DN. If a positive/negative |
| 18402 | occurrence number is specified as the optional second argument, it returns |
| 18403 | the value of the nth given entry value from the beginning/end of the DN. |
| 18404 | For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and |
| 18405 | "ssl_f_s_dn(CN)" retrieves the common name. |
Elliot Otchet | 71f8297 | 2020-01-15 08:12:14 -0500 | [diff] [blame] | 18406 | The <format> parameter allows you to receive the DN suitable for |
| 18407 | consumption by different protocols. Currently supported is rfc2253 for |
| 18408 | LDAP v3. |
| 18409 | If you'd like to modify the format only you can specify an empty string |
| 18410 | and zero for the first two parameters. Example: ssl_f_s_dn(,0,rfc2253) |
Emeric Brun | ce5ad80 | 2012-10-22 14:11:22 +0200 | [diff] [blame] | 18411 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18412 | ssl_f_serial : binary |
| 18413 | Returns the serial of the certificate presented by the frontend when the |
| 18414 | incoming connection was made over an SSL/TLS transport layer. When used for |
| 18415 | 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] | 18416 | |
Emeric Brun | 55f4fa8 | 2014-04-30 17:11:25 +0200 | [diff] [blame] | 18417 | ssl_f_sha1 : binary |
| 18418 | Returns the SHA-1 fingerprint of the certificate presented by the frontend |
| 18419 | when the incoming connection was made over an SSL/TLS transport layer. This |
| 18420 | can be used to know which certificate was chosen using SNI. |
| 18421 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18422 | ssl_f_sig_alg : string |
| 18423 | Returns the name of the algorithm used to sign the certificate presented by |
| 18424 | the frontend when the incoming connection was made over an SSL/TLS transport |
| 18425 | layer. |
Emeric Brun | 7f56e74 | 2012-10-19 18:15:40 +0200 | [diff] [blame] | 18426 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18427 | ssl_f_version : integer |
| 18428 | Returns the version of the certificate presented by the frontend when the |
| 18429 | incoming connection was made over an SSL/TLS transport layer. |
| 18430 | |
| 18431 | ssl_fc : boolean |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 18432 | Returns true when the front connection was made via an SSL/TLS transport |
| 18433 | layer and is locally deciphered. This means it has matched a socket declared |
| 18434 | with a "bind" line having the "ssl" option. |
| 18435 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18436 | Example : |
| 18437 | # This passes "X-Proto: https" to servers when client connects over SSL |
| 18438 | listen http-https |
| 18439 | bind :80 |
| 18440 | bind :443 ssl crt /etc/haproxy.pem |
| 18441 | http-request add-header X-Proto https if { ssl_fc } |
| 18442 | |
| 18443 | ssl_fc_alg_keysize : integer |
| 18444 | Returns the symmetric cipher key size supported in bits when the incoming |
| 18445 | connection was made over an SSL/TLS transport layer. |
| 18446 | |
| 18447 | ssl_fc_alpn : string |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 18448 | This extracts the Application Layer Protocol Negotiation field from an |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18449 | incoming connection made via a TLS transport layer and locally deciphered by |
| 18450 | haproxy. The result is a string containing the protocol name advertised by |
| 18451 | the client. The SSL library must have been built with support for TLS |
| 18452 | extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is |
| 18453 | not advertised unless the "alpn" keyword on the "bind" line specifies a |
| 18454 | protocol list. Also, nothing forces the client to pick a protocol from this |
| 18455 | list, any other one may be requested. The TLS ALPN extension is meant to |
| 18456 | replace the TLS NPN extension. See also "ssl_fc_npn". |
| 18457 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18458 | ssl_fc_cipher : string |
| 18459 | Returns the name of the used cipher when the incoming connection was made |
| 18460 | over an SSL/TLS transport layer. |
Willy Tarreau | ab861d3 | 2013-04-02 02:30:41 +0200 | [diff] [blame] | 18461 | |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 18462 | ssl_fc_cipherlist_bin : binary |
| 18463 | Returns the binary form of the client hello cipher list. The maximum returned |
| 18464 | value length is according with the value of |
Emmanuel Hocdet | aaee750 | 2017-03-07 18:34:58 +0100 | [diff] [blame] | 18465 | "tune.ssl.capture-cipherlist-size". |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 18466 | |
| 18467 | ssl_fc_cipherlist_hex : string |
| 18468 | Returns the binary form of the client hello cipher list encoded as |
| 18469 | hexadecimal. The maximum returned value length is according with the value of |
Emmanuel Hocdet | aaee750 | 2017-03-07 18:34:58 +0100 | [diff] [blame] | 18470 | "tune.ssl.capture-cipherlist-size". |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 18471 | |
| 18472 | ssl_fc_cipherlist_str : string |
| 18473 | Returns the decoded text form of the client hello cipher list. The maximum |
| 18474 | number of ciphers returned is according with the value of |
| 18475 | "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18476 | available with OpenSSL >= 1.0.2. If the function is not enabled, this |
Emmanuel Hocdet | ddcde19 | 2017-09-01 17:32:08 +0200 | [diff] [blame] | 18477 | sample-fetch returns the hash like "ssl_fc_cipherlist_xxh". |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 18478 | |
| 18479 | ssl_fc_cipherlist_xxh : integer |
| 18480 | Returns a xxh64 of the cipher list. This hash can be return only is the value |
| 18481 | "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash |
Emmanuel Hocdet | aaee750 | 2017-03-07 18:34:58 +0100 | [diff] [blame] | 18482 | take in account all the data of the cipher list. |
Thierry FOURNIER | 5bf7732 | 2017-02-25 12:45:22 +0100 | [diff] [blame] | 18483 | |
Patrick Hemmer | 6567466 | 2019-06-04 08:13:03 -0400 | [diff] [blame] | 18484 | ssl_fc_client_random : binary |
| 18485 | Returns the client random of the front connection when the incoming connection |
| 18486 | was made over an SSL/TLS transport layer. It is useful to to decrypt traffic |
| 18487 | sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL. |
| 18488 | |
William Lallemand | 7d42ef5 | 2020-07-06 11:41:30 +0200 | [diff] [blame] | 18489 | ssl_fc_client_early_traffic_secret : string |
| 18490 | Return the CLIENT_EARLY_TRAFFIC_SECRET as an hexadecimal string for the |
| 18491 | front connection when the incoming connection was made over a TLS 1.3 |
| 18492 | transport layer. |
| 18493 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18494 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18495 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18496 | "tune.ssl.keylog" |
| 18497 | |
| 18498 | ssl_fc_client_handshake_traffic_secret : string |
| 18499 | Return the CLIENT_HANDSHAKE_TRAFFIC_SECRET as an hexadecimal string for the |
| 18500 | front connection when the incoming connection was made over a TLS 1.3 |
| 18501 | transport layer. |
| 18502 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18503 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18504 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18505 | "tune.ssl.keylog" |
| 18506 | |
| 18507 | ssl_fc_client_traffic_secret_0 : string |
| 18508 | Return the CLIENT_TRAFFIC_SECRET_0 as an hexadecimal string for the |
| 18509 | front connection when the incoming connection was made over a TLS 1.3 |
| 18510 | transport layer. |
| 18511 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18512 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18513 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18514 | "tune.ssl.keylog" |
| 18515 | |
| 18516 | ssl_fc_exporter_secret : string |
| 18517 | Return the EXPORTER_SECRET as an hexadecimal string for the |
| 18518 | front connection when the incoming connection was made over a TLS 1.3 |
| 18519 | transport layer. |
| 18520 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18521 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18522 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18523 | "tune.ssl.keylog" |
| 18524 | |
| 18525 | ssl_fc_early_exporter_secret : string |
| 18526 | Return the EARLY_EXPORTER_SECRET as an hexadecimal string for the |
| 18527 | front connection when the incoming connection was made over an TLS 1.3 |
| 18528 | transport layer. |
| 18529 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18530 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18531 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18532 | "tune.ssl.keylog" |
| 18533 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18534 | ssl_fc_has_crt : boolean |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 18535 | Returns true if a client certificate is present in an incoming connection over |
| 18536 | SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'. |
Emeric Brun | 9143d37 | 2012-12-20 15:44:16 +0100 | [diff] [blame] | 18537 | Note: on SSL session resumption with Session ID or TLS ticket, client |
| 18538 | certificate is not present in the current connection but may be retrieved |
| 18539 | from the cache or the ticket. So prefer "ssl_c_used" if you want to check if |
| 18540 | current SSL session uses a client certificate. |
Emeric Brun | 2525b6b | 2012-10-18 15:59:43 +0200 | [diff] [blame] | 18541 | |
Olivier Houchard | ccaa7de | 2017-10-02 11:51:03 +0200 | [diff] [blame] | 18542 | ssl_fc_has_early : boolean |
| 18543 | Returns true if early data were sent, and the handshake didn't happen yet. As |
| 18544 | it has security implications, it is useful to be able to refuse those, or |
| 18545 | wait until the handshake happened. |
| 18546 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18547 | ssl_fc_has_sni : boolean |
| 18548 | 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] | 18549 | in an incoming connection was made over an SSL/TLS transport layer. Returns |
| 18550 | true when the incoming connection presents a TLS SNI field. This requires |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 18551 | that the SSL library is built with support for TLS extensions enabled (check |
Willy Tarreau | f7bc57c | 2012-10-03 00:19:48 +0200 | [diff] [blame] | 18552 | haproxy -vv). |
Willy Tarreau | 7875d09 | 2012-09-10 08:20:03 +0200 | [diff] [blame] | 18553 | |
Nenad Merdanovic | 1516fe3 | 2016-05-17 03:31:21 +0200 | [diff] [blame] | 18554 | ssl_fc_is_resumed : boolean |
Nenad Merdanovic | 26ea822 | 2015-05-18 02:28:57 +0200 | [diff] [blame] | 18555 | Returns true if the SSL/TLS session has been resumed through the use of |
Jérôme Magnin | 4a326cb | 2018-01-15 14:01:17 +0100 | [diff] [blame] | 18556 | SSL session cache or TLS tickets on an incoming connection over an SSL/TLS |
| 18557 | transport layer. |
Nenad Merdanovic | 26ea822 | 2015-05-18 02:28:57 +0200 | [diff] [blame] | 18558 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18559 | ssl_fc_npn : string |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 18560 | This extracts the Next Protocol Negotiation field from an incoming connection |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18561 | made via a TLS transport layer and locally deciphered by haproxy. The result |
| 18562 | is a string containing the protocol name advertised by the client. The SSL |
| 18563 | library must have been built with support for TLS extensions enabled (check |
| 18564 | haproxy -vv). Note that the TLS NPN extension is not advertised unless the |
| 18565 | "npn" keyword on the "bind" line specifies a protocol list. Also, nothing |
| 18566 | forces the client to pick a protocol from this list, any other one may be |
| 18567 | requested. Please note that the TLS NPN extension was replaced with ALPN. |
Willy Tarreau | a33c654 | 2012-10-15 13:19:06 +0200 | [diff] [blame] | 18568 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18569 | ssl_fc_protocol : string |
| 18570 | Returns the name of the used protocol when the incoming connection was made |
| 18571 | over an SSL/TLS transport layer. |
Willy Tarreau | 7875d09 | 2012-09-10 08:20:03 +0200 | [diff] [blame] | 18572 | |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 18573 | ssl_fc_unique_id : binary |
David S | c1ad52e | 2014-04-08 18:48:47 -0400 | [diff] [blame] | 18574 | When the incoming connection was made over an SSL/TLS transport layer, |
Emeric Brun | b73a9b0 | 2014-04-30 18:49:19 +0200 | [diff] [blame] | 18575 | returns the TLS unique ID as defined in RFC5929 section 3. The unique id |
| 18576 | 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] | 18577 | |
William Lallemand | 7d42ef5 | 2020-07-06 11:41:30 +0200 | [diff] [blame] | 18578 | ssl_fc_server_handshake_traffic_secret : string |
| 18579 | Return the SERVER_HANDSHAKE_TRAFFIC_SECRET as an hexadecimal string for the |
| 18580 | front connection when the incoming connection was made over a TLS 1.3 |
| 18581 | transport layer. |
| 18582 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18583 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18584 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18585 | "tune.ssl.keylog" |
| 18586 | |
| 18587 | ssl_fc_server_traffic_secret_0 : string |
| 18588 | Return the SERVER_TRAFFIC_SECRET_0 as an hexadecimal string for the |
| 18589 | front connection when the incoming connection was made over an TLS 1.3 |
| 18590 | transport layer. |
| 18591 | Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL |
| 18592 | keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be |
| 18593 | activated with "tune.ssl.keylog on" in the global section. See also |
| 18594 | "tune.ssl.keylog" |
| 18595 | |
Patrick Hemmer | 6567466 | 2019-06-04 08:13:03 -0400 | [diff] [blame] | 18596 | ssl_fc_server_random : binary |
| 18597 | Returns the server random of the front connection when the incoming connection |
| 18598 | was made over an SSL/TLS transport layer. It is useful to to decrypt traffic |
| 18599 | sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL. |
| 18600 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18601 | ssl_fc_session_id : binary |
| 18602 | Returns the SSL ID of the front connection when the incoming connection was |
| 18603 | made over an SSL/TLS transport layer. It is useful to stick a given client to |
| 18604 | a server. It is important to note that some browsers refresh their session ID |
| 18605 | every few minutes. |
Willy Tarreau | 7875d09 | 2012-09-10 08:20:03 +0200 | [diff] [blame] | 18606 | |
Patrick Hemmer | e027547 | 2018-04-28 19:15:51 -0400 | [diff] [blame] | 18607 | ssl_fc_session_key : binary |
| 18608 | Returns the SSL session master key of the front connection when the incoming |
| 18609 | connection was made over an SSL/TLS transport layer. It is useful to decrypt |
| 18610 | traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or |
| 18611 | BoringSSL. |
| 18612 | |
| 18613 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18614 | ssl_fc_sni : string |
| 18615 | This extracts the Server Name Indication TLS extension (SNI) field from an |
| 18616 | incoming connection made via an SSL/TLS transport layer and locally |
| 18617 | deciphered by haproxy. The result (when present) typically is a string |
| 18618 | matching the HTTPS host name (253 chars or less). The SSL library must have |
| 18619 | been built with support for TLS extensions enabled (check haproxy -vv). |
| 18620 | |
| 18621 | This fetch is different from "req_ssl_sni" above in that it applies to the |
| 18622 | connection being deciphered by haproxy and not to SSL contents being blindly |
| 18623 | forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 18624 | requires that the SSL library is built with support for TLS extensions |
Cyril Bonté | 9c1eb1e | 2012-10-09 22:45:34 +0200 | [diff] [blame] | 18625 | enabled (check haproxy -vv). |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 18626 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18627 | ACL derivatives : |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18628 | ssl_fc_sni_end : suffix match |
| 18629 | ssl_fc_sni_reg : regex match |
Emeric Brun | 589fcad | 2012-10-16 14:13:26 +0200 | [diff] [blame] | 18630 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18631 | ssl_fc_use_keysize : integer |
| 18632 | Returns the symmetric cipher key size used in bits when the incoming |
| 18633 | connection was made over an SSL/TLS transport layer. |
Willy Tarreau | b6fb420 | 2008-07-20 11:18:28 +0200 | [diff] [blame] | 18634 | |
William Lallemand | bfa3e81 | 2020-06-25 20:07:18 +0200 | [diff] [blame] | 18635 | ssl_s_der : binary |
| 18636 | Returns the DER formatted certificate presented by the server when the |
| 18637 | outgoing connection was made over an SSL/TLS transport layer. When used for |
| 18638 | an ACL, the value(s) to match against can be passed in hexadecimal form. |
| 18639 | |
William Dauchy | a598b50 | 2020-08-06 18:11:38 +0200 | [diff] [blame] | 18640 | ssl_s_chain_der : binary |
| 18641 | Returns the DER formatted chain certificate presented by the server when the |
| 18642 | outgoing connection was made over an SSL/TLS transport layer. When used for |
| 18643 | an ACL, the value(s) to match against can be passed in hexadecimal form. One |
Ilya Shipitsin | 2272d8a | 2020-12-21 01:22:40 +0500 | [diff] [blame] | 18644 | can parse the result with any lib accepting ASN.1 DER data. It currently |
William Dauchy | a598b50 | 2020-08-06 18:11:38 +0200 | [diff] [blame] | 18645 | does not support resumed sessions. |
| 18646 | |
William Lallemand | bfa3e81 | 2020-06-25 20:07:18 +0200 | [diff] [blame] | 18647 | ssl_s_key_alg : string |
| 18648 | Returns the name of the algorithm used to generate the key of the certificate |
| 18649 | presented by the server when the outgoing connection was made over an |
| 18650 | SSL/TLS transport layer. |
| 18651 | |
| 18652 | ssl_s_notafter : string |
| 18653 | Returns the end date presented by the server as a formatted string |
| 18654 | YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS |
| 18655 | transport layer. |
| 18656 | |
| 18657 | ssl_s_notbefore : string |
| 18658 | Returns the start date presented by the server as a formatted string |
| 18659 | YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS |
| 18660 | transport layer. |
| 18661 | |
| 18662 | ssl_s_i_dn([<entry>[,<occ>[,<format>]]]) : string |
| 18663 | When the outgoing connection was made over an SSL/TLS transport layer, |
| 18664 | returns the full distinguished name of the issuer of the certificate |
| 18665 | presented by the server when no <entry> is specified, or the value of the |
| 18666 | first given entry found from the beginning of the DN. If a positive/negative |
| 18667 | occurrence number is specified as the optional second argument, it returns |
| 18668 | the value of the nth given entry value from the beginning/end of the DN. |
William Lallemand | 8f600c8 | 2020-06-26 09:55:06 +0200 | [diff] [blame] | 18669 | For instance, "ssl_s_i_dn(OU,2)" the second organization unit, and |
| 18670 | "ssl_s_i_dn(CN)" retrieves the common name. |
William Lallemand | bfa3e81 | 2020-06-25 20:07:18 +0200 | [diff] [blame] | 18671 | The <format> parameter allows you to receive the DN suitable for |
| 18672 | consumption by different protocols. Currently supported is rfc2253 for |
| 18673 | LDAP v3. |
| 18674 | If you'd like to modify the format only you can specify an empty string |
| 18675 | and zero for the first two parameters. Example: ssl_s_i_dn(,0,rfc2253) |
| 18676 | |
| 18677 | ssl_s_s_dn([<entry>[,<occ>[,<format>]]]) : string |
| 18678 | When the outgoing connection was made over an SSL/TLS transport layer, |
| 18679 | returns the full distinguished name of the subject of the certificate |
| 18680 | presented by the server when no <entry> is specified, or the value of the |
| 18681 | first given entry found from the beginning of the DN. If a positive/negative |
| 18682 | occurrence number is specified as the optional second argument, it returns |
| 18683 | the value of the nth given entry value from the beginning/end of the DN. |
William Lallemand | 8f600c8 | 2020-06-26 09:55:06 +0200 | [diff] [blame] | 18684 | For instance, "ssl_s_s_dn(OU,2)" the second organization unit, and |
| 18685 | "ssl_s_s_dn(CN)" retrieves the common name. |
William Lallemand | bfa3e81 | 2020-06-25 20:07:18 +0200 | [diff] [blame] | 18686 | The <format> parameter allows you to receive the DN suitable for |
| 18687 | consumption by different protocols. Currently supported is rfc2253 for |
| 18688 | LDAP v3. |
| 18689 | If you'd like to modify the format only you can specify an empty string |
| 18690 | and zero for the first two parameters. Example: ssl_s_s_dn(,0,rfc2253) |
| 18691 | |
| 18692 | ssl_s_serial : binary |
| 18693 | Returns the serial of the certificate presented by the server when the |
| 18694 | outgoing connection was made over an SSL/TLS transport layer. When used for |
| 18695 | an ACL, the value(s) to match against can be passed in hexadecimal form. |
| 18696 | |
| 18697 | ssl_s_sha1 : binary |
| 18698 | Returns the SHA-1 fingerprint of the certificate presented by the server |
| 18699 | when the outgoing connection was made over an SSL/TLS transport layer. This |
| 18700 | can be used to know which certificate was chosen using SNI. |
| 18701 | |
| 18702 | ssl_s_sig_alg : string |
| 18703 | Returns the name of the algorithm used to sign the certificate presented by |
| 18704 | the server when the outgoing connection was made over an SSL/TLS transport |
| 18705 | layer. |
| 18706 | |
| 18707 | ssl_s_version : integer |
| 18708 | Returns the version of the certificate presented by the server when the |
| 18709 | outgoing connection was made over an SSL/TLS transport layer. |
Willy Tarreau | b6fb420 | 2008-07-20 11:18:28 +0200 | [diff] [blame] | 18710 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 18711 | 7.3.5. Fetching samples from buffer contents (Layer 6) |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18712 | ------------------------------------------------------ |
Willy Tarreau | b6fb420 | 2008-07-20 11:18:28 +0200 | [diff] [blame] | 18713 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18714 | Fetching samples from buffer contents is a bit different from the previous |
| 18715 | sample fetches above because the sampled data are ephemeral. These data can |
| 18716 | only be used when they're available and will be lost when they're forwarded. |
| 18717 | For this reason, samples fetched from buffer contents during a request cannot |
| 18718 | be used in a response for example. Even while the data are being fetched, they |
| 18719 | can change. Sometimes it is necessary to set some delays or combine multiple |
| 18720 | sample fetch methods to ensure that the expected data are complete and usable, |
| 18721 | for example through TCP request content inspection. Please see the "tcp-request |
| 18722 | content" keyword for more detailed information on the subject. |
Willy Tarreau | 6264477 | 2008-07-16 18:36:06 +0200 | [diff] [blame] | 18723 | |
Christopher Faulet | a434a00 | 2021-03-25 11:58:51 +0100 | [diff] [blame] | 18724 | Warning : Following sample fetches are ignored if used from HTTP proxies. They |
| 18725 | only deal with raw contents found in the buffers. On their side, |
| 18726 | HTTTP proxies use structured content. Thus raw representation of |
| 18727 | these data are meaningless. A warning is emitted if an ACL relies on |
| 18728 | one of the following sample fetches. But it is not possible to detect |
| 18729 | all invalid usage (for instance inside a log-format string or a |
| 18730 | sample expression). So be careful. |
| 18731 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18732 | payload(<offset>,<length>) : binary (deprecated) |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18733 | This is an alias for "req.payload" when used in the context of a request (e.g. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18734 | "stick on", "stick match"), and for "res.payload" when used in the context of |
| 18735 | a response such as in "stick store response". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 18736 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18737 | payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated) |
| 18738 | This is an alias for "req.payload_lv" when used in the context of a request |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18739 | (e.g. "stick on", "stick match"), and for "res.payload_lv" when used in the |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18740 | context of a response such as in "stick store response". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 18741 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18742 | req.len : integer |
| 18743 | req_len : integer (deprecated) |
| 18744 | Returns an integer value corresponding to the number of bytes present in the |
| 18745 | request buffer. This is mostly used in ACL. It is important to understand |
| 18746 | that this test does not return false as long as the buffer is changing. This |
| 18747 | means that a check with equality to zero will almost always immediately match |
| 18748 | at the beginning of the session, while a test for more data will wait for |
| 18749 | that data to come in and return false only when haproxy is certain that no |
| 18750 | more data will come in. This test was designed to be used with TCP request |
| 18751 | content inspection. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18752 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18753 | req.payload(<offset>,<length>) : binary |
| 18754 | 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] | 18755 | in the request buffer. As a special case, if the <length> argument is zero, |
| 18756 | the the whole buffer from <offset> to the end is extracted. This can be used |
| 18757 | with ACLs in order to check for the presence of some content in a buffer at |
| 18758 | any location. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18759 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18760 | ACL alternatives : |
| 18761 | payload(<offset>,<length>) : hex binary match |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18762 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18763 | req.payload_lv(<offset1>,<length>[,<offset2>]) : binary |
| 18764 | This extracts a binary block whose size is specified at <offset1> for <length> |
| 18765 | bytes, and which starts at <offset2> if specified or just after the length in |
| 18766 | the request buffer. The <offset2> parameter also supports relative offsets if |
| 18767 | prepended with a '+' or '-' sign. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18768 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18769 | ACL alternatives : |
| 18770 | payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18771 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18772 | Example : please consult the example from the "stick store-response" keyword. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18773 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18774 | req.proto_http : boolean |
| 18775 | req_proto_http : boolean (deprecated) |
| 18776 | Returns true when data in the request buffer look like HTTP and correctly |
| 18777 | parses as such. It is the same parser as the common HTTP request parser which |
| 18778 | is used so there should be no surprises. The test does not match until the |
| 18779 | request is complete, failed or timed out. This test may be used to report the |
| 18780 | protocol in TCP logs, but the biggest use is to block TCP request analysis |
| 18781 | until a complete HTTP request is present in the buffer, for example to track |
| 18782 | a header. |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18783 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18784 | Example: |
| 18785 | # track request counts per "base" (concatenation of Host+URL) |
| 18786 | tcp-request inspect-delay 10s |
| 18787 | tcp-request content reject if !HTTP |
Willy Tarreau | be4a3ef | 2013-06-17 15:04:07 +0200 | [diff] [blame] | 18788 | tcp-request content track-sc0 base table req-rate |
Willy Tarreau | a7ad50c | 2012-04-29 15:39:40 +0200 | [diff] [blame] | 18789 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18790 | req.rdp_cookie([<name>]) : string |
| 18791 | rdp_cookie([<name>]) : string (deprecated) |
| 18792 | When the request buffer looks like the RDP protocol, extracts the RDP cookie |
| 18793 | <name>, or any cookie if unspecified. The parser only checks for the first |
| 18794 | cookie, as illustrated in the RDP protocol specification. The cookie name is |
| 18795 | case insensitive. Generally the "MSTS" cookie name will be used, as it can |
| 18796 | contain the user name of the client connecting to the server if properly |
| 18797 | configured on the client. The "MSTSHASH" cookie is often used as well for |
| 18798 | session stickiness to servers. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18799 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18800 | This differs from "balance rdp-cookie" in that any balancing algorithm may be |
| 18801 | used and thus the distribution of clients to backend servers is not linked to |
| 18802 | a hash of the RDP cookie. It is envisaged that using a balancing algorithm |
| 18803 | such as "balance roundrobin" or "balance leastconn" will lead to a more even |
| 18804 | distribution of clients to backend servers than the hash used by "balance |
| 18805 | rdp-cookie". |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18806 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18807 | ACL derivatives : |
| 18808 | req_rdp_cookie([<name>]) : exact string match |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18809 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18810 | Example : |
| 18811 | listen tse-farm |
| 18812 | bind 0.0.0.0:3389 |
| 18813 | # wait up to 5s for an RDP cookie in the request |
| 18814 | tcp-request inspect-delay 5s |
| 18815 | tcp-request content accept if RDP_COOKIE |
| 18816 | # apply RDP cookie persistence |
| 18817 | persist rdp-cookie |
| 18818 | # Persist based on the mstshash cookie |
| 18819 | # This is only useful makes sense if |
| 18820 | # balance rdp-cookie is not used |
| 18821 | stick-table type string size 204800 |
| 18822 | stick on req.rdp_cookie(mstshash) |
| 18823 | server srv1 1.1.1.1:3389 |
| 18824 | server srv1 1.1.1.2:3389 |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18825 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18826 | See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the |
| 18827 | "req_rdp_cookie" ACL. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18828 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18829 | req.rdp_cookie_cnt([name]) : integer |
| 18830 | rdp_cookie_cnt([name]) : integer (deprecated) |
| 18831 | Tries to parse the request buffer as RDP protocol, then returns an integer |
| 18832 | corresponding to the number of RDP cookies found. If an optional cookie name |
| 18833 | is passed, only cookies matching this name are considered. This is mostly |
| 18834 | used in ACL. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18835 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18836 | ACL derivatives : |
| 18837 | req_rdp_cookie_cnt([<name>]) : integer match |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18838 | |
Alex Zorin | 4afdd13 | 2018-12-30 13:56:28 +1100 | [diff] [blame] | 18839 | req.ssl_alpn : string |
| 18840 | Returns a string containing the values of the Application-Layer Protocol |
| 18841 | Negotiation (ALPN) TLS extension (RFC7301), sent by the client within the SSL |
| 18842 | ClientHello message. Note that this only applies to raw contents found in the |
| 18843 | request buffer and not to the contents deciphered via an SSL data layer, so |
| 18844 | this will not work with "bind" lines having the "ssl" option. This is useful |
| 18845 | in ACL to make a routing decision based upon the ALPN preferences of a TLS |
Jarno Huuskonen | e504f81 | 2019-01-03 07:56:49 +0200 | [diff] [blame] | 18846 | client, like in the example below. See also "ssl_fc_alpn". |
Alex Zorin | 4afdd13 | 2018-12-30 13:56:28 +1100 | [diff] [blame] | 18847 | |
| 18848 | Examples : |
| 18849 | # Wait for a client hello for at most 5 seconds |
| 18850 | tcp-request inspect-delay 5s |
| 18851 | tcp-request content accept if { req_ssl_hello_type 1 } |
Jarno Huuskonen | e504f81 | 2019-01-03 07:56:49 +0200 | [diff] [blame] | 18852 | use_backend bk_acme if { req.ssl_alpn acme-tls/1 } |
Alex Zorin | 4afdd13 | 2018-12-30 13:56:28 +1100 | [diff] [blame] | 18853 | default_backend bk_default |
| 18854 | |
Nenad Merdanovic | 5fc7d7e | 2015-07-07 22:00:17 +0200 | [diff] [blame] | 18855 | req.ssl_ec_ext : boolean |
| 18856 | Returns a boolean identifying if client sent the Supported Elliptic Curves |
| 18857 | Extension as defined in RFC4492, section 5.1. within the SSL ClientHello |
Cyril Bonté | 307ee1e | 2015-09-28 23:16:06 +0200 | [diff] [blame] | 18858 | message. This can be used to present ECC compatible clients with EC |
| 18859 | certificate and to use RSA for all others, on the same IP address. Note that |
| 18860 | this only applies to raw contents found in the request buffer and not to |
| 18861 | contents deciphered via an SSL data layer, so this will not work with "bind" |
| 18862 | lines having the "ssl" option. |
Nenad Merdanovic | 5fc7d7e | 2015-07-07 22:00:17 +0200 | [diff] [blame] | 18863 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18864 | req.ssl_hello_type : integer |
| 18865 | req_ssl_hello_type : integer (deprecated) |
| 18866 | Returns an integer value containing the type of the SSL hello message found |
| 18867 | in the request buffer if the buffer contains data that parse as a complete |
| 18868 | SSL (v3 or superior) client hello message. Note that this only applies to raw |
| 18869 | contents found in the request buffer and not to contents deciphered via an |
| 18870 | SSL data layer, so this will not work with "bind" lines having the "ssl" |
| 18871 | option. This is mostly used in ACL to detect presence of an SSL hello message |
| 18872 | that is supposed to contain an SSL session ID usable for stickiness. |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18873 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18874 | req.ssl_sni : string |
| 18875 | req_ssl_sni : string (deprecated) |
| 18876 | Returns a string containing the value of the Server Name TLS extension sent |
| 18877 | by a client in a TLS stream passing through the request buffer if the buffer |
| 18878 | contains data that parse as a complete SSL (v3 or superior) client hello |
| 18879 | message. Note that this only applies to raw contents found in the request |
| 18880 | buffer and not to contents deciphered via an SSL data layer, so this will not |
Lukas Tribus | a267b5d | 2020-07-19 00:25:06 +0200 | [diff] [blame] | 18881 | work with "bind" lines having the "ssl" option. This will only work for actual |
| 18882 | implicit TLS based protocols like HTTPS (443), IMAPS (993), SMTPS (465), |
| 18883 | however it will not work for explicit TLS based protocols, like SMTP (25/587) |
| 18884 | or IMAP (143). SNI normally contains the name of the host the client tries to |
| 18885 | connect to (for recent browsers). SNI is useful for allowing or denying access |
| 18886 | to certain hosts when SSL/TLS is used by the client. This test was designed to |
| 18887 | be used with TCP request content inspection. If content switching is needed, |
| 18888 | it is recommended to first wait for a complete client hello (type 1), like in |
| 18889 | the example below. See also "ssl_fc_sni". |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18890 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18891 | ACL derivatives : |
| 18892 | req_ssl_sni : exact string match |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18893 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18894 | Examples : |
| 18895 | # Wait for a client hello for at most 5 seconds |
| 18896 | tcp-request inspect-delay 5s |
| 18897 | tcp-request content accept if { req_ssl_hello_type 1 } |
| 18898 | use_backend bk_allow if { req_ssl_sni -f allowed_sites } |
| 18899 | default_backend bk_sorry_page |
Willy Tarreau | 04aa6a9 | 2012-04-06 18:57:55 +0200 | [diff] [blame] | 18900 | |
Pradeep Jindal | bb2acf5 | 2015-09-29 10:12:57 +0530 | [diff] [blame] | 18901 | req.ssl_st_ext : integer |
| 18902 | Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077) |
| 18903 | Returns 1 if the client sent SessionTicket TLS Extension |
| 18904 | Returns 2 if the client also sent non-zero length TLS SessionTicket |
| 18905 | Note that this only applies to raw contents found in the request buffer and |
| 18906 | not to contents deciphered via an SSL data layer, so this will not work with |
| 18907 | "bind" lines having the "ssl" option. This can for example be used to detect |
| 18908 | whether the client sent a SessionTicket or not and stick it accordingly, if |
| 18909 | no SessionTicket then stick on SessionID or don't stick as there's no server |
| 18910 | side state is there when SessionTickets are in use. |
| 18911 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18912 | req.ssl_ver : integer |
| 18913 | req_ssl_ver : integer (deprecated) |
| 18914 | Returns an integer value containing the version of the SSL/TLS protocol of a |
| 18915 | stream present in the request buffer. Both SSLv2 hello messages and SSLv3 |
| 18916 | messages are supported. TLSv1 is announced as SSL version 3.1. The value is |
| 18917 | composed of the major version multiplied by 65536, added to the minor |
| 18918 | version. Note that this only applies to raw contents found in the request |
| 18919 | buffer and not to contents deciphered via an SSL data layer, so this will not |
| 18920 | work with "bind" lines having the "ssl" option. The ACL version of the test |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18921 | matches against a decimal notation in the form MAJOR.MINOR (e.g. 3.1). This |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18922 | fetch is mostly used in ACL. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18923 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18924 | ACL derivatives : |
| 18925 | req_ssl_ver : decimal match |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18926 | |
Willy Tarreau | 47e8eba | 2013-09-11 23:28:46 +0200 | [diff] [blame] | 18927 | res.len : integer |
| 18928 | Returns an integer value corresponding to the number of bytes present in the |
| 18929 | response buffer. This is mostly used in ACL. It is important to understand |
| 18930 | that this test does not return false as long as the buffer is changing. This |
| 18931 | means that a check with equality to zero will almost always immediately match |
| 18932 | at the beginning of the session, while a test for more data will wait for |
| 18933 | that data to come in and return false only when haproxy is certain that no |
| 18934 | more data will come in. This test was designed to be used with TCP response |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 18935 | content inspection. But it may also be used in tcp-check based expect rules. |
Willy Tarreau | 47e8eba | 2013-09-11 23:28:46 +0200 | [diff] [blame] | 18936 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18937 | res.payload(<offset>,<length>) : binary |
| 18938 | 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] | 18939 | in the response buffer. As a special case, if the <length> argument is zero, |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 18940 | the whole buffer from <offset> to the end is extracted. This can be used |
Willy Tarreau | 00f0084 | 2013-08-02 11:07:32 +0200 | [diff] [blame] | 18941 | with ACLs in order to check for the presence of some content in a buffer at |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 18942 | any location. It may also be used in tcp-check based expect rules. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18943 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18944 | res.payload_lv(<offset1>,<length>[,<offset2>]) : binary |
| 18945 | This extracts a binary block whose size is specified at <offset1> for <length> |
| 18946 | bytes, and which starts at <offset2> if specified or just after the length in |
| 18947 | the response buffer. The <offset2> parameter also supports relative offsets |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 18948 | if prepended with a '+' or '-' sign. It may also be used in tcp-check based |
| 18949 | expect rules. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18950 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18951 | Example : please consult the example from the "stick store-response" keyword. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18952 | |
Willy Tarreau | 971f7b6 | 2015-09-29 14:06:59 +0200 | [diff] [blame] | 18953 | res.ssl_hello_type : integer |
| 18954 | rep_ssl_hello_type : integer (deprecated) |
| 18955 | Returns an integer value containing the type of the SSL hello message found |
| 18956 | in the response buffer if the buffer contains data that parses as a complete |
| 18957 | SSL (v3 or superior) hello message. Note that this only applies to raw |
| 18958 | contents found in the response buffer and not to contents deciphered via an |
| 18959 | SSL data layer, so this will not work with "server" lines having the "ssl" |
| 18960 | option. This is mostly used in ACL to detect presence of an SSL hello message |
| 18961 | that is supposed to contain an SSL session ID usable for stickiness. |
| 18962 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18963 | wait_end : boolean |
| 18964 | This fetch either returns true when the inspection period is over, or does |
| 18965 | not fetch. It is only used in ACLs, in conjunction with content analysis to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18966 | avoid returning a wrong verdict early. It may also be used to delay some |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18967 | actions, such as a delayed reject for some special addresses. Since it either |
| 18968 | stops the rules evaluation or immediately returns true, it is recommended to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 18969 | use this acl as the last one in a rule. Please note that the default ACL |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18970 | "WAIT_END" is always usable without prior declaration. This test was designed |
| 18971 | to be used with TCP request content inspection. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18972 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18973 | Examples : |
| 18974 | # delay every incoming request by 2 seconds |
| 18975 | tcp-request inspect-delay 2s |
| 18976 | tcp-request content accept if WAIT_END |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 18977 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18978 | # don't immediately tell bad guys they are rejected |
| 18979 | tcp-request inspect-delay 10s |
| 18980 | acl goodguys src 10.0.0.0/24 |
| 18981 | acl badguys src 10.0.1.0/24 |
| 18982 | tcp-request content accept if goodguys |
| 18983 | tcp-request content reject if badguys WAIT_END |
| 18984 | tcp-request content reject |
| 18985 | |
| 18986 | |
Thierry FOURNIER | 060762e | 2014-04-23 13:29:15 +0200 | [diff] [blame] | 18987 | 7.3.6. Fetching HTTP samples (Layer 7) |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 18988 | -------------------------------------- |
| 18989 | |
| 18990 | It is possible to fetch samples from HTTP contents, requests and responses. |
| 18991 | This application layer is also called layer 7. It is only possible to fetch the |
| 18992 | data in this section when a full HTTP request or response has been parsed from |
| 18993 | its respective request or response buffer. This is always the case with all |
| 18994 | HTTP specific rules and for sections running with "mode http". When using TCP |
| 18995 | content inspection, it may be necessary to support an inspection delay in order |
| 18996 | to let the request or response come in first. These fetches may require a bit |
| 18997 | more CPU resources than the layer 4 ones, but not much since the request and |
| 18998 | response are indexed. |
| 18999 | |
Christopher Faulet | 4d37e53 | 2021-03-26 14:44:00 +0100 | [diff] [blame] | 19000 | Note : Regarding HTTP processing from the tcp-request content rules, everything |
| 19001 | will work as expected from an HTTP proxy. However, from a TCP proxy, |
| 19002 | without an HTTP upgrade, it will only work for HTTP/1 content. For |
| 19003 | HTTP/2 content, only the preface is visible. Thus, it is only possible |
| 19004 | to rely to "req.proto_http", "req.ver" and eventually "method" sample |
| 19005 | fetches. All other L7 sample fetches will fail. After an HTTP upgrade, |
| 19006 | they will work in the same manner than from an HTTP proxy. |
| 19007 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19008 | base : string |
| 19009 | This returns the concatenation of the first Host header and the path part of |
| 19010 | the request, which starts at the first slash and ends before the question |
| 19011 | mark. It can be useful in virtual hosted environments to detect URL abuses as |
| 19012 | well as to improve shared caches efficiency. Using this with a limited size |
| 19013 | stick table also allows one to collect statistics about most commonly |
| 19014 | requested objects by host/path. With ACLs it can allow simple content |
| 19015 | switching rules involving the host and the path at the same time, such as |
| 19016 | "www.example.com/favicon.ico". See also "path" and "uri". |
| 19017 | |
| 19018 | ACL derivatives : |
| 19019 | base : exact string match |
| 19020 | base_beg : prefix match |
| 19021 | base_dir : subdir match |
| 19022 | base_dom : domain match |
| 19023 | base_end : suffix match |
| 19024 | base_len : length match |
| 19025 | base_reg : regex match |
| 19026 | base_sub : substring match |
| 19027 | |
| 19028 | base32 : integer |
| 19029 | This returns a 32-bit hash of the value returned by the "base" fetch method |
| 19030 | above. This is useful to track per-URL activity on high traffic sites without |
| 19031 | having to store all URLs. Instead a shorter hash is stored, saving a lot of |
Willy Tarreau | 23ec4ca | 2014-07-15 20:15:37 +0200 | [diff] [blame] | 19032 | memory. The output type is an unsigned integer. The hash function used is |
| 19033 | SDBM with full avalanche on the output. Technically, base32 is exactly equal |
| 19034 | to "base,sdbm(1)". |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19035 | |
| 19036 | base32+src : binary |
| 19037 | This returns the concatenation of the base32 fetch above and the src fetch |
| 19038 | below. The resulting type is of type binary, with a size of 8 or 20 bytes |
| 19039 | depending on the source address family. This can be used to track per-IP, |
| 19040 | per-URL counters. |
| 19041 | |
Yves Lafon | b4d3708 | 2021-02-11 11:01:28 +0100 | [diff] [blame] | 19042 | baseq : string |
| 19043 | This returns the concatenation of the first Host header and the path part of |
| 19044 | the request with the query-string, which starts at the first slash. Using this |
| 19045 | instead of "base" allows one to properly identify the target resource, for |
| 19046 | statistics or caching use cases. See also "path", "pathq" and "base". |
| 19047 | |
William Lallemand | 65ad6e1 | 2014-01-31 15:08:02 +0100 | [diff] [blame] | 19048 | capture.req.hdr(<idx>) : string |
| 19049 | This extracts the content of the header captured by the "capture request |
| 19050 | header", idx is the position of the capture keyword in the configuration. |
| 19051 | The first entry is an index of 0. See also: "capture request header". |
| 19052 | |
| 19053 | capture.req.method : string |
| 19054 | This extracts the METHOD of an HTTP request. It can be used in both request |
| 19055 | and response. Unlike "method", it can be used in both request and response |
| 19056 | because it's allocated. |
| 19057 | |
| 19058 | capture.req.uri : string |
| 19059 | This extracts the request's URI, which starts at the first slash and ends |
| 19060 | before the first space in the request (without the host part). Unlike "path" |
| 19061 | and "url", it can be used in both request and response because it's |
| 19062 | allocated. |
| 19063 | |
Willy Tarreau | 3c1b5ec | 2014-04-24 23:41:57 +0200 | [diff] [blame] | 19064 | capture.req.ver : string |
| 19065 | This extracts the request's HTTP version and returns either "HTTP/1.0" or |
| 19066 | "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and |
| 19067 | logs because it relies on a persistent flag. |
| 19068 | |
William Lallemand | 65ad6e1 | 2014-01-31 15:08:02 +0100 | [diff] [blame] | 19069 | capture.res.hdr(<idx>) : string |
| 19070 | This extracts the content of the header captured by the "capture response |
| 19071 | header", idx is the position of the capture keyword in the configuration. |
| 19072 | The first entry is an index of 0. |
| 19073 | See also: "capture response header" |
| 19074 | |
Willy Tarreau | 3c1b5ec | 2014-04-24 23:41:57 +0200 | [diff] [blame] | 19075 | capture.res.ver : string |
| 19076 | This extracts the response's HTTP version and returns either "HTTP/1.0" or |
| 19077 | "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a |
| 19078 | persistent flag. |
| 19079 | |
Willy Tarreau | a5910cc | 2015-05-02 00:46:08 +0200 | [diff] [blame] | 19080 | req.body : binary |
Christopher Faulet | af4dc4c | 2020-05-05 17:33:25 +0200 | [diff] [blame] | 19081 | This returns the HTTP request's available body as a block of data. It is |
| 19082 | recommended to use "option http-buffer-request" to be sure to wait, as much |
| 19083 | as possible, for the request's body. |
Willy Tarreau | a5910cc | 2015-05-02 00:46:08 +0200 | [diff] [blame] | 19084 | |
Thierry FOURNIER | 9826c77 | 2015-05-20 15:50:54 +0200 | [diff] [blame] | 19085 | req.body_param([<name>) : string |
| 19086 | This fetch assumes that the body of the POST request is url-encoded. The user |
| 19087 | can check if the "content-type" contains the value |
| 19088 | "application/x-www-form-urlencoded". This extracts the first occurrence of the |
| 19089 | parameter <name> in the body, which ends before '&'. The parameter name is |
| 19090 | case-sensitive. If no name is given, any parameter will match, and the first |
| 19091 | one will be returned. The result is a string corresponding to the value of the |
| 19092 | parameter <name> as presented in the request body (no URL decoding is |
| 19093 | performed). Note that the ACL version of this fetch iterates over multiple |
| 19094 | parameters and will iteratively report all parameters values if no name is |
| 19095 | given. |
| 19096 | |
Willy Tarreau | a5910cc | 2015-05-02 00:46:08 +0200 | [diff] [blame] | 19097 | req.body_len : integer |
| 19098 | This returns the length of the HTTP request's available body in bytes. It may |
| 19099 | be lower than the advertised length if the body is larger than the buffer. It |
Christopher Faulet | af4dc4c | 2020-05-05 17:33:25 +0200 | [diff] [blame] | 19100 | is recommended to use "option http-buffer-request" to be sure to wait, as |
| 19101 | much as possible, for the request's body. |
Willy Tarreau | a5910cc | 2015-05-02 00:46:08 +0200 | [diff] [blame] | 19102 | |
| 19103 | req.body_size : integer |
| 19104 | This returns the advertised length of the HTTP request's body in bytes. It |
Christopher Faulet | af4dc4c | 2020-05-05 17:33:25 +0200 | [diff] [blame] | 19105 | will represent the advertised Content-Length header, or the size of the |
| 19106 | available data in case of chunked encoding. |
Willy Tarreau | a5910cc | 2015-05-02 00:46:08 +0200 | [diff] [blame] | 19107 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19108 | req.cook([<name>]) : string |
| 19109 | cook([<name>]) : string (deprecated) |
| 19110 | This extracts the last occurrence of the cookie name <name> on a "Cookie" |
| 19111 | header line from the request, and returns its value as string. If no name is |
| 19112 | specified, the first cookie value is returned. When used with ACLs, all |
| 19113 | matching cookies are evaluated. Spaces around the name and the value are |
| 19114 | ignored as requested by the Cookie header specification (RFC6265). The cookie |
| 19115 | name is case-sensitive. Empty cookies are valid, so an empty cookie may very |
| 19116 | well return an empty value if it is present. Use the "found" match to detect |
| 19117 | presence. Use the res.cook() variant for response cookies sent by the server. |
| 19118 | |
| 19119 | ACL derivatives : |
| 19120 | cook([<name>]) : exact string match |
| 19121 | cook_beg([<name>]) : prefix match |
| 19122 | cook_dir([<name>]) : subdir match |
| 19123 | cook_dom([<name>]) : domain match |
| 19124 | cook_end([<name>]) : suffix match |
| 19125 | cook_len([<name>]) : length match |
| 19126 | cook_reg([<name>]) : regex match |
| 19127 | cook_sub([<name>]) : substring match |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19128 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19129 | req.cook_cnt([<name>]) : integer |
| 19130 | cook_cnt([<name>]) : integer (deprecated) |
| 19131 | Returns an integer value representing the number of occurrences of the cookie |
| 19132 | <name> in the request, or all cookies if <name> is not specified. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19133 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19134 | req.cook_val([<name>]) : integer |
| 19135 | cook_val([<name>]) : integer (deprecated) |
| 19136 | This extracts the last occurrence of the cookie name <name> on a "Cookie" |
| 19137 | header line from the request, and converts its value to an integer which is |
| 19138 | returned. If no name is specified, the first cookie value is returned. When |
| 19139 | 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] | 19140 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19141 | cookie([<name>]) : string (deprecated) |
| 19142 | This extracts the last occurrence of the cookie name <name> on a "Cookie" |
| 19143 | header line from the request, or a "Set-Cookie" header from the response, and |
| 19144 | returns its value as a string. A typical use is to get multiple clients |
| 19145 | sharing a same profile use the same server. This can be similar to what |
Willy Tarreau | 294d0f0 | 2015-08-10 19:40:12 +0200 | [diff] [blame] | 19146 | "appsession" did with the "request-learn" statement, but with support for |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19147 | multi-peer synchronization and state keeping across restarts. If no name is |
| 19148 | specified, the first cookie value is returned. This fetch should not be used |
| 19149 | anymore and should be replaced by req.cook() or res.cook() instead as it |
| 19150 | ambiguously uses the direction based on the context where it is used. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19151 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19152 | hdr([<name>[,<occ>]]) : string |
| 19153 | This is equivalent to req.hdr() when used on requests, and to res.hdr() when |
| 19154 | used on responses. Please refer to these respective fetches for more details. |
| 19155 | In case of doubt about the fetch direction, please use the explicit ones. |
| 19156 | 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] | 19157 | unambiguously apply to the request headers. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19158 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19159 | req.fhdr(<name>[,<occ>]) : string |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19160 | This returns the full value of the last occurrence of header <name> in an |
| 19161 | HTTP request. It differs from req.hdr() in that any commas present in the |
| 19162 | value are returned and are not used as delimiters. This is sometimes useful |
| 19163 | with headers such as User-Agent. |
| 19164 | |
| 19165 | When used from an ACL, all occurrences are iterated over until a match is |
| 19166 | found. |
| 19167 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19168 | Optionally, a specific occurrence might be specified as a position number. |
| 19169 | Positive values indicate a position from the first occurrence, with 1 being |
| 19170 | the first one. Negative values indicate positions relative to the last one, |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19171 | with -1 being the last one. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19172 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19173 | req.fhdr_cnt([<name>]) : integer |
| 19174 | Returns an integer value representing the number of occurrences of request |
| 19175 | header field name <name>, or the total number of header fields if <name> is |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19176 | not specified. Like req.fhdr() it differs from res.hdr_cnt() by not splitting |
| 19177 | headers at commas. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19178 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19179 | req.hdr([<name>[,<occ>]]) : string |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19180 | This returns the last comma-separated value of the header <name> in an HTTP |
| 19181 | request. The fetch considers any comma as a delimiter for distinct values. |
| 19182 | This is useful if you need to process headers that are defined to be a list |
| 19183 | of values, such as Accept, or X-Forwarded-For. If full-line headers are |
| 19184 | desired instead, use req.fhdr(). Please carefully check RFC 7231 to know how |
| 19185 | certain headers are supposed to be parsed. Also, some of them are case |
| 19186 | insensitive (e.g. Connection). |
| 19187 | |
| 19188 | When used from an ACL, all occurrences are iterated over until a match is |
| 19189 | found. |
| 19190 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19191 | Optionally, a specific occurrence might be specified as a position number. |
| 19192 | Positive values indicate a position from the first occurrence, with 1 being |
| 19193 | the first one. Negative values indicate positions relative to the last one, |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19194 | with -1 being the last one. |
| 19195 | |
| 19196 | A typical use is with the X-Forwarded-For header once converted to IP, |
| 19197 | associated with an IP stick-table. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19198 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19199 | ACL derivatives : |
| 19200 | hdr([<name>[,<occ>]]) : exact string match |
| 19201 | hdr_beg([<name>[,<occ>]]) : prefix match |
| 19202 | hdr_dir([<name>[,<occ>]]) : subdir match |
| 19203 | hdr_dom([<name>[,<occ>]]) : domain match |
| 19204 | hdr_end([<name>[,<occ>]]) : suffix match |
| 19205 | hdr_len([<name>[,<occ>]]) : length match |
| 19206 | hdr_reg([<name>[,<occ>]]) : regex match |
| 19207 | hdr_sub([<name>[,<occ>]]) : substring match |
| 19208 | |
| 19209 | req.hdr_cnt([<name>]) : integer |
| 19210 | hdr_cnt([<header>]) : integer (deprecated) |
| 19211 | Returns an integer value representing the number of occurrences of request |
| 19212 | header field name <name>, or the total number of header field values if |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19213 | <name> is not specified. Like req.hdr() it counts each comma separated |
| 19214 | part of the header's value. If counting of full-line headers is desired, |
| 19215 | then req.fhdr_cnt() should be used instead. |
| 19216 | |
| 19217 | With ACLs, it can be used to detect presence, absence or abuse of a specific |
| 19218 | header, as well as to block request smuggling attacks by rejecting requests |
| 19219 | which contain more than one of certain headers. |
| 19220 | |
| 19221 | Refer to req.hdr() for more information on header matching. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19222 | |
| 19223 | req.hdr_ip([<name>[,<occ>]]) : ip |
| 19224 | hdr_ip([<name>[,<occ>]]) : ip (deprecated) |
| 19225 | This extracts the last occurrence of header <name> in an HTTP request, |
| 19226 | converts it to an IPv4 or IPv6 address and returns this address. When used |
| 19227 | with ACLs, all occurrences are checked, and if <name> is omitted, every value |
Willy Tarreau | 7b0e00d | 2021-03-25 14:12:29 +0100 | [diff] [blame] | 19228 | of every header is checked. The parser strictly adheres to the format |
| 19229 | described in RFC7239, with the extension that IPv4 addresses may optionally |
| 19230 | be followed by a colon (':') and a valid decimal port number (0 to 65535), |
| 19231 | which will be silently dropped. All other forms will not match and will |
| 19232 | cause the address to be ignored. |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19233 | |
| 19234 | The <occ> parameter is processed as with req.hdr(). |
| 19235 | |
| 19236 | A typical use is with the X-Forwarded-For and X-Client-IP headers. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19237 | |
| 19238 | req.hdr_val([<name>[,<occ>]]) : integer |
| 19239 | hdr_val([<name>[,<occ>]]) : integer (deprecated) |
| 19240 | This extracts the last occurrence of header <name> in an HTTP request, and |
| 19241 | converts it to an integer value. When used with ACLs, all occurrences are |
| 19242 | checked, and if <name> is omitted, every value of every header is checked. |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19243 | |
| 19244 | The <occ> parameter is processed as with req.hdr(). |
| 19245 | |
| 19246 | A typical use is with the X-Forwarded-For header. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19247 | |
Christopher Faulet | 687a68e | 2020-11-24 17:13:24 +0100 | [diff] [blame] | 19248 | req.hdrs : string |
| 19249 | Returns the current request headers as string including the last empty line |
| 19250 | separating headers from the request body. The last empty line can be used to |
| 19251 | detect a truncated header block. This sample fetch is useful for some SPOE |
| 19252 | headers analyzers and for advanced logging. |
| 19253 | |
| 19254 | req.hdrs_bin : binary |
| 19255 | Returns the current request headers contained in preparsed binary form. This |
| 19256 | is useful for offloading some processing with SPOE. Each string is described |
| 19257 | by a length followed by the number of bytes indicated in the length. The |
| 19258 | length is represented using the variable integer encoding detailed in the |
| 19259 | SPOE documentation. The end of the list is marked by a couple of empty header |
| 19260 | names and values (length of 0 for both). |
| 19261 | |
| 19262 | *(<str:header-name><str:header-value>)<empty string><empty string> |
Frédéric Lécaille | ec89119 | 2019-02-26 15:02:35 +0100 | [diff] [blame] | 19263 | |
Christopher Faulet | 687a68e | 2020-11-24 17:13:24 +0100 | [diff] [blame] | 19264 | int: refer to the SPOE documentation for the encoding |
| 19265 | str: <int:length><bytes> |
Frédéric Lécaille | ec89119 | 2019-02-26 15:02:35 +0100 | [diff] [blame] | 19266 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19267 | http_auth(<userlist>) : boolean |
| 19268 | Returns a boolean indicating whether the authentication data received from |
| 19269 | the client match a username & password stored in the specified userlist. This |
| 19270 | fetch function is not really useful outside of ACLs. Currently only http |
| 19271 | basic auth is supported. |
| 19272 | |
Thierry FOURNIER | 9eec0a6 | 2014-01-22 18:38:02 +0100 | [diff] [blame] | 19273 | http_auth_group(<userlist>) : string |
| 19274 | Returns a string corresponding to the user name found in the authentication |
| 19275 | data received from the client if both the user name and password are valid |
| 19276 | according to the specified userlist. The main purpose is to use it in ACLs |
| 19277 | 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] | 19278 | This fetch function is not really useful outside of ACLs. Currently only http |
| 19279 | basic auth is supported. |
| 19280 | |
| 19281 | ACL derivatives : |
Thierry FOURNIER | 9eec0a6 | 2014-01-22 18:38:02 +0100 | [diff] [blame] | 19282 | http_auth_group(<userlist>) : group ... |
| 19283 | Returns true when the user extracted from the request and whose password is |
| 19284 | valid according to the specified userlist belongs to at least one of the |
| 19285 | groups. |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19286 | |
Christopher Faulet | a406356 | 2019-08-02 11:51:37 +0200 | [diff] [blame] | 19287 | http_auth_pass : string |
Willy Tarreau | c9c6cdb | 2020-03-05 16:03:58 +0100 | [diff] [blame] | 19288 | Returns the user's password found in the authentication data received from |
| 19289 | the client, as supplied in the Authorization header. Not checks are |
| 19290 | performed by this sample fetch. Only Basic authentication is supported. |
Christopher Faulet | a406356 | 2019-08-02 11:51:37 +0200 | [diff] [blame] | 19291 | |
| 19292 | http_auth_type : string |
Willy Tarreau | c9c6cdb | 2020-03-05 16:03:58 +0100 | [diff] [blame] | 19293 | Returns the authentication method found in the authentication data received from |
| 19294 | the client, as supplied in the Authorization header. Not checks are |
| 19295 | performed by this sample fetch. Only Basic authentication is supported. |
Christopher Faulet | a406356 | 2019-08-02 11:51:37 +0200 | [diff] [blame] | 19296 | |
| 19297 | http_auth_user : string |
Willy Tarreau | c9c6cdb | 2020-03-05 16:03:58 +0100 | [diff] [blame] | 19298 | Returns the user name found in the authentication data received from the |
| 19299 | client, as supplied in the Authorization header. Not checks are performed by |
| 19300 | this sample fetch. Only Basic authentication is supported. |
Christopher Faulet | a406356 | 2019-08-02 11:51:37 +0200 | [diff] [blame] | 19301 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19302 | http_first_req : boolean |
Willy Tarreau | 7f18e52 | 2010-10-22 20:04:13 +0200 | [diff] [blame] | 19303 | Returns true when the request being processed is the first one of the |
| 19304 | 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] | 19305 | from some requests when a request is not the first one, or to help grouping |
| 19306 | requests in the logs. |
Willy Tarreau | 7f18e52 | 2010-10-22 20:04:13 +0200 | [diff] [blame] | 19307 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19308 | method : integer + string |
| 19309 | Returns an integer value corresponding to the method in the HTTP request. For |
| 19310 | example, "GET" equals 1 (check sources to establish the matching). Value 9 |
| 19311 | means "other method" and may be converted to a string extracted from the |
| 19312 | stream. This should not be used directly as a sample, this is only meant to |
| 19313 | be used from ACLs, which transparently convert methods from patterns to these |
| 19314 | integer + string values. Some predefined ACL already check for most common |
| 19315 | methods. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19316 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19317 | ACL derivatives : |
| 19318 | method : case insensitive method match |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19319 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19320 | Example : |
| 19321 | # only accept GET and HEAD requests |
| 19322 | acl valid_method method GET HEAD |
| 19323 | http-request deny if ! valid_method |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19324 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19325 | path : string |
| 19326 | This extracts the request's URL path, which starts at the first slash and |
| 19327 | ends before the question mark (without the host part). A typical use is with |
| 19328 | prefetch-capable caches, and with portals which need to aggregate multiple |
| 19329 | information from databases and keep them in caches. Note that with outgoing |
| 19330 | caches, it would be wiser to use "url" instead. With ACLs, it's typically |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 19331 | used to match exact file names (e.g. "/login.php"), or directory parts using |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19332 | the derivative forms. See also the "url" and "base" fetch methods. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19333 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19334 | ACL derivatives : |
| 19335 | path : exact string match |
| 19336 | path_beg : prefix match |
| 19337 | path_dir : subdir match |
| 19338 | path_dom : domain match |
| 19339 | path_end : suffix match |
| 19340 | path_len : length match |
| 19341 | path_reg : regex match |
| 19342 | path_sub : substring match |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19343 | |
Christopher Faulet | e720c32 | 2020-09-02 17:25:18 +0200 | [diff] [blame] | 19344 | pathq : string |
| 19345 | This extracts the request's URL path with the query-string, which starts at |
| 19346 | the first slash. This sample fetch is pretty handy to always retrieve a |
| 19347 | relative URI, excluding the scheme and the authority part, if any. Indeed, |
| 19348 | while it is the common representation for an HTTP/1.1 request target, in |
| 19349 | HTTP/2, an absolute URI is often used. This sample fetch will return the same |
| 19350 | result in both cases. |
| 19351 | |
Willy Tarreau | 49ad95c | 2015-01-19 15:06:26 +0100 | [diff] [blame] | 19352 | query : string |
| 19353 | This extracts the request's query string, which starts after the first |
| 19354 | question mark. If no question mark is present, this fetch returns nothing. If |
| 19355 | a question mark is present but nothing follows, it returns an empty string. |
| 19356 | This means it's possible to easily know whether a query string is present |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 19357 | using the "found" matching method. This fetch is the complement of "path" |
Willy Tarreau | 49ad95c | 2015-01-19 15:06:26 +0100 | [diff] [blame] | 19358 | which stops before the question mark. |
| 19359 | |
Willy Tarreau | eb27ec7 | 2015-02-20 13:55:29 +0100 | [diff] [blame] | 19360 | req.hdr_names([<delim>]) : string |
| 19361 | This builds a string made from the concatenation of all header names as they |
| 19362 | appear in the request when the rule is evaluated. The default delimiter is |
| 19363 | the comma (',') but it may be overridden as an optional argument <delim>. In |
| 19364 | this case, only the first character of <delim> is considered. |
| 19365 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19366 | req.ver : string |
| 19367 | req_ver : string (deprecated) |
| 19368 | Returns the version string from the HTTP request, for example "1.1". This can |
| 19369 | be useful for logs, but is mostly there for ACL. Some predefined ACL already |
| 19370 | check for versions 1.0 and 1.1. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19371 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19372 | ACL derivatives : |
| 19373 | req_ver : exact string match |
Willy Tarreau | 0e69854 | 2011-09-16 08:32:32 +0200 | [diff] [blame] | 19374 | |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19375 | res.body : binary |
| 19376 | This returns the HTTP response's available body as a block of data. Unlike |
| 19377 | the request side, there is no directive to wait for the response's body. This |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19378 | sample fetch is really useful (and usable) in the health-check context. |
| 19379 | |
| 19380 | It may be used in tcp-check based expect rules. |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19381 | |
| 19382 | res.body_len : integer |
| 19383 | This returns the length of the HTTP response available body in bytes. Unlike |
| 19384 | the request side, there is no directive to wait for the response's body. This |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19385 | sample fetch is really useful (and usable) in the health-check context. |
| 19386 | |
| 19387 | It may be used in tcp-check based expect rules. |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19388 | |
| 19389 | res.body_size : integer |
| 19390 | This returns the advertised length of the HTTP response body in bytes. It |
| 19391 | will represent the advertised Content-Length header, or the size of the |
| 19392 | available data in case of chunked encoding. Unlike the request side, there is |
| 19393 | no directive to wait for the response body. This sample fetch is really |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19394 | useful (and usable) in the health-check context. |
| 19395 | |
| 19396 | It may be used in tcp-check based expect rules. |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19397 | |
Remi Tricot-Le Breton | bf97121 | 2020-10-27 11:55:57 +0100 | [diff] [blame] | 19398 | res.cache_hit : boolean |
| 19399 | Returns the boolean "true" value if the response has been built out of an |
| 19400 | HTTP cache entry, otherwise returns boolean "false". |
| 19401 | |
| 19402 | res.cache_name : string |
| 19403 | Returns a string containing the name of the HTTP cache that was used to |
| 19404 | build the HTTP response if res.cache_hit is true, otherwise returns an |
| 19405 | empty string. |
| 19406 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19407 | res.comp : boolean |
| 19408 | Returns the boolean "true" value if the response has been compressed by |
| 19409 | HAProxy, otherwise returns boolean "false". This may be used to add |
| 19410 | information in the logs. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19411 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19412 | res.comp_algo : string |
| 19413 | Returns a string containing the name of the algorithm used if the response |
| 19414 | was compressed by HAProxy, for example : "deflate". This may be used to add |
| 19415 | some information in the logs. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19416 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19417 | res.cook([<name>]) : string |
| 19418 | scook([<name>]) : string (deprecated) |
| 19419 | This extracts the last occurrence of the cookie name <name> on a "Set-Cookie" |
| 19420 | header line from the response, and returns its value as string. If no name is |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19421 | specified, the first cookie value is returned. |
| 19422 | |
| 19423 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 0ce3aa0 | 2012-04-25 18:46:33 +0200 | [diff] [blame] | 19424 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19425 | ACL derivatives : |
| 19426 | scook([<name>] : exact string match |
Willy Tarreau | 0ce3aa0 | 2012-04-25 18:46:33 +0200 | [diff] [blame] | 19427 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19428 | res.cook_cnt([<name>]) : integer |
| 19429 | scook_cnt([<name>]) : integer (deprecated) |
| 19430 | Returns an integer value representing the number of occurrences of the cookie |
| 19431 | <name> in the response, or all cookies if <name> is not specified. This is |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19432 | mostly useful when combined with ACLs to detect suspicious responses. |
| 19433 | |
| 19434 | It may be used in tcp-check based expect rules. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19435 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19436 | res.cook_val([<name>]) : integer |
| 19437 | scook_val([<name>]) : integer (deprecated) |
| 19438 | This extracts the last occurrence of the cookie name <name> on a "Set-Cookie" |
| 19439 | header line from the response, and converts its value to an integer which is |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19440 | returned. If no name is specified, the first cookie value is returned. |
| 19441 | |
| 19442 | It may be used in tcp-check based expect rules. |
Willy Tarreau | d63335a | 2010-02-26 12:56:52 +0100 | [diff] [blame] | 19443 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19444 | res.fhdr([<name>[,<occ>]]) : string |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19445 | This fetch works like the req.fhdr() fetch with the difference that it acts |
| 19446 | on the headers within an HTTP response. |
| 19447 | |
| 19448 | Like req.fhdr() the res.fhdr() fetch returns full values. If the header is |
| 19449 | defined to be a list you should use res.hdr(). |
| 19450 | |
| 19451 | This fetch is sometimes useful with headers such as Date or Expires. |
| 19452 | |
| 19453 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19454 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19455 | res.fhdr_cnt([<name>]) : integer |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19456 | This fetch works like the req.fhdr_cnt() fetch with the difference that it |
| 19457 | acts on the headers within an HTTP response. |
| 19458 | |
| 19459 | Like req.fhdr_cnt() the res.fhdr_cnt() fetch acts on full values. If the |
| 19460 | header is defined to be a list you should use res.hdr_cnt(). |
| 19461 | |
| 19462 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19463 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19464 | res.hdr([<name>[,<occ>]]) : string |
| 19465 | shdr([<name>[,<occ>]]) : string (deprecated) |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19466 | This fetch works like the req.hdr() fetch with the difference that it acts |
| 19467 | on the headers within an HTTP response. |
| 19468 | |
Ilya Shipitsin | acf8459 | 2021-02-06 22:29:08 +0500 | [diff] [blame] | 19469 | Like req.hdr() the res.hdr() fetch considers the comma to be a delimiter. If |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19470 | this is not desired res.fhdr() should be used. |
| 19471 | |
| 19472 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19473 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19474 | ACL derivatives : |
| 19475 | shdr([<name>[,<occ>]]) : exact string match |
| 19476 | shdr_beg([<name>[,<occ>]]) : prefix match |
| 19477 | shdr_dir([<name>[,<occ>]]) : subdir match |
| 19478 | shdr_dom([<name>[,<occ>]]) : domain match |
| 19479 | shdr_end([<name>[,<occ>]]) : suffix match |
| 19480 | shdr_len([<name>[,<occ>]]) : length match |
| 19481 | shdr_reg([<name>[,<occ>]]) : regex match |
| 19482 | shdr_sub([<name>[,<occ>]]) : substring match |
| 19483 | |
| 19484 | res.hdr_cnt([<name>]) : integer |
| 19485 | shdr_cnt([<name>]) : integer (deprecated) |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19486 | This fetch works like the req.hdr_cnt() fetch with the difference that it |
| 19487 | acts on the headers within an HTTP response. |
| 19488 | |
| 19489 | Like req.hdr_cnt() the res.hdr_cnt() fetch considers the comma to be a |
Ilya Shipitsin | acf8459 | 2021-02-06 22:29:08 +0500 | [diff] [blame] | 19490 | delimiter. If this is not desired res.fhdr_cnt() should be used. |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19491 | |
| 19492 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19493 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19494 | res.hdr_ip([<name>[,<occ>]]) : ip |
| 19495 | shdr_ip([<name>[,<occ>]]) : ip (deprecated) |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19496 | This fetch works like the req.hdr_ip() fetch with the difference that it |
| 19497 | acts on the headers within an HTTP response. |
| 19498 | |
| 19499 | This can be useful to learn some data into a stick table. |
| 19500 | |
| 19501 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19502 | |
Willy Tarreau | eb27ec7 | 2015-02-20 13:55:29 +0100 | [diff] [blame] | 19503 | res.hdr_names([<delim>]) : string |
| 19504 | This builds a string made from the concatenation of all header names as they |
| 19505 | appear in the response when the rule is evaluated. The default delimiter is |
| 19506 | the comma (',') but it may be overridden as an optional argument <delim>. In |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19507 | this case, only the first character of <delim> is considered. |
| 19508 | |
| 19509 | It may be used in tcp-check based expect rules. |
Willy Tarreau | eb27ec7 | 2015-02-20 13:55:29 +0100 | [diff] [blame] | 19510 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19511 | res.hdr_val([<name>[,<occ>]]) : integer |
| 19512 | shdr_val([<name>[,<occ>]]) : integer (deprecated) |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19513 | This fetch works like the req.hdr_val() fetch with the difference that it |
| 19514 | acts on the headers within an HTTP response. |
| 19515 | |
| 19516 | This can be useful to learn some data into a stick table. |
| 19517 | |
| 19518 | It may be used in tcp-check based expect rules. |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19519 | |
| 19520 | res.hdrs : string |
| 19521 | Returns the current response headers as string including the last empty line |
| 19522 | separating headers from the request body. The last empty line can be used to |
| 19523 | detect a truncated header block. This sample fetch is useful for some SPOE |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19524 | headers analyzers and for advanced logging. |
| 19525 | |
| 19526 | It may also be used in tcp-check based expect rules. |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19527 | |
| 19528 | res.hdrs_bin : binary |
| 19529 | Returns the current response headers contained in preparsed binary form. This |
| 19530 | is useful for offloading some processing with SPOE. It may be used in |
| 19531 | tcp-check based expect rules. Each string is described by a length followed |
| 19532 | by the number of bytes indicated in the length. The length is represented |
| 19533 | using the variable integer encoding detailed in the SPOE documentation. The |
| 19534 | end of the list is marked by a couple of empty header names and values |
| 19535 | (length of 0 for both). |
| 19536 | |
| 19537 | *(<str:header-name><str:header-value>)<empty string><empty string> |
| 19538 | |
| 19539 | int: refer to the SPOE documentation for the encoding |
| 19540 | str: <int:length><bytes> |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 19541 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19542 | res.ver : string |
| 19543 | resp_ver : string (deprecated) |
| 19544 | Returns the version string from the HTTP response, for example "1.1". This |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19545 | can be useful for logs, but is mostly there for ACL. |
| 19546 | |
| 19547 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 0e69854 | 2011-09-16 08:32:32 +0200 | [diff] [blame] | 19548 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19549 | ACL derivatives : |
| 19550 | resp_ver : exact string match |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 19551 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19552 | set-cookie([<name>]) : string (deprecated) |
| 19553 | This extracts the last occurrence of the cookie name <name> on a "Set-Cookie" |
| 19554 | header line from the response and uses the corresponding value to match. This |
Willy Tarreau | 294d0f0 | 2015-08-10 19:40:12 +0200 | [diff] [blame] | 19555 | can be comparable to what "appsession" did with default options, but with |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19556 | support for multi-peer synchronization and state keeping across restarts. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 19557 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19558 | This fetch function is deprecated and has been superseded by the "res.cook" |
| 19559 | fetch. This keyword will disappear soon. |
Krzysztof Piotr Oledzki | 6b35ce1 | 2010-02-01 23:35:44 +0100 | [diff] [blame] | 19560 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19561 | status : integer |
| 19562 | Returns an integer containing the HTTP status code in the HTTP response, for |
| 19563 | example, 302. It is mostly used within ACLs and integer ranges, for example, |
Tim Duesterhus | 27c70ae | 2021-01-23 17:50:21 +0100 | [diff] [blame] | 19564 | to remove any Location header if the response is not a 3xx. |
| 19565 | |
| 19566 | It may be used in tcp-check based expect rules. |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19567 | |
Thierry Fournier | 0e00dca | 2016-04-07 15:47:40 +0200 | [diff] [blame] | 19568 | unique-id : string |
| 19569 | Returns the unique-id attached to the request. The directive |
| 19570 | "unique-id-format" must be set. If it is not set, the unique-id sample fetch |
| 19571 | fails. Note that the unique-id is usually used with HTTP requests, however this |
| 19572 | sample fetch can be used with other protocols. Obviously, if it is used with |
| 19573 | other protocols than HTTP, the unique-id-format directive must not contain |
| 19574 | HTTP parts. See: unique-id-format and unique-id-header |
| 19575 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19576 | url : string |
| 19577 | This extracts the request's URL as presented in the request. A typical use is |
| 19578 | with prefetch-capable caches, and with portals which need to aggregate |
| 19579 | multiple information from databases and keep them in caches. With ACLs, using |
| 19580 | "path" is preferred over using "url", because clients may send a full URL as |
| 19581 | is normally done with proxies. The only real use is to match "*" which does |
| 19582 | not match in "path", and for which there is already a predefined ACL. See |
| 19583 | also "path" and "base". |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19584 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19585 | ACL derivatives : |
| 19586 | url : exact string match |
| 19587 | url_beg : prefix match |
| 19588 | url_dir : subdir match |
| 19589 | url_dom : domain match |
| 19590 | url_end : suffix match |
| 19591 | url_len : length match |
| 19592 | url_reg : regex match |
| 19593 | url_sub : substring match |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19594 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19595 | url_ip : ip |
| 19596 | This extracts the IP address from the request's URL when the host part is |
| 19597 | presented as an IP address. Its use is very limited. For instance, a |
| 19598 | monitoring system might use this field as an alternative for the source IP in |
| 19599 | order to test what path a given source address would follow, or to force an |
| 19600 | entry in a table for a given source address. With ACLs it can be used to |
| 19601 | restrict access to certain systems through a proxy, for example when combined |
| 19602 | with option "http_proxy". |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19603 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19604 | url_port : integer |
| 19605 | This extracts the port part from the request's URL. Note that if the port is |
| 19606 | not specified in the request, port 80 is assumed. With ACLs it can be used to |
| 19607 | restrict access to certain systems through a proxy, for example when combined |
| 19608 | with option "http_proxy". |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19609 | |
Willy Tarreau | 1ede1da | 2015-05-07 16:06:18 +0200 | [diff] [blame] | 19610 | urlp([<name>[,<delim>]]) : string |
| 19611 | url_param([<name>[,<delim>]]) : string |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19612 | This extracts the first occurrence of the parameter <name> in the query |
| 19613 | string, which begins after either '?' or <delim>, and which ends before '&', |
Willy Tarreau | 1ede1da | 2015-05-07 16:06:18 +0200 | [diff] [blame] | 19614 | ';' or <delim>. The parameter name is case-sensitive. If no name is given, |
| 19615 | any parameter will match, and the first one will be returned. The result is |
| 19616 | a string corresponding to the value of the parameter <name> as presented in |
| 19617 | the request (no URL decoding is performed). This can be used for session |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19618 | stickiness based on a client ID, to extract an application cookie passed as a |
| 19619 | URL parameter, or in ACLs to apply some checks. Note that the ACL version of |
Willy Tarreau | 1ede1da | 2015-05-07 16:06:18 +0200 | [diff] [blame] | 19620 | this fetch iterates over multiple parameters and will iteratively report all |
| 19621 | parameters values if no name is given |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19622 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19623 | ACL derivatives : |
| 19624 | urlp(<name>[,<delim>]) : exact string match |
| 19625 | urlp_beg(<name>[,<delim>]) : prefix match |
| 19626 | urlp_dir(<name>[,<delim>]) : subdir match |
| 19627 | urlp_dom(<name>[,<delim>]) : domain match |
| 19628 | urlp_end(<name>[,<delim>]) : suffix match |
| 19629 | urlp_len(<name>[,<delim>]) : length match |
| 19630 | urlp_reg(<name>[,<delim>]) : regex match |
| 19631 | urlp_sub(<name>[,<delim>]) : substring match |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19632 | |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19633 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19634 | Example : |
| 19635 | # match http://example.com/foo?PHPSESSIONID=some_id |
| 19636 | stick on urlp(PHPSESSIONID) |
| 19637 | # match http://example.com/foo;JSESSIONID=some_id |
| 19638 | stick on urlp(JSESSIONID,;) |
Willy Tarreau | 25c1ebc | 2012-04-25 16:21:44 +0200 | [diff] [blame] | 19639 | |
Jarno Huuskonen | 676f622 | 2017-03-30 09:19:45 +0300 | [diff] [blame] | 19640 | urlp_val([<name>[,<delim>]]) : integer |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19641 | See "urlp" above. This one extracts the URL parameter <name> in the request |
| 19642 | and converts it to an integer value. This can be used for session stickiness |
| 19643 | 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] | 19644 | |
Dragan Dosen | 0070cd5 | 2016-06-16 12:19:49 +0200 | [diff] [blame] | 19645 | url32 : integer |
| 19646 | This returns a 32-bit hash of the value obtained by concatenating the first |
| 19647 | Host header and the whole URL including parameters (not only the path part of |
| 19648 | the request, as in the "base32" fetch above). This is useful to track per-URL |
| 19649 | activity. A shorter hash is stored, saving a lot of memory. The output type |
| 19650 | is an unsigned integer. |
| 19651 | |
| 19652 | url32+src : binary |
| 19653 | This returns the concatenation of the "url32" fetch and the "src" fetch. The |
| 19654 | resulting type is of type binary, with a size of 8 or 20 bytes depending on |
| 19655 | the source address family. This can be used to track per-IP, per-URL counters. |
| 19656 | |
Christopher Faulet | 16032ab | 2020-04-30 11:30:00 +0200 | [diff] [blame] | 19657 | |
Christopher Faulet | e596d18 | 2020-05-05 17:46:34 +0200 | [diff] [blame] | 19658 | 7.3.7. Fetching samples for developers |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19659 | --------------------------------------- |
| 19660 | |
| 19661 | This set of sample fetch methods is reserved to developers and must never be |
| 19662 | used on a production environment, except on developer demand, for debugging |
| 19663 | purposes. Moreover, no special care will be taken on backwards compatibility. |
| 19664 | There is no warranty the following sample fetches will never change, be renamed |
| 19665 | or simply removed. So be really careful if you should use one of them. To avoid |
| 19666 | any ambiguity, these sample fetches are placed in the dedicated scope "internal", |
| 19667 | for instance "internal.strm.is_htx". |
| 19668 | |
| 19669 | internal.htx.data : integer |
| 19670 | Returns the size in bytes used by data in the HTX message associated to a |
| 19671 | channel. The channel is chosen depending on the sample direction. |
| 19672 | |
| 19673 | internal.htx.free : integer |
| 19674 | Returns the free space (size - used) in bytes in the HTX message associated |
| 19675 | to a channel. The channel is chosen depending on the sample direction. |
| 19676 | |
| 19677 | internal.htx.free_data : integer |
| 19678 | Returns the free space for the data in bytes in the HTX message associated to |
| 19679 | a channel. The channel is chosen depending on the sample direction. |
| 19680 | |
| 19681 | internal.htx.has_eom : boolean |
Christopher Faulet | d1ac2b9 | 2020-12-02 19:12:22 +0100 | [diff] [blame] | 19682 | Returns true if the HTX message associated to a channel contains the |
| 19683 | end-of-message flag (EOM). Otherwise, it returns false. The channel is chosen |
| 19684 | depending on the sample direction. |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19685 | |
| 19686 | internal.htx.nbblks : integer |
| 19687 | Returns the number of blocks present in the HTX message associated to a |
| 19688 | channel. The channel is chosen depending on the sample direction. |
| 19689 | |
| 19690 | internal.htx.size : integer |
| 19691 | Returns the total size in bytes of the HTX message associated to a |
| 19692 | channel. The channel is chosen depending on the sample direction. |
| 19693 | |
| 19694 | internal.htx.used : integer |
| 19695 | Returns the total size used in bytes (data + metadata) in the HTX message |
| 19696 | associated to a channel. The channel is chosen depending on the sample |
| 19697 | direction. |
| 19698 | |
| 19699 | internal.htx_blk.size(<idx>) : integer |
| 19700 | Returns the size of the block at the position <idx> in the HTX message |
| 19701 | associated to a channel or 0 if it does not exist. The channel is chosen |
| 19702 | depending on the sample direction. <idx> may be any positive integer or one |
| 19703 | of the special value : |
| 19704 | * head : The oldest inserted block |
| 19705 | * tail : The newest inserted block |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 19706 | * first : The first block where to (re)start the analysis |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19707 | |
| 19708 | internal.htx_blk.type(<idx>) : string |
| 19709 | Returns the type of the block at the position <idx> in the HTX message |
| 19710 | associated to a channel or "HTX_BLK_UNUSED" if it does not exist. The channel |
| 19711 | is chosen depending on the sample direction. <idx> may be any positive |
| 19712 | integer or one of the special value : |
| 19713 | * head : The oldest inserted block |
| 19714 | * tail : The newest inserted block |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 19715 | * first : The first block where to (re)start the analysis |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19716 | |
| 19717 | internal.htx_blk.data(<idx>) : binary |
| 19718 | Returns the value of the DATA block at the position <idx> in the HTX message |
| 19719 | associated to a channel or an empty string if it does not exist or if it is |
| 19720 | not a DATA block. The channel is chosen depending on the sample direction. |
| 19721 | <idx> may be any positive integer or one of the special value : |
| 19722 | |
| 19723 | * head : The oldest inserted block |
| 19724 | * tail : The newest inserted block |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 19725 | * first : The first block where to (re)start the analysis |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19726 | |
| 19727 | internal.htx_blk.hdrname(<idx>) : string |
| 19728 | Returns the header name of the HEADER block at the position <idx> in the HTX |
| 19729 | message associated to a channel or an empty string if it does not exist or if |
| 19730 | it is not an HEADER block. The channel is chosen depending on the sample |
| 19731 | direction. <idx> may be any positive integer or one of the special value : |
| 19732 | |
| 19733 | * head : The oldest inserted block |
| 19734 | * tail : The newest inserted block |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 19735 | * first : The first block where to (re)start the analysis |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19736 | |
| 19737 | internal.htx_blk.hdrval(<idx>) : string |
| 19738 | Returns the header value of the HEADER block at the position <idx> in the HTX |
| 19739 | message associated to a channel or an empty string if it does not exist or if |
| 19740 | it is not an HEADER block. The channel is chosen depending on the sample |
| 19741 | direction. <idx> may be any positive integer or one of the special value : |
| 19742 | |
| 19743 | * head : The oldest inserted block |
| 19744 | * tail : The newest inserted block |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 19745 | * first : The first block where to (re)start the analysis |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19746 | |
| 19747 | internal.htx_blk.start_line(<idx>) : string |
| 19748 | Returns the value of the REQ_SL or RES_SL block at the position <idx> in the |
| 19749 | HTX message associated to a channel or an empty string if it does not exist |
| 19750 | or if it is not a SL block. The channel is chosen depending on the sample |
| 19751 | direction. <idx> may be any positive integer or one of the special value : |
| 19752 | |
| 19753 | * head : The oldest inserted block |
| 19754 | * tail : The newest inserted block |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 19755 | * first : The first block where to (re)start the analysis |
Christopher Faulet | d47941d | 2020-01-08 14:40:19 +0100 | [diff] [blame] | 19756 | |
| 19757 | internal.strm.is_htx : boolean |
| 19758 | Returns true if the current stream is an HTX stream. It means the data in the |
| 19759 | channels buffers are stored using the internal HTX representation. Otherwise, |
| 19760 | it returns false. |
| 19761 | |
| 19762 | |
Willy Tarreau | 74ca504 | 2013-06-11 23:12:07 +0200 | [diff] [blame] | 19763 | 7.4. Pre-defined ACLs |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19764 | --------------------- |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 19765 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19766 | Some predefined ACLs are hard-coded so that they do not have to be declared in |
| 19767 | 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] | 19768 | order to avoid confusion. Their equivalence is provided below. |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 19769 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19770 | ACL name Equivalent to Usage |
Christopher Faulet | 779184e | 2021-04-01 17:24:04 +0200 | [diff] [blame] | 19771 | ---------------+----------------------------------+------------------------------------------------------ |
| 19772 | FALSE always_false never match |
| 19773 | HTTP req.proto_http match if request protocol is valid HTTP |
| 19774 | HTTP_1.0 req.ver 1.0 match if HTTP request version is 1.0 |
| 19775 | HTTP_1.1 req.ver 1.1 match if HTTP request version is 1.1 |
Christopher Faulet | 8043e83 | 2021-03-26 16:00:54 +0100 | [diff] [blame] | 19776 | HTTP_2.0 req.ver 2.0 match if HTTP request version is 2.0 |
Christopher Faulet | 779184e | 2021-04-01 17:24:04 +0200 | [diff] [blame] | 19777 | HTTP_CONTENT req.hdr_val(content-length) gt 0 match an existing content-length in the HTTP request |
| 19778 | HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme |
| 19779 | HTTP_URL_SLASH url_beg / match URL beginning with "/" |
| 19780 | HTTP_URL_STAR url * match URL equal to "*" |
| 19781 | LOCALHOST src 127.0.0.1/8 match connection from local host |
| 19782 | METH_CONNECT method CONNECT match HTTP CONNECT method |
| 19783 | METH_DELETE method DELETE match HTTP DELETE method |
| 19784 | METH_GET method GET HEAD match HTTP GET or HEAD method |
| 19785 | METH_HEAD method HEAD match HTTP HEAD method |
| 19786 | METH_OPTIONS method OPTIONS match HTTP OPTIONS method |
| 19787 | METH_POST method POST match HTTP POST method |
| 19788 | METH_PUT method PUT match HTTP PUT method |
| 19789 | METH_TRACE method TRACE match HTTP TRACE method |
| 19790 | RDP_COOKIE req.rdp_cookie_cnt gt 0 match presence of an RDP cookie in the request buffer |
| 19791 | REQ_CONTENT req.len gt 0 match data in the request buffer |
| 19792 | TRUE always_true always match |
| 19793 | WAIT_END wait_end wait for end of content analysis |
| 19794 | ---------------+----------------------------------+------------------------------------------------------ |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 19795 | |
Willy Tarreau | b937b7e | 2010-01-12 15:27:54 +0100 | [diff] [blame] | 19796 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19797 | 8. Logging |
| 19798 | ---------- |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 19799 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19800 | One of HAProxy's strong points certainly lies is its precise logs. It probably |
| 19801 | provides the finest level of information available for such a product, which is |
| 19802 | very important for troubleshooting complex environments. Standard information |
| 19803 | provided in logs include client ports, TCP/HTTP state timers, precise session |
| 19804 | state at termination and precise termination cause, information about decisions |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 19805 | 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] | 19806 | headers. |
| 19807 | |
| 19808 | In order to improve administrators reactivity, it offers a great transparency |
| 19809 | about encountered problems, both internal and external, and it is possible to |
| 19810 | send logs to different sources at the same time with different level filters : |
| 19811 | |
| 19812 | - global process-level logs (system errors, start/stop, etc..) |
| 19813 | - per-instance system and internal errors (lack of resource, bugs, ...) |
| 19814 | - per-instance external troubles (servers up/down, max connections) |
| 19815 | - per-instance activity (client connections), either at the establishment or |
| 19816 | at the termination. |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 19817 | - per-request control of log-level, e.g. |
Jim Freeman | 9e8714b | 2015-05-26 09:16:34 -0600 | [diff] [blame] | 19818 | http-request set-log-level silent if sensitive_request |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19819 | |
| 19820 | The ability to distribute different levels of logs to different log servers |
| 19821 | allow several production teams to interact and to fix their problems as soon |
| 19822 | as possible. For example, the system team might monitor system-wide errors, |
| 19823 | while the application team might be monitoring the up/down for their servers in |
| 19824 | real time, and the security team might analyze the activity logs with one hour |
| 19825 | delay. |
| 19826 | |
| 19827 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19828 | 8.1. Log levels |
| 19829 | --------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19830 | |
Simon Horman | df791f5 | 2011-05-29 15:01:10 +0900 | [diff] [blame] | 19831 | 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] | 19832 | source IP address, destination address, connection duration, response times, |
Simon Horman | df791f5 | 2011-05-29 15:01:10 +0900 | [diff] [blame] | 19833 | HTTP request, HTTP return code, number of bytes transmitted, conditions |
| 19834 | in which the session ended, and even exchanged cookies values. For example |
| 19835 | track a particular user's problems. All messages may be sent to up to two |
| 19836 | syslog servers. Check the "log" keyword in section 4.2 for more information |
| 19837 | about log facilities. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19838 | |
| 19839 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19840 | 8.2. Log formats |
| 19841 | ---------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19842 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 19843 | HAProxy supports 5 log formats. Several fields are common between these formats |
Simon Horman | df791f5 | 2011-05-29 15:01:10 +0900 | [diff] [blame] | 19844 | and will be detailed in the following sections. A few of them may vary |
| 19845 | slightly with the configuration, due to indicators specific to certain |
| 19846 | options. The supported formats are as follows : |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19847 | |
| 19848 | - the default format, which is very basic and very rarely used. It only |
| 19849 | provides very basic information about the incoming connection at the moment |
| 19850 | it is accepted : source IP:port, destination IP:port, and frontend-name. |
| 19851 | This mode will eventually disappear so it will not be described to great |
| 19852 | extents. |
| 19853 | |
| 19854 | - the TCP format, which is more advanced. This format is enabled when "option |
| 19855 | tcplog" is set on the frontend. HAProxy will then usually wait for the |
| 19856 | connection to terminate before logging. This format provides much richer |
| 19857 | information, such as timers, connection counts, queue size, etc... This |
| 19858 | format is recommended for pure TCP proxies. |
| 19859 | |
| 19860 | - the HTTP format, which is the most advanced for HTTP proxying. This format |
| 19861 | is enabled when "option httplog" is set on the frontend. It provides the |
| 19862 | same information as the TCP format with some HTTP-specific fields such as |
| 19863 | the request, the status code, and captures of headers and cookies. This |
| 19864 | format is recommended for HTTP proxies. |
| 19865 | |
Emeric Brun | 3a058f3 | 2009-06-30 18:26:00 +0200 | [diff] [blame] | 19866 | - the CLF HTTP format, which is equivalent to the HTTP format, but with the |
| 19867 | fields arranged in the same order as the CLF format. In this mode, all |
| 19868 | timers, captures, flags, etc... appear one per field after the end of the |
| 19869 | common fields, in the same order they appear in the standard HTTP format. |
| 19870 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 19871 | - the custom log format, allows you to make your own log line. |
| 19872 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19873 | Next sections will go deeper into details for each of these formats. Format |
| 19874 | specification will be performed on a "field" basis. Unless stated otherwise, a |
| 19875 | field is a portion of text delimited by any number of spaces. Since syslog |
| 19876 | servers are susceptible of inserting fields at the beginning of a line, it is |
| 19877 | always assumed that the first field is the one containing the process name and |
| 19878 | identifier. |
| 19879 | |
| 19880 | Note : Since log lines may be quite long, the log examples in sections below |
| 19881 | might be broken into multiple lines. The example log lines will be |
| 19882 | prefixed with 3 closing angle brackets ('>>>') and each time a log is |
| 19883 | broken into multiple lines, each non-final line will end with a |
| 19884 | backslash ('\') and the next line will start indented by two characters. |
| 19885 | |
| 19886 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19887 | 8.2.1. Default log format |
| 19888 | ------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19889 | |
| 19890 | This format is used when no specific option is set. The log is emitted as soon |
| 19891 | as the connection is accepted. One should note that this currently is the only |
| 19892 | format which logs the request's destination IP and ports. |
| 19893 | |
| 19894 | Example : |
| 19895 | listen www |
| 19896 | mode http |
| 19897 | log global |
| 19898 | server srv1 127.0.0.1:8000 |
| 19899 | |
| 19900 | >>> Feb 6 12:12:09 localhost \ |
| 19901 | haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \ |
| 19902 | (www/HTTP) |
| 19903 | |
| 19904 | Field Format Extract from the example above |
| 19905 | 1 process_name '[' pid ']:' haproxy[14385]: |
| 19906 | 2 'Connect from' Connect from |
| 19907 | 3 source_ip ':' source_port 10.0.1.2:33312 |
| 19908 | 4 'to' to |
| 19909 | 5 destination_ip ':' destination_port 10.0.3.31:8012 |
| 19910 | 6 '(' frontend_name '/' mode ')' (www/HTTP) |
| 19911 | |
| 19912 | Detailed fields description : |
| 19913 | - "source_ip" is the IP address of the client which initiated the connection. |
| 19914 | - "source_port" is the TCP port of the client which initiated the connection. |
| 19915 | - "destination_ip" is the IP address the client connected to. |
| 19916 | - "destination_port" is the TCP port the client connected to. |
| 19917 | - "frontend_name" is the name of the frontend (or listener) which received |
| 19918 | and processed the connection. |
| 19919 | - "mode is the mode the frontend is operating (TCP or HTTP). |
| 19920 | |
Willy Tarreau | ceb24bc | 2010-11-09 12:46:41 +0100 | [diff] [blame] | 19921 | In case of a UNIX socket, the source and destination addresses are marked as |
| 19922 | "unix:" and the ports reflect the internal ID of the socket which accepted the |
| 19923 | connection (the same ID as reported in the stats). |
| 19924 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19925 | It is advised not to use this deprecated format for newer installations as it |
| 19926 | will eventually disappear. |
| 19927 | |
| 19928 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 19929 | 8.2.2. TCP log format |
| 19930 | --------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19931 | |
| 19932 | The TCP format is used when "option tcplog" is specified in the frontend, and |
| 19933 | is the recommended format for pure TCP proxies. It provides a lot of precious |
| 19934 | information for troubleshooting. Since this format includes timers and byte |
| 19935 | counts, the log is normally emitted at the end of the session. It can be |
| 19936 | emitted earlier if "option logasap" is specified, which makes sense in most |
| 19937 | environments with long sessions such as remote terminals. Sessions which match |
| 19938 | the "monitor" rules are never logged. It is also possible not to emit logs for |
| 19939 | 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] | 19940 | specifying "option dontlognull" in the frontend. Successful connections will |
| 19941 | not be logged if "option dontlog-normal" is specified in the frontend. A few |
| 19942 | fields may slightly vary depending on some configuration options, those are |
| 19943 | marked with a star ('*') after the field name below. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19944 | |
| 19945 | Example : |
| 19946 | frontend fnt |
| 19947 | mode tcp |
| 19948 | option tcplog |
| 19949 | log global |
| 19950 | default_backend bck |
| 19951 | |
| 19952 | backend bck |
| 19953 | server srv1 127.0.0.1:8000 |
| 19954 | |
| 19955 | >>> Feb 6 12:12:56 localhost \ |
| 19956 | haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \ |
| 19957 | bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0 |
| 19958 | |
| 19959 | Field Format Extract from the example above |
| 19960 | 1 process_name '[' pid ']:' haproxy[14387]: |
| 19961 | 2 client_ip ':' client_port 10.0.1.2:33313 |
| 19962 | 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443] |
| 19963 | 4 frontend_name fnt |
| 19964 | 5 backend_name '/' server_name bck/srv1 |
| 19965 | 6 Tw '/' Tc '/' Tt* 0/0/5007 |
| 19966 | 7 bytes_read* 212 |
| 19967 | 8 termination_state -- |
| 19968 | 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3 |
| 19969 | 10 srv_queue '/' backend_queue 0/0 |
| 19970 | |
| 19971 | Detailed fields description : |
| 19972 | - "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] | 19973 | connection to haproxy. If the connection was accepted on a UNIX socket |
| 19974 | instead, the IP address would be replaced with the word "unix". Note that |
| 19975 | when the connection is accepted on a socket configured with "accept-proxy" |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 19976 | and the PROXY protocol is correctly used, or with a "accept-netscaler-cip" |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 19977 | and the NetScaler Client IP insertion protocol is correctly used, then the |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 19978 | logs will reflect the forwarded connection's information. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19979 | |
| 19980 | - "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] | 19981 | If the connection was accepted on a UNIX socket instead, the port would be |
| 19982 | replaced with the ID of the accepting socket, which is also reported in the |
| 19983 | stats interface. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19984 | |
| 19985 | - "accept_date" is the exact date when the connection was received by haproxy |
| 19986 | (which might be very slightly different from the date observed on the |
| 19987 | network if there was some queuing in the system's backlog). This is usually |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 19988 | the same date which may appear in any upstream firewall's log. When used in |
| 19989 | HTTP mode, the accept_date field will be reset to the first moment the |
| 19990 | connection is ready to receive a new request (end of previous response for |
| 19991 | HTTP/1, immediately after previous request for HTTP/2). |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 19992 | |
| 19993 | - "frontend_name" is the name of the frontend (or listener) which received |
| 19994 | and processed the connection. |
| 19995 | |
| 19996 | - "backend_name" is the name of the backend (or listener) which was selected |
| 19997 | to manage the connection to the server. This will be the same as the |
| 19998 | frontend if no switching rule has been applied, which is common for TCP |
| 19999 | applications. |
| 20000 | |
| 20001 | - "server_name" is the name of the last server to which the connection was |
| 20002 | sent, which might differ from the first one if there were connection errors |
| 20003 | and a redispatch occurred. Note that this server belongs to the backend |
| 20004 | which processed the request. If the connection was aborted before reaching |
| 20005 | a server, "<NOSRV>" is indicated instead of a server name. |
| 20006 | |
| 20007 | - "Tw" is the total time in milliseconds spent waiting in the various queues. |
| 20008 | It can be "-1" if the connection was aborted before reaching the queue. |
| 20009 | See "Timers" below for more details. |
| 20010 | |
| 20011 | - "Tc" is the total time in milliseconds spent waiting for the connection to |
| 20012 | establish to the final server, including retries. It can be "-1" if the |
| 20013 | connection was aborted before a connection could be established. See |
| 20014 | "Timers" below for more details. |
| 20015 | |
| 20016 | - "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] | 20017 | last close. It covers all possible processing. There is one exception, if |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20018 | "option logasap" was specified, then the time counting stops at the moment |
| 20019 | the log is emitted. In this case, a '+' sign is prepended before the value, |
| 20020 | indicating that the final one will be larger. See "Timers" below for more |
| 20021 | details. |
| 20022 | |
| 20023 | - "bytes_read" is the total number of bytes transmitted from the server to |
| 20024 | the client when the log is emitted. If "option logasap" is specified, the |
| 20025 | this value will be prefixed with a '+' sign indicating that the final one |
| 20026 | may be larger. Please note that this value is a 64-bit counter, so log |
| 20027 | analysis tools must be able to handle it without overflowing. |
| 20028 | |
| 20029 | - "termination_state" is the condition the session was in when the session |
| 20030 | ended. This indicates the session state, which side caused the end of |
| 20031 | session to happen, and for what reason (timeout, error, ...). The normal |
| 20032 | flags should be "--", indicating the session was closed by either end with |
| 20033 | no data remaining in buffers. See below "Session state at disconnection" |
| 20034 | for more details. |
| 20035 | |
| 20036 | - "actconn" is the total number of concurrent connections on the process when |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 20037 | 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] | 20038 | limits have been reached. For instance, if actconn is close to 512 when |
| 20039 | multiple connection errors occur, chances are high that the system limits |
| 20040 | 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] | 20041 | 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] | 20042 | |
| 20043 | - "feconn" is the total number of concurrent connections on the frontend when |
| 20044 | the session was logged. It is useful to estimate the amount of resource |
| 20045 | required to sustain high loads, and to detect when the frontend's "maxconn" |
| 20046 | has been reached. Most often when this value increases by huge jumps, it is |
| 20047 | because there is congestion on the backend servers, but sometimes it can be |
| 20048 | caused by a denial of service attack. |
| 20049 | |
| 20050 | - "beconn" is the total number of concurrent connections handled by the |
| 20051 | backend when the session was logged. It includes the total number of |
| 20052 | concurrent connections active on servers as well as the number of |
| 20053 | connections pending in queues. It is useful to estimate the amount of |
| 20054 | additional servers needed to support high loads for a given application. |
| 20055 | Most often when this value increases by huge jumps, it is because there is |
| 20056 | congestion on the backend servers, but sometimes it can be caused by a |
| 20057 | denial of service attack. |
| 20058 | |
| 20059 | - "srv_conn" is the total number of concurrent connections still active on |
| 20060 | the server when the session was logged. It can never exceed the server's |
| 20061 | configured "maxconn" parameter. If this value is very often close or equal |
| 20062 | to the server's "maxconn", it means that traffic regulation is involved a |
| 20063 | lot, meaning that either the server's maxconn value is too low, or that |
| 20064 | there aren't enough servers to process the load with an optimal response |
| 20065 | time. When only one of the server's "srv_conn" is high, it usually means |
| 20066 | that this server has some trouble causing the connections to take longer to |
| 20067 | be processed than on other servers. |
| 20068 | |
| 20069 | - "retries" is the number of connection retries experienced by this session |
| 20070 | when trying to connect to the server. It must normally be zero, unless a |
| 20071 | server is being stopped at the same moment the connection was attempted. |
| 20072 | Frequent retries generally indicate either a network problem between |
| 20073 | haproxy and the server, or a misconfigured system backlog on the server |
| 20074 | preventing new connections from being queued. This field may optionally be |
| 20075 | prefixed with a '+' sign, indicating that the session has experienced a |
| 20076 | redispatch after the maximal retry count has been reached on the initial |
| 20077 | server. In this case, the server name appearing in the log is the one the |
| 20078 | connection was redispatched to, and not the first one, though both may |
| 20079 | sometimes be the same in case of hashing for instance. So as a general rule |
| 20080 | of thumb, when a '+' is present in front of the retry count, this count |
| 20081 | should not be attributed to the logged server. |
| 20082 | |
| 20083 | - "srv_queue" is the total number of requests which were processed before |
| 20084 | this one in the server queue. It is zero when the request has not gone |
| 20085 | through the server queue. It makes it possible to estimate the approximate |
| 20086 | server's response time by dividing the time spent in queue by the number of |
| 20087 | requests in the queue. It is worth noting that if a session experiences a |
| 20088 | redispatch and passes through two server queues, their positions will be |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20089 | cumulative. A request should not pass through both the server queue and the |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20090 | backend queue unless a redispatch occurs. |
| 20091 | |
| 20092 | - "backend_queue" is the total number of requests which were processed before |
| 20093 | this one in the backend's global queue. It is zero when the request has not |
| 20094 | gone through the global queue. It makes it possible to estimate the average |
| 20095 | queue length, which easily translates into a number of missing servers when |
| 20096 | divided by a server's "maxconn" parameter. It is worth noting that if a |
| 20097 | session experiences a redispatch, it may pass twice in the backend's queue, |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20098 | and then both positions will be cumulative. A request should not pass |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20099 | through both the server queue and the backend queue unless a redispatch |
| 20100 | occurs. |
| 20101 | |
| 20102 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20103 | 8.2.3. HTTP log format |
| 20104 | ---------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20105 | |
| 20106 | The HTTP format is the most complete and the best suited for HTTP proxies. It |
| 20107 | is enabled by when "option httplog" is specified in the frontend. It provides |
| 20108 | the same level of information as the TCP format with additional features which |
| 20109 | are specific to the HTTP protocol. Just like the TCP format, the log is usually |
| 20110 | emitted at the end of the session, unless "option logasap" is specified, which |
| 20111 | generally only makes sense for download sites. A session which matches the |
| 20112 | "monitor" rules will never logged. It is also possible not to log sessions for |
| 20113 | 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] | 20114 | frontend. Successful connections will not be logged if "option dontlog-normal" |
| 20115 | is specified in the frontend. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20116 | |
| 20117 | Most fields are shared with the TCP log, some being different. A few fields may |
| 20118 | slightly vary depending on some configuration options. Those ones are marked |
| 20119 | with a star ('*') after the field name below. |
| 20120 | |
| 20121 | Example : |
| 20122 | frontend http-in |
| 20123 | mode http |
| 20124 | option httplog |
| 20125 | log global |
| 20126 | default_backend bck |
| 20127 | |
| 20128 | backend static |
| 20129 | server srv1 127.0.0.1:8000 |
| 20130 | |
| 20131 | >>> Feb 6 12:14:14 localhost \ |
| 20132 | haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ |
| 20133 | 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] | 20134 | {} "GET /index.html HTTP/1.1" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20135 | |
| 20136 | Field Format Extract from the example above |
| 20137 | 1 process_name '[' pid ']:' haproxy[14389]: |
| 20138 | 2 client_ip ':' client_port 10.0.1.2:33317 |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20139 | 3 '[' request_date ']' [06/Feb/2009:12:14:14.655] |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20140 | 4 frontend_name http-in |
| 20141 | 5 backend_name '/' server_name static/srv1 |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20142 | 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109 |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20143 | 7 status_code 200 |
| 20144 | 8 bytes_read* 2750 |
| 20145 | 9 captured_request_cookie - |
| 20146 | 10 captured_response_cookie - |
| 20147 | 11 termination_state ---- |
| 20148 | 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0 |
| 20149 | 13 srv_queue '/' backend_queue 0/0 |
| 20150 | 14 '{' captured_request_headers* '}' {haproxy.1wt.eu} |
| 20151 | 15 '{' captured_response_headers* '}' {} |
| 20152 | 16 '"' http_request '"' "GET /index.html HTTP/1.1" |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 20153 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20154 | Detailed fields description : |
| 20155 | - "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] | 20156 | connection to haproxy. If the connection was accepted on a UNIX socket |
| 20157 | instead, the IP address would be replaced with the word "unix". Note that |
| 20158 | when the connection is accepted on a socket configured with "accept-proxy" |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 20159 | and the PROXY protocol is correctly used, or with a "accept-netscaler-cip" |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20160 | and the NetScaler Client IP insertion protocol is correctly used, then the |
Bertrand Jacquin | 93b227d | 2016-06-04 15:11:10 +0100 | [diff] [blame] | 20161 | logs will reflect the forwarded connection's information. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20162 | |
| 20163 | - "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] | 20164 | If the connection was accepted on a UNIX socket instead, the port would be |
| 20165 | replaced with the ID of the accepting socket, which is also reported in the |
| 20166 | stats interface. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20167 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20168 | - "request_date" is the exact date when the first byte of the HTTP request |
| 20169 | was received by haproxy (log field %tr). |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20170 | |
| 20171 | - "frontend_name" is the name of the frontend (or listener) which received |
| 20172 | and processed the connection. |
| 20173 | |
| 20174 | - "backend_name" is the name of the backend (or listener) which was selected |
| 20175 | to manage the connection to the server. This will be the same as the |
| 20176 | frontend if no switching rule has been applied. |
| 20177 | |
| 20178 | - "server_name" is the name of the last server to which the connection was |
| 20179 | sent, which might differ from the first one if there were connection errors |
| 20180 | and a redispatch occurred. Note that this server belongs to the backend |
| 20181 | which processed the request. If the request was aborted before reaching a |
| 20182 | server, "<NOSRV>" is indicated instead of a server name. If the request was |
| 20183 | intercepted by the stats subsystem, "<STATS>" is indicated instead. |
| 20184 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20185 | - "TR" is the total time in milliseconds spent waiting for a full HTTP |
| 20186 | request from the client (not counting body) after the first byte was |
| 20187 | received. It can be "-1" if the connection was aborted before a complete |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 20188 | request could be received or a bad request was received. It should |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20189 | always be very small because a request generally fits in one single packet. |
| 20190 | Large times here generally indicate network issues between the client and |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20191 | haproxy or requests being typed by hand. See section 8.4 "Timing Events" |
| 20192 | for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20193 | |
| 20194 | - "Tw" is the total time in milliseconds spent waiting in the various queues. |
| 20195 | It can be "-1" if the connection was aborted before reaching the queue. |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20196 | See section 8.4 "Timing Events" for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20197 | |
| 20198 | - "Tc" is the total time in milliseconds spent waiting for the connection to |
| 20199 | establish to the final server, including retries. It can be "-1" if the |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20200 | request was aborted before a connection could be established. See section |
| 20201 | 8.4 "Timing Events" for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20202 | |
| 20203 | - "Tr" is the total time in milliseconds spent waiting for the server to send |
| 20204 | a full HTTP response, not counting data. It can be "-1" if the request was |
| 20205 | aborted before a complete response could be received. It generally matches |
| 20206 | the server's processing time for the request, though it may be altered by |
| 20207 | the amount of data sent by the client to the server. Large times here on |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20208 | "GET" requests generally indicate an overloaded server. See section 8.4 |
| 20209 | "Timing Events" for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20210 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20211 | - "Ta" is the time the request remained active in haproxy, which is the total |
| 20212 | time in milliseconds elapsed between the first byte of the request was |
| 20213 | received and the last byte of response was sent. It covers all possible |
| 20214 | processing except the handshake (see Th) and idle time (see Ti). There is |
| 20215 | one exception, if "option logasap" was specified, then the time counting |
| 20216 | stops at the moment the log is emitted. In this case, a '+' sign is |
| 20217 | prepended before the value, indicating that the final one will be larger. |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20218 | See section 8.4 "Timing Events" for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20219 | |
| 20220 | - "status_code" is the HTTP status code returned to the client. This status |
| 20221 | is generally set by the server, but it might also be set by haproxy when |
| 20222 | the server cannot be reached or when its response is blocked by haproxy. |
| 20223 | |
| 20224 | - "bytes_read" is the total number of bytes transmitted to the client when |
| 20225 | the log is emitted. This does include HTTP headers. If "option logasap" is |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 20226 | specified, this value will be prefixed with a '+' sign indicating that |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20227 | the final one may be larger. Please note that this value is a 64-bit |
| 20228 | counter, so log analysis tools must be able to handle it without |
| 20229 | overflowing. |
| 20230 | |
| 20231 | - "captured_request_cookie" is an optional "name=value" entry indicating that |
| 20232 | the client had this cookie in the request. The cookie name and its maximum |
| 20233 | length are defined by the "capture cookie" statement in the frontend |
| 20234 | configuration. The field is a single dash ('-') when the option is not |
| 20235 | set. Only one cookie may be captured, it is generally used to track session |
| 20236 | ID exchanges between a client and a server to detect session crossing |
| 20237 | between clients due to application bugs. For more details, please consult |
| 20238 | the section "Capturing HTTP headers and cookies" below. |
| 20239 | |
| 20240 | - "captured_response_cookie" is an optional "name=value" entry indicating |
| 20241 | that the server has returned a cookie with its response. The cookie name |
| 20242 | and its maximum length are defined by the "capture cookie" statement in the |
| 20243 | frontend configuration. The field is a single dash ('-') when the option is |
| 20244 | not set. Only one cookie may be captured, it is generally used to track |
| 20245 | session ID exchanges between a client and a server to detect session |
| 20246 | crossing between clients due to application bugs. For more details, please |
| 20247 | consult the section "Capturing HTTP headers and cookies" below. |
| 20248 | |
| 20249 | - "termination_state" is the condition the session was in when the session |
| 20250 | ended. This indicates the session state, which side caused the end of |
| 20251 | session to happen, for what reason (timeout, error, ...), just like in TCP |
| 20252 | logs, and information about persistence operations on cookies in the last |
| 20253 | two characters. The normal flags should begin with "--", indicating the |
| 20254 | session was closed by either end with no data remaining in buffers. See |
| 20255 | below "Session state at disconnection" for more details. |
| 20256 | |
| 20257 | - "actconn" is the total number of concurrent connections on the process when |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 20258 | 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] | 20259 | limits have been reached. For instance, if actconn is close to 512 or 1024 |
| 20260 | when multiple connection errors occur, chances are high that the system |
| 20261 | 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] | 20262 | 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] | 20263 | system. |
| 20264 | |
| 20265 | - "feconn" is the total number of concurrent connections on the frontend when |
| 20266 | the session was logged. It is useful to estimate the amount of resource |
| 20267 | required to sustain high loads, and to detect when the frontend's "maxconn" |
| 20268 | has been reached. Most often when this value increases by huge jumps, it is |
| 20269 | because there is congestion on the backend servers, but sometimes it can be |
| 20270 | caused by a denial of service attack. |
| 20271 | |
| 20272 | - "beconn" is the total number of concurrent connections handled by the |
| 20273 | backend when the session was logged. It includes the total number of |
| 20274 | concurrent connections active on servers as well as the number of |
| 20275 | connections pending in queues. It is useful to estimate the amount of |
| 20276 | additional servers needed to support high loads for a given application. |
| 20277 | Most often when this value increases by huge jumps, it is because there is |
| 20278 | congestion on the backend servers, but sometimes it can be caused by a |
| 20279 | denial of service attack. |
| 20280 | |
| 20281 | - "srv_conn" is the total number of concurrent connections still active on |
| 20282 | the server when the session was logged. It can never exceed the server's |
| 20283 | configured "maxconn" parameter. If this value is very often close or equal |
| 20284 | to the server's "maxconn", it means that traffic regulation is involved a |
| 20285 | lot, meaning that either the server's maxconn value is too low, or that |
| 20286 | there aren't enough servers to process the load with an optimal response |
| 20287 | time. When only one of the server's "srv_conn" is high, it usually means |
| 20288 | that this server has some trouble causing the requests to take longer to be |
| 20289 | processed than on other servers. |
| 20290 | |
| 20291 | - "retries" is the number of connection retries experienced by this session |
| 20292 | when trying to connect to the server. It must normally be zero, unless a |
| 20293 | server is being stopped at the same moment the connection was attempted. |
| 20294 | Frequent retries generally indicate either a network problem between |
| 20295 | haproxy and the server, or a misconfigured system backlog on the server |
| 20296 | preventing new connections from being queued. This field may optionally be |
| 20297 | prefixed with a '+' sign, indicating that the session has experienced a |
| 20298 | redispatch after the maximal retry count has been reached on the initial |
| 20299 | server. In this case, the server name appearing in the log is the one the |
| 20300 | connection was redispatched to, and not the first one, though both may |
| 20301 | sometimes be the same in case of hashing for instance. So as a general rule |
| 20302 | of thumb, when a '+' is present in front of the retry count, this count |
| 20303 | should not be attributed to the logged server. |
| 20304 | |
| 20305 | - "srv_queue" is the total number of requests which were processed before |
| 20306 | this one in the server queue. It is zero when the request has not gone |
| 20307 | through the server queue. It makes it possible to estimate the approximate |
| 20308 | server's response time by dividing the time spent in queue by the number of |
| 20309 | requests in the queue. It is worth noting that if a session experiences a |
| 20310 | redispatch and passes through two server queues, their positions will be |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20311 | cumulative. A request should not pass through both the server queue and the |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20312 | backend queue unless a redispatch occurs. |
| 20313 | |
| 20314 | - "backend_queue" is the total number of requests which were processed before |
| 20315 | this one in the backend's global queue. It is zero when the request has not |
| 20316 | gone through the global queue. It makes it possible to estimate the average |
| 20317 | queue length, which easily translates into a number of missing servers when |
| 20318 | divided by a server's "maxconn" parameter. It is worth noting that if a |
| 20319 | session experiences a redispatch, it may pass twice in the backend's queue, |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20320 | and then both positions will be cumulative. A request should not pass |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20321 | through both the server queue and the backend queue unless a redispatch |
| 20322 | occurs. |
| 20323 | |
| 20324 | - "captured_request_headers" is a list of headers captured in the request due |
| 20325 | to the presence of the "capture request header" statement in the frontend. |
| 20326 | Multiple headers can be captured, they will be delimited by a vertical bar |
| 20327 | ('|'). When no capture is enabled, the braces do not appear, causing a |
| 20328 | shift of remaining fields. It is important to note that this field may |
| 20329 | contain spaces, and that using it requires a smarter log parser than when |
| 20330 | it's not used. Please consult the section "Capturing HTTP headers and |
| 20331 | cookies" below for more details. |
| 20332 | |
| 20333 | - "captured_response_headers" is a list of headers captured in the response |
| 20334 | due to the presence of the "capture response header" statement in the |
| 20335 | frontend. Multiple headers can be captured, they will be delimited by a |
| 20336 | vertical bar ('|'). When no capture is enabled, the braces do not appear, |
| 20337 | causing a shift of remaining fields. It is important to note that this |
| 20338 | field may contain spaces, and that using it requires a smarter log parser |
| 20339 | than when it's not used. Please consult the section "Capturing HTTP headers |
| 20340 | and cookies" below for more details. |
| 20341 | |
| 20342 | - "http_request" is the complete HTTP request line, including the method, |
| 20343 | request and HTTP version string. Non-printable characters are encoded (see |
| 20344 | below the section "Non-printable characters"). This is always the last |
| 20345 | field, and it is always delimited by quotes and is the only one which can |
| 20346 | contain quotes. If new fields are added to the log format, they will be |
| 20347 | added before this field. This field might be truncated if the request is |
| 20348 | huge and does not fit in the standard syslog buffer (1024 characters). This |
| 20349 | is the reason why this field must always remain the last one. |
| 20350 | |
| 20351 | |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 20352 | 8.2.4. Custom log format |
| 20353 | ------------------------ |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20354 | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20355 | 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] | 20356 | mode. It takes a string as argument. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20357 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20358 | HAProxy understands some log format variables. % precedes log format variables. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20359 | Variables can take arguments using braces ('{}'), and multiple arguments are |
| 20360 | separated by commas within the braces. Flags may be added or removed by |
| 20361 | prefixing them with a '+' or '-' sign. |
| 20362 | |
| 20363 | Special variable "%o" may be used to propagate its flags to all other |
| 20364 | variables on the same format string. This is particularly handy with quoted |
Dragan Dosen | 835b921 | 2016-02-12 13:23:03 +0100 | [diff] [blame] | 20365 | ("Q") and escaped ("E") string formats. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20366 | |
Willy Tarreau | c836845 | 2012-12-21 00:09:23 +0100 | [diff] [blame] | 20367 | If a variable is named between square brackets ('[' .. ']') then it is used |
Willy Tarreau | be722a2 | 2014-06-13 16:31:59 +0200 | [diff] [blame] | 20368 | as a sample expression rule (see section 7.3). This it useful to add some |
Willy Tarreau | c836845 | 2012-12-21 00:09:23 +0100 | [diff] [blame] | 20369 | less common information such as the client's SSL certificate's DN, or to log |
| 20370 | the key that would be used to store an entry into a stick table. |
| 20371 | |
Dragan Dosen | 1e3b16f | 2020-06-23 18:16:44 +0200 | [diff] [blame] | 20372 | Note: spaces must be escaped. In configuration directives "log-format", |
| 20373 | "log-format-sd" and "unique-id-format", spaces are considered as |
| 20374 | delimiters and are merged. In order to emit a verbatim '%', it must be |
| 20375 | preceded by another '%' resulting in '%%'. |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20376 | |
Dragan Dosen | 835b921 | 2016-02-12 13:23:03 +0100 | [diff] [blame] | 20377 | Note: when using the RFC5424 syslog message format, the characters '"', |
| 20378 | '\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see |
| 20379 | https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In |
| 20380 | such cases, the use of the flag "E" should be considered. |
| 20381 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20382 | Flags are : |
| 20383 | * Q: quote a string |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 20384 | * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid) |
Dragan Dosen | 835b921 | 2016-02-12 13:23:03 +0100 | [diff] [blame] | 20385 | * E: escape characters '"', '\' and ']' in a string with '\' as prefix |
| 20386 | (intended purpose is for the RFC5424 structured-data log formats) |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20387 | |
| 20388 | Example: |
| 20389 | |
| 20390 | log-format %T\ %t\ Some\ Text |
| 20391 | log-format %{+Q}o\ %t\ %s\ %{-Q}r |
| 20392 | |
Dragan Dosen | 835b921 | 2016-02-12 13:23:03 +0100 | [diff] [blame] | 20393 | log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]] |
| 20394 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20395 | At the moment, the default HTTP format is defined this way : |
| 20396 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20397 | log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \ |
| 20398 | %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] | 20399 | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20400 | the default CLF format is defined this way : |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20401 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20402 | log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \ |
| 20403 | %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \ |
| 20404 | %bc %sc %rc %sq %bq %CC %CS %hrl %hsl" |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20405 | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20406 | and the default TCP format is defined this way : |
| 20407 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20408 | log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \ |
| 20409 | %ac/%fc/%bc/%sc/%rc %sq/%bq" |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20410 | |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20411 | Please refer to the table below for currently defined variables : |
| 20412 | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20413 | +---+------+-----------------------------------------------+-------------+ |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 20414 | | 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] | 20415 | +---+------+-----------------------------------------------+-------------+ |
| 20416 | | | %o | special variable, apply flags on all next var | | |
| 20417 | +---+------+-----------------------------------------------+-------------+ |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20418 | | | %B | bytes_read (from server to client) | numeric | |
| 20419 | | H | %CC | captured_request_cookie | string | |
| 20420 | | H | %CS | captured_response_cookie | string | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 20421 | | | %H | hostname | string | |
Andrew Hayworth | 0ebc55f | 2015-04-27 21:37:03 +0000 | [diff] [blame] | 20422 | | H | %HM | HTTP method (ex: POST) | string | |
Maciej Zdeb | 21acc33 | 2020-11-26 10:45:52 +0000 | [diff] [blame] | 20423 | | H | %HP | HTTP request URI without query string | string | |
Maciej Zdeb | fcdfd85 | 2020-11-30 18:27:47 +0000 | [diff] [blame] | 20424 | | H | %HPO | HTTP path only (without host nor query string)| string | |
Andrew Hayworth | e63ac87 | 2015-07-31 16:14:16 +0000 | [diff] [blame] | 20425 | | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string | |
Andrew Hayworth | 0ebc55f | 2015-04-27 21:37:03 +0000 | [diff] [blame] | 20426 | | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string | |
| 20427 | | H | %HV | HTTP version (ex: HTTP/1.0) | string | |
William Lallemand | a73203e | 2012-03-12 12:48:57 +0100 | [diff] [blame] | 20428 | | | %ID | unique-id | string | |
Willy Tarreau | 4bf9963 | 2014-06-13 12:21:40 +0200 | [diff] [blame] | 20429 | | | %ST | status_code | numeric | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 20430 | | | %T | gmt_date_time | date | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20431 | | | %Ta | Active time of the request (from TR to end) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20432 | | | %Tc | Tc | numeric | |
Willy Tarreau | 27b639d | 2016-05-17 17:55:27 +0200 | [diff] [blame] | 20433 | | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric | |
Yuxans Yao | 4e25b01 | 2012-10-19 10:36:09 +0800 | [diff] [blame] | 20434 | | | %Tl | local_date_time | date | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20435 | | | %Th | connection handshake time (SSL, PROXY proto) | numeric | |
| 20436 | | H | %Ti | idle time before the HTTP request | numeric | |
| 20437 | | H | %Tq | Th + Ti + TR | numeric | |
| 20438 | | H | %TR | time to receive the full request from 1st byte| numeric | |
| 20439 | | H | %Tr | Tr (response time) | numeric | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 20440 | | | %Ts | timestamp | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20441 | | | %Tt | Tt | numeric | |
Damien Claisse | 57c8eb9 | 2020-04-28 12:09:19 +0000 | [diff] [blame] | 20442 | | | %Tu | Tu | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20443 | | | %Tw | Tw | numeric | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20444 | | | %U | bytes_uploaded (from client to server) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20445 | | | %ac | actconn | numeric | |
| 20446 | | | %b | backend_name | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20447 | | | %bc | beconn (backend concurrent connections) | numeric | |
| 20448 | | | %bi | backend_source_ip (connecting address) | IP | |
| 20449 | | | %bp | backend_source_port (connecting address) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20450 | | | %bq | backend_queue | numeric | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20451 | | | %ci | client_ip (accepted address) | IP | |
| 20452 | | | %cp | client_port (accepted address) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20453 | | | %f | frontend_name | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20454 | | | %fc | feconn (frontend concurrent connections) | numeric | |
| 20455 | | | %fi | frontend_ip (accepting address) | IP | |
| 20456 | | | %fp | frontend_port (accepting address) | numeric | |
Willy Tarreau | 773d65f | 2012-10-12 14:56:11 +0200 | [diff] [blame] | 20457 | | | %ft | frontend_name_transport ('~' suffix for SSL) | string | |
Willy Tarreau | 7346acb | 2014-08-28 15:03:15 +0200 | [diff] [blame] | 20458 | | | %lc | frontend_log_counter | numeric | |
Willy Tarreau | d9ed3d2 | 2014-06-13 12:23:06 +0200 | [diff] [blame] | 20459 | | | %hr | captured_request_headers default style | string | |
| 20460 | | | %hrl | captured_request_headers CLF style | string list | |
| 20461 | | | %hs | captured_response_headers default style | string | |
| 20462 | | | %hsl | captured_response_headers CLF style | string list | |
Willy Tarreau | 812c88e | 2015-08-09 10:56:35 +0200 | [diff] [blame] | 20463 | | | %ms | accept date milliseconds (left-padded with 0) | numeric | |
William Lallemand | 5f23240 | 2012-04-05 18:02:55 +0200 | [diff] [blame] | 20464 | | | %pid | PID | numeric | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 20465 | | H | %r | http_request | string | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20466 | | | %rc | retries | numeric | |
Willy Tarreau | 1f0da24 | 2014-01-25 11:01:50 +0100 | [diff] [blame] | 20467 | | | %rt | request_counter (HTTP req or TCP session) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20468 | | | %s | server_name | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20469 | | | %sc | srv_conn (server concurrent connections) | numeric | |
| 20470 | | | %si | server_IP (target address) | IP | |
| 20471 | | | %sp | server_port (target address) | numeric | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20472 | | | %sq | srv_queue | numeric | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 20473 | | S | %sslc| ssl_ciphers (ex: AES-SHA) | string | |
| 20474 | | S | %sslv| ssl_version (ex: TLSv1) | string | |
Willy Tarreau | 2beef58 | 2012-12-20 17:22:52 +0100 | [diff] [blame] | 20475 | | | %t | date_time (with millisecond resolution) | date | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20476 | | H | %tr | date_time of HTTP request | date | |
| 20477 | | H | %trg | gmt_date_time of start of HTTP request | date | |
Jens Bissinger | 15c64ff | 2018-08-23 14:11:27 +0200 | [diff] [blame] | 20478 | | H | %trl | local_date_time of start of HTTP request | date | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20479 | | | %ts | termination_state | string | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 20480 | | H | %tsc | termination_state with cookie status | string | |
William Lallemand | bddd4fd | 2012-02-27 11:23:10 +0100 | [diff] [blame] | 20481 | +---+------+-----------------------------------------------+-------------+ |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20482 | |
Willy Tarreau | ffc3fcd | 2012-10-12 20:17:54 +0200 | [diff] [blame] | 20483 | R = Restrictions : H = mode http only ; S = SSL only |
William Lallemand | 4894040 | 2012-01-30 16:47:22 +0100 | [diff] [blame] | 20484 | |
Willy Tarreau | 5f51e1a | 2012-12-03 18:40:10 +0100 | [diff] [blame] | 20485 | |
| 20486 | 8.2.5. Error log format |
| 20487 | ----------------------- |
| 20488 | |
| 20489 | When an incoming connection fails due to an SSL handshake or an invalid PROXY |
| 20490 | protocol header, haproxy will log the event using a shorter, fixed line format. |
| 20491 | By default, logs are emitted at the LOG_INFO level, unless the option |
| 20492 | "log-separate-errors" is set in the backend, in which case the LOG_ERR level |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20493 | will be used. Connections on which no data are exchanged (e.g. probes) are not |
Willy Tarreau | 5f51e1a | 2012-12-03 18:40:10 +0100 | [diff] [blame] | 20494 | logged if the "dontlognull" option is set. |
| 20495 | |
| 20496 | The format looks like this : |
| 20497 | |
| 20498 | >>> Dec 3 18:27:14 localhost \ |
| 20499 | haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \ |
| 20500 | Connection error during SSL handshake |
| 20501 | |
| 20502 | Field Format Extract from the example above |
| 20503 | 1 process_name '[' pid ']:' haproxy[6103]: |
| 20504 | 2 client_ip ':' client_port 127.0.0.1:56059 |
| 20505 | 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380] |
| 20506 | 4 frontend_name "/" bind_name ":" frt/f1: |
| 20507 | 5 message Connection error during SSL handshake |
| 20508 | |
| 20509 | These fields just provide minimal information to help debugging connection |
| 20510 | failures. |
| 20511 | |
| 20512 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20513 | 8.3. Advanced logging options |
| 20514 | ----------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20515 | |
| 20516 | Some advanced logging options are often looked for but are not easy to find out |
| 20517 | just by looking at the various options. Here is an entry point for the few |
| 20518 | options which can enable better logging. Please refer to the keywords reference |
| 20519 | for more information about their usage. |
| 20520 | |
| 20521 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20522 | 8.3.1. Disabling logging of external tests |
| 20523 | ------------------------------------------ |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20524 | |
| 20525 | It is quite common to have some monitoring tools perform health checks on |
| 20526 | haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any |
| 20527 | commercial load-balancer, and sometimes it will simply be a more complete |
| 20528 | monitoring system such as Nagios. When the tests are very frequent, users often |
| 20529 | ask how to disable logging for those checks. There are three possibilities : |
| 20530 | |
| 20531 | - if connections come from everywhere and are just TCP probes, it is often |
| 20532 | desired to simply disable logging of connections without data exchange, by |
| 20533 | setting "option dontlognull" in the frontend. It also disables logging of |
| 20534 | port scans, which may or may not be desired. |
| 20535 | |
Willy Tarreau | 9e9919d | 2020-10-14 15:55:23 +0200 | [diff] [blame] | 20536 | - it is possible to use the "http-request set-log-level silent" action using |
| 20537 | a variety of conditions (source networks, paths, user-agents, etc). |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20538 | |
| 20539 | - if the tests are performed on a known URI, use "monitor-uri" to declare |
| 20540 | this URI as dedicated to monitoring. Any host sending this request will |
| 20541 | only get the result of a health-check, and the request will not be logged. |
| 20542 | |
| 20543 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20544 | 8.3.2. Logging before waiting for the session to terminate |
| 20545 | ---------------------------------------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20546 | |
| 20547 | The problem with logging at end of connection is that you have no clue about |
| 20548 | what is happening during very long sessions, such as remote terminal sessions |
| 20549 | or large file downloads. This problem can be worked around by specifying |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20550 | "option logasap" in the frontend. HAProxy will then log as soon as possible, |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20551 | just before data transfer begins. This means that in case of TCP, it will still |
| 20552 | log the connection status to the server, and in case of HTTP, it will log just |
| 20553 | after processing the server headers. In this case, the number of bytes reported |
| 20554 | is the number of header bytes sent to the client. In order to avoid confusion |
| 20555 | with normal logs, the total time field and the number of bytes are prefixed |
| 20556 | with a '+' sign which means that real numbers are certainly larger. |
| 20557 | |
| 20558 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20559 | 8.3.3. Raising log level upon errors |
| 20560 | ------------------------------------ |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 20561 | |
| 20562 | Sometimes it is more convenient to separate normal traffic from errors logs, |
| 20563 | for instance in order to ease error monitoring from log files. When the option |
| 20564 | "log-separate-errors" is used, connections which experience errors, timeouts, |
| 20565 | retries, redispatches or HTTP status codes 5xx will see their syslog level |
| 20566 | raised from "info" to "err". This will help a syslog daemon store the log in |
| 20567 | a separate file. It is very important to keep the errors in the normal traffic |
| 20568 | file too, so that log ordering is not altered. You should also be careful if |
| 20569 | you already have configured your syslog daemon to store all logs higher than |
| 20570 | "notice" in an "admin" file, because the "err" level is higher than "notice". |
| 20571 | |
| 20572 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20573 | 8.3.4. Disabling logging of successful connections |
| 20574 | -------------------------------------------------- |
Willy Tarreau | c9bd0cc | 2009-05-10 11:57:02 +0200 | [diff] [blame] | 20575 | |
| 20576 | Although this may sound strange at first, some large sites have to deal with |
| 20577 | multiple thousands of logs per second and are experiencing difficulties keeping |
| 20578 | them intact for a long time or detecting errors within them. If the option |
| 20579 | "dontlog-normal" is set on the frontend, all normal connections will not be |
| 20580 | logged. In this regard, a normal connection is defined as one without any |
| 20581 | error, timeout, retry nor redispatch. In HTTP, the status code is checked too, |
| 20582 | and a response with a status 5xx is not considered normal and will be logged |
| 20583 | too. Of course, doing is is really discouraged as it will remove most of the |
| 20584 | useful information from the logs. Do this only if you have no other |
| 20585 | alternative. |
| 20586 | |
| 20587 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20588 | 8.4. Timing events |
| 20589 | ------------------ |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20590 | |
| 20591 | Timers provide a great help in troubleshooting network problems. All values are |
| 20592 | reported in milliseconds (ms). These timers should be used in conjunction with |
| 20593 | the session termination flags. In TCP mode with "option tcplog" set on the |
| 20594 | frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20595 | mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In |
| 20596 | addition, three other measures are provided, "Th", "Ti", and "Tq". |
| 20597 | |
Guillaume de Lafond | f27cddc | 2016-12-23 17:32:43 +0100 | [diff] [blame] | 20598 | Timings events in HTTP mode: |
| 20599 | |
| 20600 | first request 2nd request |
| 20601 | |<-------------------------------->|<-------------- ... |
| 20602 | t tr t tr ... |
| 20603 | ---|----|----|----|----|----|----|----|----|-- |
| 20604 | : Th Ti TR Tw Tc Tr Td : Ti ... |
| 20605 | :<---- Tq ---->: : |
| 20606 | :<-------------- Tt -------------->: |
Damien Claisse | 57c8eb9 | 2020-04-28 12:09:19 +0000 | [diff] [blame] | 20607 | :<-- -----Tu--------------->: |
Guillaume de Lafond | f27cddc | 2016-12-23 17:32:43 +0100 | [diff] [blame] | 20608 | :<--------- Ta --------->: |
| 20609 | |
| 20610 | Timings events in TCP mode: |
| 20611 | |
| 20612 | TCP session |
| 20613 | |<----------------->| |
| 20614 | t t |
| 20615 | ---|----|----|----|----|--- |
| 20616 | | Th Tw Tc Td | |
| 20617 | |<------ Tt ------->| |
| 20618 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20619 | - Th: total time to accept tcp connection and execute handshakes for low level |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20620 | protocols. Currently, these protocols are proxy-protocol and SSL. This may |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20621 | only happen once during the whole connection's lifetime. A large time here |
| 20622 | may indicate that the client only pre-established the connection without |
| 20623 | speaking, that it is experiencing network issues preventing it from |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20624 | completing a handshake in a reasonable time (e.g. MTU issues), or that an |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20625 | SSL handshake was very expensive to compute. Please note that this time is |
| 20626 | reported only before the first request, so it is safe to average it over |
| 20627 | all request to calculate the amortized value. The second and subsequent |
| 20628 | request will always report zero here. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20629 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20630 | - Ti: is the idle time before the HTTP request (HTTP mode only). This timer |
| 20631 | counts between the end of the handshakes and the first byte of the HTTP |
| 20632 | request. When dealing with a second request in keep-alive mode, it starts |
Willy Tarreau | 590a051 | 2018-09-05 11:56:48 +0200 | [diff] [blame] | 20633 | to count after the end of the transmission the previous response. When a |
| 20634 | multiplexed protocol such as HTTP/2 is used, it starts to count immediately |
| 20635 | after the previous request. Some browsers pre-establish connections to a |
| 20636 | server in order to reduce the latency of a future request, and keep them |
| 20637 | pending until they need it. This delay will be reported as the idle time. A |
| 20638 | value of -1 indicates that nothing was received on the connection. |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20639 | |
| 20640 | - TR: total time to get the client request (HTTP mode only). It's the time |
| 20641 | elapsed between the first bytes received and the moment the proxy received |
| 20642 | the empty line marking the end of the HTTP headers. The value "-1" |
| 20643 | indicates that the end of headers has never been seen. This happens when |
| 20644 | the client closes prematurely or times out. This time is usually very short |
| 20645 | since most requests fit in a single packet. A large time may indicate a |
| 20646 | request typed by hand during a test. |
| 20647 | |
| 20648 | - Tq: total time to get the client request from the accept date or since the |
| 20649 | emission of the last byte of the previous response (HTTP mode only). It's |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20650 | exactly equal to Th + Ti + TR unless any of them is -1, in which case it |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20651 | returns -1 as well. This timer used to be very useful before the arrival of |
| 20652 | HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop |
| 20653 | it in favor of TR nowadays, as the idle time adds a lot of noise to the |
| 20654 | reports. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20655 | |
| 20656 | - Tw: total time spent in the queues waiting for a connection slot. It |
| 20657 | accounts for backend queue as well as the server queues, and depends on the |
| 20658 | queue size, and the time needed for the server to complete previous |
| 20659 | requests. The value "-1" means that the request was killed before reaching |
| 20660 | the queue, which is generally what happens with invalid or denied requests. |
| 20661 | |
| 20662 | - Tc: total time to establish the TCP connection to the server. It's the time |
| 20663 | elapsed between the moment the proxy sent the connection request, and the |
| 20664 | moment it was acknowledged by the server, or between the TCP SYN packet and |
| 20665 | the matching SYN/ACK packet in return. The value "-1" means that the |
| 20666 | connection never established. |
| 20667 | |
| 20668 | - Tr: server response time (HTTP mode only). It's the time elapsed between |
| 20669 | the moment the TCP connection was established to the server and the moment |
| 20670 | the server sent its complete response headers. It purely shows its request |
| 20671 | processing time, without the network overhead due to the data transmission. |
| 20672 | It is worth noting that when the client has data to send to the server, for |
| 20673 | instance during a POST request, the time already runs, and this can distort |
| 20674 | apparent response time. For this reason, it's generally wise not to trust |
| 20675 | too much this field for POST requests initiated from clients behind an |
| 20676 | untrusted network. A value of "-1" here means that the last the response |
| 20677 | header (empty line) was never seen, most likely because the server timeout |
| 20678 | stroke before the server managed to process the request. |
| 20679 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20680 | - Ta: total active time for the HTTP request, between the moment the proxy |
| 20681 | received the first byte of the request header and the emission of the last |
| 20682 | byte of the response body. The exception is when the "logasap" option is |
| 20683 | specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with |
| 20684 | a '+' sign. From this field, we can deduce "Td", the data transmission time, |
| 20685 | by subtracting other timers when valid : |
| 20686 | |
| 20687 | Td = Ta - (TR + Tw + Tc + Tr) |
| 20688 | |
| 20689 | Timers with "-1" values have to be excluded from this equation. Note that |
| 20690 | "Ta" can never be negative. |
| 20691 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20692 | - Tt: total session duration time, between the moment the proxy accepted it |
| 20693 | and the moment both ends were closed. The exception is when the "logasap" |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20694 | option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and |
| 20695 | is 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] | 20696 | transmission time, by subtracting other timers when valid : |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20697 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20698 | Td = Tt - (Th + Ti + TR + Tw + Tc + Tr) |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20699 | |
| 20700 | Timers with "-1" values have to be excluded from this equation. In TCP |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20701 | mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never |
| 20702 | be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta). |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20703 | |
Damien Claisse | 57c8eb9 | 2020-04-28 12:09:19 +0000 | [diff] [blame] | 20704 | - Tu: total estimated time as seen from client, between the moment the proxy |
| 20705 | accepted it and the moment both ends were closed, without idle time. |
| 20706 | This is useful to roughly measure end-to-end time as a user would see it, |
| 20707 | without idle time pollution from keep-alive time between requests. This |
| 20708 | timer in only an estimation of time seen by user as it assumes network |
| 20709 | latency is the same in both directions. The exception is when the "logasap" |
| 20710 | option is specified. In this case, it only equals (Th+TR+Tw+Tc+Tr), and is |
| 20711 | prefixed with a '+' sign. |
| 20712 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20713 | These timers provide precious indications on trouble causes. Since the TCP |
| 20714 | protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure |
| 20715 | that timers close to multiples of 3s are nearly always related to lost packets |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20716 | due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or |
| 20717 | "Tt" is close to a timeout value specified in the configuration, it often means |
| 20718 | that a session has been aborted on timeout. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20719 | |
| 20720 | Most common cases : |
| 20721 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20722 | - If "Th" or "Ti" are close to 3000, a packet has probably been lost between |
| 20723 | the client and the proxy. This is very rare on local networks but might |
| 20724 | happen when clients are on far remote networks and send large requests. It |
| 20725 | may happen that values larger than usual appear here without any network |
| 20726 | cause. Sometimes, during an attack or just after a resource starvation has |
| 20727 | ended, haproxy may accept thousands of connections in a few milliseconds. |
| 20728 | The time spent accepting these connections will inevitably slightly delay |
| 20729 | processing of other connections, and it can happen that request times in the |
| 20730 | order of a few tens of milliseconds are measured after a few thousands of |
| 20731 | new connections have been accepted at once. Using one of the keep-alive |
| 20732 | modes may display larger idle times since "Ti" measures the time spent |
Patrick Mezard | 105faca | 2010-06-12 17:02:46 +0200 | [diff] [blame] | 20733 | waiting for additional requests. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20734 | |
| 20735 | - If "Tc" is close to 3000, a packet has probably been lost between the |
| 20736 | server and the proxy during the server connection phase. This value should |
| 20737 | always be very low, such as 1 ms on local networks and less than a few tens |
| 20738 | of ms on remote networks. |
| 20739 | |
Willy Tarreau | 55165fe | 2009-05-10 12:02:55 +0200 | [diff] [blame] | 20740 | - If "Tr" is nearly always lower than 3000 except some rare values which seem |
| 20741 | to be the average majored by 3000, there are probably some packets lost |
| 20742 | between the proxy and the server. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20743 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20744 | - If "Ta" is large even for small byte counts, it generally is because |
| 20745 | neither the client nor the server decides to close the connection while |
| 20746 | haproxy is running in tunnel mode and both have agreed on a keep-alive |
| 20747 | connection mode. In order to solve this issue, it will be needed to specify |
| 20748 | one of the HTTP options to manipulate keep-alive or close options on either |
| 20749 | the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is |
| 20750 | important when connection regulation is used with the "maxconn" option on |
| 20751 | the servers, since no new connection will be sent to the server until |
| 20752 | another one is released. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20753 | |
| 20754 | Other noticeable HTTP log cases ('xx' means any value to be ignored) : |
| 20755 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20756 | TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20757 | was emitted before the data phase. All the timers are valid |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20758 | except "Ta" which is shorter than reality. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20759 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20760 | -1/xx/xx/xx/Ta The client was not able to send a complete request in time |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20761 | or it aborted too early. Check the session termination flags |
| 20762 | then "timeout http-request" and "timeout client" settings. |
| 20763 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20764 | TR/-1/xx/xx/Ta It was not possible to process the request, maybe because |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20765 | servers were out of order, because the request was invalid |
| 20766 | or forbidden by ACL rules. Check the session termination |
| 20767 | flags. |
| 20768 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20769 | TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it |
| 20770 | actively refused it or it timed out after Ta-(TR+Tw) ms. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20771 | Check the session termination flags, then check the |
| 20772 | "timeout connect" setting. Note that the tarpit action might |
| 20773 | return similar-looking patterns, with "Tw" equal to the time |
| 20774 | the client connection was maintained open. |
| 20775 | |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20776 | TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 20777 | a complete response in time, or it closed its connection |
Thierry FOURNIER / OZON.IO | 4cac359 | 2016-07-28 17:19:45 +0200 | [diff] [blame] | 20778 | unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20779 | termination flags, then check the "timeout server" setting. |
| 20780 | |
| 20781 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 20782 | 8.5. Session state at disconnection |
| 20783 | ----------------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20784 | |
| 20785 | TCP and HTTP logs provide a session termination indicator in the |
| 20786 | "termination_state" field, just before the number of active connections. It is |
| 20787 | 2-characters long in TCP mode, and is extended to 4 characters in HTTP mode, |
| 20788 | each of which has a special meaning : |
| 20789 | |
| 20790 | - On the first character, a code reporting the first event which caused the |
| 20791 | session to terminate : |
| 20792 | |
| 20793 | C : the TCP session was unexpectedly aborted by the client. |
| 20794 | |
| 20795 | S : the TCP session was unexpectedly aborted by the server, or the |
| 20796 | server explicitly refused it. |
| 20797 | |
| 20798 | P : the session was prematurely aborted by the proxy, because of a |
| 20799 | connection limit enforcement, because a DENY filter was matched, |
| 20800 | because of a security check which detected and blocked a dangerous |
| 20801 | error in server response which might have caused information leak |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20802 | (e.g. cacheable cookie). |
Willy Tarreau | 570f221 | 2013-06-10 16:42:09 +0200 | [diff] [blame] | 20803 | |
| 20804 | L : the session was locally processed by haproxy and was not passed to |
| 20805 | a server. This is what happens for stats and redirects. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20806 | |
| 20807 | R : a resource on the proxy has been exhausted (memory, sockets, source |
| 20808 | ports, ...). Usually, this appears during the connection phase, and |
| 20809 | system logs should contain a copy of the precise error. If this |
| 20810 | happens, it must be considered as a very serious anomaly which |
| 20811 | should be fixed as soon as possible by any means. |
| 20812 | |
| 20813 | I : an internal error was identified by the proxy during a self-check. |
| 20814 | This should NEVER happen, and you are encouraged to report any log |
| 20815 | containing this, because this would almost certainly be a bug. It |
| 20816 | would be wise to preventively restart the process after such an |
| 20817 | event too, in case it would be caused by memory corruption. |
| 20818 | |
Simon Horman | 752dc4a | 2011-06-21 14:34:59 +0900 | [diff] [blame] | 20819 | D : the session was killed by haproxy because the server was detected |
| 20820 | as down and was configured to kill all connections when going down. |
| 20821 | |
Justin Karneges | eb2c24a | 2012-05-24 15:28:52 -0700 | [diff] [blame] | 20822 | U : the session was killed by haproxy on this backup server because an |
| 20823 | active server was detected as up and was configured to kill all |
| 20824 | backup connections when going up. |
| 20825 | |
Willy Tarreau | a2a64e9 | 2011-09-07 23:01:56 +0200 | [diff] [blame] | 20826 | K : the session was actively killed by an admin operating on haproxy. |
| 20827 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20828 | c : the client-side timeout expired while waiting for the client to |
| 20829 | send or receive data. |
| 20830 | |
| 20831 | s : the server-side timeout expired while waiting for the server to |
| 20832 | send or receive data. |
| 20833 | |
| 20834 | - : normal session completion, both the client and the server closed |
| 20835 | with nothing left in the buffers. |
| 20836 | |
| 20837 | - on the second character, the TCP or HTTP session state when it was closed : |
| 20838 | |
Willy Tarreau | f7b30a9 | 2010-12-06 22:59:17 +0100 | [diff] [blame] | 20839 | 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] | 20840 | (HTTP mode only). Nothing was sent to any server. |
| 20841 | |
| 20842 | Q : the proxy was waiting in the QUEUE for a connection slot. This can |
| 20843 | only happen when servers have a 'maxconn' parameter set. It can |
| 20844 | also happen in the global queue after a redispatch consecutive to |
| 20845 | a failed attempt to connect to a dying server. If no redispatch is |
| 20846 | reported, then no connection attempt was made to any server. |
| 20847 | |
| 20848 | C : the proxy was waiting for the CONNECTION to establish on the |
| 20849 | server. The server might at most have noticed a connection attempt. |
| 20850 | |
| 20851 | H : the proxy was waiting for complete, valid response HEADERS from the |
| 20852 | server (HTTP only). |
| 20853 | |
| 20854 | D : the session was in the DATA phase. |
| 20855 | |
| 20856 | L : the proxy was still transmitting LAST data to the client while the |
| 20857 | server had already finished. This one is very rare as it can only |
| 20858 | happen when the client dies while receiving the last packets. |
| 20859 | |
| 20860 | T : the request was tarpitted. It has been held open with the client |
| 20861 | during the whole "timeout tarpit" duration or until the client |
| 20862 | closed, both of which will be reported in the "Tw" timer. |
| 20863 | |
| 20864 | - : normal session completion after end of data transfer. |
| 20865 | |
| 20866 | - the third character tells whether the persistence cookie was provided by |
| 20867 | the client (only in HTTP mode) : |
| 20868 | |
| 20869 | N : the client provided NO cookie. This is usually the case for new |
| 20870 | visitors, so counting the number of occurrences of this flag in the |
| 20871 | logs generally indicate a valid trend for the site frequentation. |
| 20872 | |
| 20873 | I : the client provided an INVALID cookie matching no known server. |
| 20874 | This might be caused by a recent configuration change, mixed |
Cyril Bonté | a8e7bbc | 2010-04-25 22:29:29 +0200 | [diff] [blame] | 20875 | cookies between HTTP/HTTPS sites, persistence conditionally |
| 20876 | ignored, or an attack. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20877 | |
| 20878 | D : the client provided a cookie designating a server which was DOWN, |
| 20879 | so either "option persist" was used and the client was sent to |
| 20880 | this server, or it was not set and the client was redispatched to |
| 20881 | another server. |
| 20882 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 20883 | 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] | 20884 | server. |
| 20885 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 20886 | E : the client provided a valid cookie, but with a last date which was |
| 20887 | older than what is allowed by the "maxidle" cookie parameter, so |
| 20888 | the cookie is consider EXPIRED and is ignored. The request will be |
| 20889 | redispatched just as if there was no cookie. |
| 20890 | |
| 20891 | O : the client provided a valid cookie, but with a first date which was |
| 20892 | older than what is allowed by the "maxlife" cookie parameter, so |
| 20893 | the cookie is consider too OLD and is ignored. The request will be |
| 20894 | redispatched just as if there was no cookie. |
| 20895 | |
Willy Tarreau | c89ccb6 | 2012-04-05 21:18:22 +0200 | [diff] [blame] | 20896 | U : a cookie was present but was not used to select the server because |
| 20897 | some other server selection mechanism was used instead (typically a |
| 20898 | "use-server" rule). |
| 20899 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20900 | - : does not apply (no cookie set in configuration). |
| 20901 | |
| 20902 | - the last character reports what operations were performed on the persistence |
| 20903 | cookie returned by the server (only in HTTP mode) : |
| 20904 | |
| 20905 | N : NO cookie was provided by the server, and none was inserted either. |
| 20906 | |
| 20907 | I : no cookie was provided by the server, and the proxy INSERTED one. |
| 20908 | Note that in "cookie insert" mode, if the server provides a cookie, |
| 20909 | it will still be overwritten and reported as "I" here. |
| 20910 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 20911 | U : the proxy UPDATED the last date in the cookie that was presented by |
| 20912 | the client. This can only happen in insert mode with "maxidle". It |
Jarno Huuskonen | 0e82b92 | 2014-04-12 18:22:19 +0300 | [diff] [blame] | 20913 | happens every time there is activity at a different date than the |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 20914 | date indicated in the cookie. If any other change happens, such as |
| 20915 | a redispatch, then the cookie will be marked as inserted instead. |
| 20916 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20917 | P : a cookie was PROVIDED by the server and transmitted as-is. |
| 20918 | |
| 20919 | R : the cookie provided by the server was REWRITTEN by the proxy, which |
| 20920 | happens in "cookie rewrite" or "cookie prefix" modes. |
| 20921 | |
| 20922 | D : the cookie provided by the server was DELETED by the proxy. |
| 20923 | |
| 20924 | - : does not apply (no cookie set in configuration). |
| 20925 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 20926 | The combination of the two first flags gives a lot of information about what |
| 20927 | 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] | 20928 | helpful to detect server saturation, network troubles, local system resource |
| 20929 | starvation, attacks, etc... |
| 20930 | |
| 20931 | The most common termination flags combinations are indicated below. They are |
| 20932 | alphabetically sorted, with the lowercase set just after the upper case for |
| 20933 | easier finding and understanding. |
| 20934 | |
| 20935 | Flags Reason |
| 20936 | |
| 20937 | -- Normal termination. |
| 20938 | |
| 20939 | CC The client aborted before the connection could be established to the |
| 20940 | server. This can happen when haproxy tries to connect to a recently |
| 20941 | dead (or unchecked) server, and the client aborts while haproxy is |
| 20942 | waiting for the server to respond or for "timeout connect" to expire. |
| 20943 | |
| 20944 | CD The client unexpectedly aborted during data transfer. This can be |
| 20945 | caused by a browser crash, by an intermediate equipment between the |
| 20946 | client and haproxy which decided to actively break the connection, |
| 20947 | by network routing issues between the client and haproxy, or by a |
| 20948 | keep-alive session between the server and the client terminated first |
| 20949 | by the client. |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 20950 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20951 | cD The client did not send nor acknowledge any data for as long as the |
| 20952 | "timeout client" delay. This is often caused by network failures on |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 20953 | the client side, or the client simply leaving the net uncleanly. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20954 | |
| 20955 | CH The client aborted while waiting for the server to start responding. |
| 20956 | It might be the server taking too long to respond or the client |
| 20957 | clicking the 'Stop' button too fast. |
| 20958 | |
| 20959 | cH The "timeout client" stroke while waiting for client data during a |
| 20960 | POST request. This is sometimes caused by too large TCP MSS values |
| 20961 | for PPPoE networks which cannot transport full-sized packets. It can |
| 20962 | also happen when client timeout is smaller than server timeout and |
| 20963 | the server takes too long to respond. |
| 20964 | |
| 20965 | CQ The client aborted while its session was queued, waiting for a server |
| 20966 | with enough empty slots to accept it. It might be that either all the |
| 20967 | servers were saturated or that the assigned server was taking too |
| 20968 | long a time to respond. |
| 20969 | |
| 20970 | CR The client aborted before sending a full HTTP request. Most likely |
| 20971 | the request was typed by hand using a telnet client, and aborted |
| 20972 | too early. The HTTP status code is likely a 400 here. Sometimes this |
| 20973 | might also be caused by an IDS killing the connection between haproxy |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 20974 | and the client. "option http-ignore-probes" can be used to ignore |
| 20975 | connections without any data transfer. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20976 | |
| 20977 | cR The "timeout http-request" stroke before the client sent a full HTTP |
| 20978 | request. This is sometimes caused by too large TCP MSS values on the |
| 20979 | client side for PPPoE networks which cannot transport full-sized |
| 20980 | packets, or by clients sending requests by hand and not typing fast |
| 20981 | enough, or forgetting to enter the empty line at the end of the |
Willy Tarreau | 2705a61 | 2014-05-23 17:38:34 +0200 | [diff] [blame] | 20982 | request. The HTTP status code is likely a 408 here. Note: recently, |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 20983 | some browsers started to implement a "pre-connect" feature consisting |
| 20984 | in speculatively connecting to some recently visited web sites just |
| 20985 | in case the user would like to visit them. This results in many |
| 20986 | connections being established to web sites, which end up in 408 |
| 20987 | Request Timeout if the timeout strikes first, or 400 Bad Request when |
| 20988 | the browser decides to close them first. These ones pollute the log |
| 20989 | and feed the error counters. Some versions of some browsers have even |
| 20990 | been reported to display the error code. It is possible to work |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 20991 | around the undesirable effects of this behavior by adding "option |
Willy Tarreau | 0f228a0 | 2015-05-01 15:37:53 +0200 | [diff] [blame] | 20992 | http-ignore-probes" in the frontend, resulting in connections with |
| 20993 | zero data transfer to be totally ignored. This will definitely hide |
| 20994 | the errors of people experiencing connectivity issues though. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 20995 | |
| 20996 | CT The client aborted while its session was tarpitted. It is important to |
| 20997 | 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] | 20998 | wrong tarpit rules have been written. If a lot of them happen, it |
| 20999 | might make sense to lower the "timeout tarpit" value to something |
| 21000 | closer to the average reported "Tw" timer, in order not to consume |
| 21001 | resources for just a few attackers. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21002 | |
Willy Tarreau | 570f221 | 2013-06-10 16:42:09 +0200 | [diff] [blame] | 21003 | LR The request was intercepted and locally handled by haproxy. Generally |
| 21004 | it means that this was a redirect or a stats request. |
| 21005 | |
Krzysztof Piotr Oledzki | f864533 | 2009-12-13 21:55:50 +0100 | [diff] [blame] | 21006 | SC The server or an equipment between it and haproxy explicitly refused |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21007 | the TCP connection (the proxy received a TCP RST or an ICMP message |
| 21008 | in return). Under some circumstances, it can also be the network |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21009 | stack telling the proxy that the server is unreachable (e.g. no route, |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21010 | or no ARP response on local network). When this happens in HTTP mode, |
| 21011 | the status code is likely a 502 or 503 here. |
| 21012 | |
| 21013 | sC The "timeout connect" stroke before a connection to the server could |
| 21014 | complete. When this happens in HTTP mode, the status code is likely a |
| 21015 | 503 or 504 here. |
| 21016 | |
| 21017 | SD The connection to the server died with an error during the data |
| 21018 | transfer. This usually means that haproxy has received an RST from |
| 21019 | the server or an ICMP message from an intermediate equipment while |
| 21020 | exchanging data with the server. This can be caused by a server crash |
| 21021 | or by a network issue on an intermediate equipment. |
| 21022 | |
| 21023 | sD The server did not send nor acknowledge any data for as long as the |
| 21024 | "timeout server" setting during the data phase. This is often caused |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21025 | by too short timeouts on L4 equipment before the server (firewalls, |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21026 | load-balancers, ...), as well as keep-alive sessions maintained |
| 21027 | between the client and the server expiring first on haproxy. |
| 21028 | |
| 21029 | SH The server aborted before sending its full HTTP response headers, or |
| 21030 | it crashed while processing the request. Since a server aborting at |
| 21031 | this moment is very rare, it would be wise to inspect its logs to |
| 21032 | control whether it crashed and why. The logged request may indicate a |
| 21033 | small set of faulty requests, demonstrating bugs in the application. |
| 21034 | Sometimes this might also be caused by an IDS killing the connection |
| 21035 | between haproxy and the server. |
| 21036 | |
| 21037 | sH The "timeout server" stroke before the server could return its |
| 21038 | response headers. This is the most common anomaly, indicating too |
| 21039 | long transactions, probably caused by server or database saturation. |
| 21040 | The immediate workaround consists in increasing the "timeout server" |
| 21041 | setting, but it is important to keep in mind that the user experience |
| 21042 | will suffer from these long response times. The only long term |
| 21043 | solution is to fix the application. |
| 21044 | |
| 21045 | sQ The session spent too much time in queue and has been expired. See |
| 21046 | the "timeout queue" and "timeout connect" settings to find out how to |
| 21047 | fix this if it happens too often. If it often happens massively in |
| 21048 | short periods, it may indicate general problems on the affected |
| 21049 | servers due to I/O or database congestion, or saturation caused by |
| 21050 | external attacks. |
| 21051 | |
| 21052 | PC The proxy refused to establish a connection to the server because the |
Thayne McCombs | cdbcca9 | 2021-01-07 21:24:41 -0700 | [diff] [blame] | 21053 | process's socket limit has been reached while attempting to connect. |
Cyril Bonté | dc4d903 | 2012-04-08 21:57:39 +0200 | [diff] [blame] | 21054 | The global "maxconn" parameter may be increased in the configuration |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21055 | so that it does not happen anymore. This status is very rare and |
| 21056 | might happen when the global "ulimit-n" parameter is forced by hand. |
| 21057 | |
Willy Tarreau | ed2fd2d | 2010-12-29 11:23:27 +0100 | [diff] [blame] | 21058 | PD The proxy blocked an incorrectly formatted chunked encoded message in |
| 21059 | a request or a response, after the server has emitted its headers. In |
| 21060 | most cases, this will indicate an invalid message from the server to |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21061 | the client. HAProxy supports chunk sizes of up to 2GB - 1 (2147483647 |
Willy Tarreau | f3a3e13 | 2013-08-31 08:16:26 +0200 | [diff] [blame] | 21062 | bytes). Any larger size will be considered as an error. |
Willy Tarreau | ed2fd2d | 2010-12-29 11:23:27 +0100 | [diff] [blame] | 21063 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21064 | PH The proxy blocked the server's response, because it was invalid, |
| 21065 | incomplete, dangerous (cache control), or matched a security filter. |
| 21066 | In any case, an HTTP 502 error is sent to the client. One possible |
| 21067 | 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] | 21068 | containing unauthorized characters. It is also possible but quite |
| 21069 | rare, that the proxy blocked a chunked-encoding request from the |
| 21070 | client due to an invalid syntax, before the server responded. In this |
| 21071 | case, an HTTP 400 error is sent to the client and reported in the |
| 21072 | logs. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21073 | |
| 21074 | PR The proxy blocked the client's HTTP request, either because of an |
| 21075 | invalid HTTP syntax, in which case it returned an HTTP 400 error to |
| 21076 | the client, or because a deny filter matched, in which case it |
| 21077 | returned an HTTP 403 error. |
| 21078 | |
| 21079 | PT The proxy blocked the client's request and has tarpitted its |
| 21080 | connection before returning it a 500 server error. Nothing was sent |
| 21081 | to the server. The connection was maintained open for as long as |
| 21082 | reported by the "Tw" timer field. |
| 21083 | |
| 21084 | RC A local resource has been exhausted (memory, sockets, source ports) |
| 21085 | preventing the connection to the server from establishing. The error |
| 21086 | logs will tell precisely what was missing. This is very rare and can |
| 21087 | only be solved by proper system tuning. |
| 21088 | |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 21089 | The combination of the two last flags gives a lot of information about how |
| 21090 | persistence was handled by the client, the server and by haproxy. This is very |
| 21091 | important to troubleshoot disconnections, when users complain they have to |
| 21092 | re-authenticate. The commonly encountered flags are : |
| 21093 | |
| 21094 | -- Persistence cookie is not enabled. |
| 21095 | |
| 21096 | NN No cookie was provided by the client, none was inserted in the |
| 21097 | response. For instance, this can be in insert mode with "postonly" |
| 21098 | set on a GET request. |
| 21099 | |
| 21100 | II A cookie designating an invalid server was provided by the client, |
| 21101 | a valid one was inserted in the response. This typically happens when |
Jamie Gloudon | aaa2100 | 2012-08-25 00:18:33 -0400 | [diff] [blame] | 21102 | a "server" entry is removed from the configuration, since its cookie |
Willy Tarreau | 996a92c | 2010-10-13 19:30:47 +0200 | [diff] [blame] | 21103 | value can be presented by a client when no other server knows it. |
| 21104 | |
| 21105 | NI No cookie was provided by the client, one was inserted in the |
| 21106 | response. This typically happens for first requests from every user |
| 21107 | in "insert" mode, which makes it an easy way to count real users. |
| 21108 | |
| 21109 | VN A cookie was provided by the client, none was inserted in the |
| 21110 | response. This happens for most responses for which the client has |
| 21111 | already got a cookie. |
| 21112 | |
| 21113 | VU A cookie was provided by the client, with a last visit date which is |
| 21114 | not completely up-to-date, so an updated cookie was provided in |
| 21115 | response. This can also happen if there was no date at all, or if |
| 21116 | there was a date but the "maxidle" parameter was not set, so that the |
| 21117 | cookie can be switched to unlimited time. |
| 21118 | |
| 21119 | EI A cookie was provided by the client, with a last visit date which is |
| 21120 | too old for the "maxidle" parameter, so the cookie was ignored and a |
| 21121 | new cookie was inserted in the response. |
| 21122 | |
| 21123 | OI A cookie was provided by the client, with a first visit date which is |
| 21124 | too old for the "maxlife" parameter, so the cookie was ignored and a |
| 21125 | new cookie was inserted in the response. |
| 21126 | |
| 21127 | DI The server designated by the cookie was down, a new server was |
| 21128 | selected and a new cookie was emitted in the response. |
| 21129 | |
| 21130 | VI The server designated by the cookie was not marked dead but could not |
| 21131 | be reached. A redispatch happened and selected another one, which was |
| 21132 | then advertised in the response. |
| 21133 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21134 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21135 | 8.6. Non-printable characters |
| 21136 | ----------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21137 | |
| 21138 | In order not to cause trouble to log analysis tools or terminals during log |
| 21139 | consulting, non-printable characters are not sent as-is into log files, but are |
| 21140 | converted to the two-digits hexadecimal representation of their ASCII code, |
| 21141 | prefixed by the character '#'. The only characters that can be logged without |
| 21142 | being escaped are comprised between 32 and 126 (inclusive). Obviously, the |
| 21143 | escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It |
| 21144 | is the same for the character '"' which becomes "#22", as well as '{', '|' and |
| 21145 | '}' when logging headers. |
| 21146 | |
| 21147 | Note that the space character (' ') is not encoded in headers, which can cause |
| 21148 | issues for tools relying on space count to locate fields. A typical header |
| 21149 | containing spaces is "User-Agent". |
| 21150 | |
| 21151 | Last, it has been observed that some syslog daemons such as syslog-ng escape |
| 21152 | the quote ('"') with a backslash ('\'). The reverse operation can safely be |
| 21153 | performed since no quote may appear anywhere else in the logs. |
| 21154 | |
| 21155 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21156 | 8.7. Capturing HTTP cookies |
| 21157 | --------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21158 | |
| 21159 | Cookie capture simplifies the tracking a complete user session. This can be |
| 21160 | achieved using the "capture cookie" statement in the frontend. Please refer to |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21161 | 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] | 21162 | cookie will simultaneously be checked in the request ("Cookie:" header) and in |
| 21163 | the response ("Set-Cookie:" header). The respective values will be reported in |
| 21164 | the HTTP logs at the "captured_request_cookie" and "captured_response_cookie" |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21165 | 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] | 21166 | not seen, a dash ('-') replaces the value. This way, it's easy to detect when a |
| 21167 | user switches to a new session for example, because the server will reassign it |
| 21168 | a new cookie. It is also possible to detect if a server unexpectedly sets a |
| 21169 | wrong cookie to a client, leading to session crossing. |
| 21170 | |
| 21171 | Examples : |
| 21172 | # capture the first cookie whose name starts with "ASPSESSION" |
| 21173 | capture cookie ASPSESSION len 32 |
| 21174 | |
| 21175 | # capture the first cookie whose name is exactly "vgnvisitor" |
| 21176 | capture cookie vgnvisitor= len 32 |
| 21177 | |
| 21178 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21179 | 8.8. Capturing HTTP headers |
| 21180 | --------------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21181 | |
| 21182 | Header captures are useful to track unique request identifiers set by an upper |
| 21183 | proxy, virtual host names, user-agents, POST content-length, referrers, etc. In |
| 21184 | the response, one can search for information about the response length, how the |
| 21185 | server asked the cache to behave, or an object location during a redirection. |
| 21186 | |
| 21187 | Header captures are performed using the "capture request header" and "capture |
| 21188 | response header" statements in the frontend. Please consult their definition in |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21189 | section 4.2 for more details. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21190 | |
| 21191 | 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] | 21192 | time. Non-existent headers are logged as empty strings, and if one header |
| 21193 | 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] | 21194 | are grouped within braces '{' and '}' in the same order as they were declared, |
| 21195 | and delimited with a vertical bar '|' without any space. Response headers |
| 21196 | follow the same representation, but are displayed after a space following the |
| 21197 | request headers block. These blocks are displayed just before the HTTP request |
| 21198 | in the logs. |
| 21199 | |
Willy Tarreau | d9ed3d2 | 2014-06-13 12:23:06 +0200 | [diff] [blame] | 21200 | As a special case, it is possible to specify an HTTP header capture in a TCP |
| 21201 | frontend. The purpose is to enable logging of headers which will be parsed in |
| 21202 | an HTTP backend if the request is then switched to this HTTP backend. |
| 21203 | |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21204 | Example : |
| 21205 | # This instance chains to the outgoing proxy |
| 21206 | listen proxy-out |
| 21207 | mode http |
| 21208 | option httplog |
| 21209 | option logasap |
| 21210 | log global |
| 21211 | server cache1 192.168.1.1:3128 |
| 21212 | |
| 21213 | # log the name of the virtual server |
| 21214 | capture request header Host len 20 |
| 21215 | |
| 21216 | # log the amount of data uploaded during a POST |
| 21217 | capture request header Content-Length len 10 |
| 21218 | |
| 21219 | # log the beginning of the referrer |
| 21220 | capture request header Referer len 20 |
| 21221 | |
| 21222 | # server name (useful for outgoing proxies only) |
| 21223 | capture response header Server len 20 |
| 21224 | |
| 21225 | # logging the content-length is useful with "option logasap" |
| 21226 | capture response header Content-Length len 10 |
| 21227 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21228 | # log the expected cache behavior on the response |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21229 | capture response header Cache-Control len 8 |
| 21230 | |
| 21231 | # the Via header will report the next proxy's name |
| 21232 | capture response header Via len 20 |
| 21233 | |
| 21234 | # log the URL location during a redirection |
| 21235 | capture response header Location len 20 |
| 21236 | |
| 21237 | >>> Aug 9 20:26:09 localhost \ |
| 21238 | haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \ |
| 21239 | proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \ |
| 21240 | {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \ |
| 21241 | "GET http://fr.adserver.yahoo.com/" |
| 21242 | |
| 21243 | >>> Aug 9 20:30:46 localhost \ |
| 21244 | haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \ |
| 21245 | proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \ |
| 21246 | {w.ods.org||} {Formilux/0.1.8|3495|||} \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 21247 | "GET http://trafic.1wt.eu/ HTTP/1.1" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21248 | |
| 21249 | >>> Aug 9 20:30:46 localhost \ |
| 21250 | haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \ |
| 21251 | proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \ |
| 21252 | {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \ |
| 21253 | {Apache|230|||http://www.sytadin.} \ |
Willy Tarreau | d72758d | 2010-01-12 10:42:19 +0100 | [diff] [blame] | 21254 | "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21255 | |
| 21256 | |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21257 | 8.9. Examples of logs |
| 21258 | --------------------- |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21259 | |
| 21260 | These are real-world examples of logs accompanied with an explanation. Some of |
| 21261 | them have been made up by hand. The syslog part has been removed for better |
| 21262 | reading. Their sole purpose is to explain how to decipher them. |
| 21263 | |
| 21264 | >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \ |
| 21265 | px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \ |
| 21266 | "HEAD / HTTP/1.0" |
| 21267 | |
| 21268 | => long request (6.5s) entered by hand through 'telnet'. The server replied |
| 21269 | in 147 ms, and the session ended normally ('----') |
| 21270 | |
| 21271 | >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \ |
| 21272 | px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \ |
| 21273 | 0/9 "HEAD / HTTP/1.0" |
| 21274 | |
| 21275 | => Idem, but the request was queued in the global queue behind 9 other |
| 21276 | requests, and waited there for 1230 ms. |
| 21277 | |
| 21278 | >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \ |
| 21279 | px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \ |
| 21280 | "GET /image.iso HTTP/1.0" |
| 21281 | |
| 21282 | => 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] | 21283 | the log was produced just before transferring data. The server replied in |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21284 | 14 ms, 243 bytes of headers were sent to the client, and total time from |
| 21285 | accept to first data byte is 30 ms. |
| 21286 | |
| 21287 | >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \ |
| 21288 | px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \ |
| 21289 | "GET /cgi-bin/bug.cgi? HTTP/1.0" |
| 21290 | |
Christopher Faulet | 87f1f3d | 2019-07-18 14:51:20 +0200 | [diff] [blame] | 21291 | => the proxy blocked a server response either because of an "http-response |
| 21292 | deny" rule, or because the response was improperly formatted and not |
| 21293 | HTTP-compliant, or because it blocked sensitive information which risked |
| 21294 | being cached. In this case, the response is replaced with a "502 bad |
| 21295 | gateway". The flags ("PH--") tell us that it was haproxy who decided to |
| 21296 | return the 502 and not the server. |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21297 | |
| 21298 | >>> 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] | 21299 | 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] | 21300 | |
| 21301 | => the client never completed its request and aborted itself ("C---") after |
| 21302 | 8.5s, while the proxy was waiting for the request headers ("-R--"). |
| 21303 | Nothing was sent to any server. |
| 21304 | |
| 21305 | >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \ |
| 21306 | px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 "" |
| 21307 | |
| 21308 | => The client never completed its request, which was aborted by the |
| 21309 | time-out ("c---") after 50s, while the proxy was waiting for the request |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21310 | headers ("-R--"). Nothing was sent to any server, but the proxy could |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21311 | send a 408 return code to the client. |
| 21312 | |
| 21313 | >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \ |
| 21314 | px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0 |
| 21315 | |
| 21316 | => This log was produced with "option tcplog". The client timed out after |
| 21317 | 5 seconds ("c----"). |
| 21318 | |
| 21319 | >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \ |
| 21320 | 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] | 21321 | 0/0 "HEAD / HTTP/1.0" |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21322 | |
| 21323 | => The request took 3s to complete (probably a network problem), and the |
Willy Tarreau | c57f0e2 | 2009-05-10 13:12:33 +0200 | [diff] [blame] | 21324 | connection to the server failed ('SC--') after 4 attempts of 2 seconds |
Willy Tarreau | cc6c891 | 2009-02-22 10:53:55 +0100 | [diff] [blame] | 21325 | (config says 'retries 3'), and no redispatch (otherwise we would have |
| 21326 | seen "/+3"). Status code 503 was returned to the client. There were 115 |
| 21327 | connections on this server, 202 connections on this proxy, and 205 on |
| 21328 | the global process. It is possible that the server refused the |
| 21329 | connection because of too many already established. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 21330 | |
Willy Tarreau | 52b2d22 | 2011-09-07 23:48:48 +0200 | [diff] [blame] | 21331 | |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21332 | 9. Supported filters |
| 21333 | -------------------- |
| 21334 | |
| 21335 | Here are listed officially supported filters with the list of parameters they |
| 21336 | accept. Depending on compile options, some of these filters might be |
| 21337 | unavailable. The list of available filters is reported in haproxy -vv. |
| 21338 | |
| 21339 | See also : "filter" |
| 21340 | |
| 21341 | 9.1. Trace |
| 21342 | ---------- |
| 21343 | |
Christopher Faulet | c41d8bd | 2020-11-17 10:43:26 +0100 | [diff] [blame] | 21344 | filter trace [name <name>] [random-forwarding] [hexdump] |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21345 | |
| 21346 | Arguments: |
| 21347 | <name> is an arbitrary name that will be reported in |
| 21348 | messages. If no name is provided, "TRACE" is used. |
| 21349 | |
Christopher Faulet | 96a577a | 2020-11-17 10:45:05 +0100 | [diff] [blame] | 21350 | <quiet> inhibits trace messages. |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21351 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21352 | <random-forwarding> enables the random forwarding of parsed data. By |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21353 | default, this filter forwards all previously parsed |
| 21354 | data. With this parameter, it only forwards a random |
| 21355 | amount of the parsed data. |
| 21356 | |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21357 | <hexdump> dumps all forwarded data to the server and the client. |
Christopher Faulet | 31bfe1f | 2016-12-09 17:42:38 +0100 | [diff] [blame] | 21358 | |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21359 | This filter can be used as a base to develop new filters. It defines all |
| 21360 | callbacks and print a message on the standard error stream (stderr) with useful |
| 21361 | information for all of them. It may be useful to debug the activity of other |
| 21362 | filters or, quite simply, HAProxy's activity. |
| 21363 | |
| 21364 | Using <random-parsing> and/or <random-forwarding> parameters is a good way to |
| 21365 | tests the behavior of a filter that parses data exchanged between a client and |
| 21366 | a server by adding some latencies in the processing. |
| 21367 | |
| 21368 | |
| 21369 | 9.2. HTTP compression |
| 21370 | --------------------- |
| 21371 | |
| 21372 | filter compression |
| 21373 | |
| 21374 | The HTTP compression has been moved in a filter in HAProxy 1.7. "compression" |
| 21375 | keyword must still be used to enable and configure the HTTP compression. And |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21376 | when no other filter is used, it is enough. When used with the cache or the |
| 21377 | fcgi-app enabled, it is also enough. In this case, the compression is always |
| 21378 | done after the response is stored in the cache. But it is mandatory to |
| 21379 | explicitly use a filter line to enable the HTTP compression when at least one |
| 21380 | filter other than the cache or the fcgi-app is used for the same |
| 21381 | listener/frontend/backend. This is important to know the filters evaluation |
| 21382 | order. |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21383 | |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21384 | See also : "compression", section 9.4 about the cache filter and section 9.5 |
| 21385 | about the fcgi-app filter. |
Christopher Faulet | c3fe533 | 2016-04-07 15:30:10 +0200 | [diff] [blame] | 21386 | |
| 21387 | |
Christopher Faulet | f7e4e7e | 2016-10-27 22:29:49 +0200 | [diff] [blame] | 21388 | 9.3. Stream Processing Offload Engine (SPOE) |
| 21389 | -------------------------------------------- |
| 21390 | |
| 21391 | filter spoe [engine <name>] config <file> |
| 21392 | |
| 21393 | Arguments : |
| 21394 | |
| 21395 | <name> is the engine name that will be used to find the right scope in |
| 21396 | the configuration file. If not provided, all the file will be |
| 21397 | parsed. |
| 21398 | |
| 21399 | <file> is the path of the engine configuration file. This file can |
| 21400 | contain configuration of several engines. In this case, each |
| 21401 | part must be placed in its own scope. |
| 21402 | |
| 21403 | The Stream Processing Offload Engine (SPOE) is a filter communicating with |
| 21404 | external components. It allows the offload of some specifics processing on the |
Davor Ocelic | e9ed281 | 2017-12-25 17:49:28 +0100 | [diff] [blame] | 21405 | streams in tiered applications. These external components and information |
Christopher Faulet | f7e4e7e | 2016-10-27 22:29:49 +0200 | [diff] [blame] | 21406 | exchanged with them are configured in dedicated files, for the main part. It |
| 21407 | also requires dedicated backends, defined in HAProxy configuration. |
| 21408 | |
| 21409 | SPOE communicates with external components using an in-house binary protocol, |
| 21410 | the Stream Processing Offload Protocol (SPOP). |
| 21411 | |
Tim Düsterhus | 4896c44 | 2016-11-29 02:15:19 +0100 | [diff] [blame] | 21412 | For all information about the SPOE configuration and the SPOP specification, see |
Christopher Faulet | f7e4e7e | 2016-10-27 22:29:49 +0200 | [diff] [blame] | 21413 | "doc/SPOE.txt". |
| 21414 | |
Christopher Faulet | 99a17a2 | 2018-12-11 09:18:27 +0100 | [diff] [blame] | 21415 | 9.4. Cache |
| 21416 | ---------- |
| 21417 | |
| 21418 | filter cache <name> |
| 21419 | |
| 21420 | Arguments : |
| 21421 | |
| 21422 | <name> is name of the cache section this filter will use. |
| 21423 | |
| 21424 | The cache uses a filter to store cacheable responses. The HTTP rules |
| 21425 | "cache-store" and "cache-use" must be used to define how and when to use a |
John Roesler | fb2fce1 | 2019-07-10 15:45:51 -0500 | [diff] [blame] | 21426 | cache. By default the corresponding filter is implicitly defined. And when no |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21427 | other filters than fcgi-app or compression are used, it is enough. In such |
| 21428 | case, the compression filter is always evaluated after the cache filter. But it |
| 21429 | is mandatory to explicitly use a filter line to use a cache when at least one |
| 21430 | filter other than the compression or the fcgi-app is used for the same |
Christopher Faulet | 27d93c3 | 2018-12-15 22:32:02 +0100 | [diff] [blame] | 21431 | listener/frontend/backend. This is important to know the filters evaluation |
| 21432 | order. |
Christopher Faulet | 99a17a2 | 2018-12-11 09:18:27 +0100 | [diff] [blame] | 21433 | |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21434 | See also : section 9.2 about the compression filter, section 9.5 about the |
| 21435 | fcgi-app filter and section 6 about cache. |
| 21436 | |
| 21437 | |
| 21438 | 9.5. Fcgi-app |
| 21439 | ------------- |
| 21440 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 21441 | filter fcgi-app <name> |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21442 | |
| 21443 | Arguments : |
| 21444 | |
| 21445 | <name> is name of the fcgi-app section this filter will use. |
| 21446 | |
| 21447 | The FastCGI application uses a filter to evaluate all custom parameters on the |
| 21448 | request path, and to process the headers on the response path. the <name> must |
| 21449 | reference an existing fcgi-app section. The directive "use-fcgi-app" should be |
| 21450 | used to define the application to use. By default the corresponding filter is |
| 21451 | implicitly defined. And when no other filters than cache or compression are |
| 21452 | used, it is enough. But it is mandatory to explicitly use a filter line to a |
| 21453 | fcgi-app when at least one filter other than the compression or the cache is |
| 21454 | used for the same backend. This is important to know the filters evaluation |
| 21455 | order. |
| 21456 | |
| 21457 | See also: "use-fcgi-app", section 9.2 about the compression filter, section 9.4 |
| 21458 | about the cache filter and section 10 about FastCGI application. |
| 21459 | |
| 21460 | |
Miroslav Zagorac | dc32cd9 | 2020-12-13 18:32:57 +0100 | [diff] [blame] | 21461 | 9.6. OpenTracing |
| 21462 | ---------------- |
| 21463 | |
| 21464 | The OpenTracing filter adds native support for using distributed tracing in |
| 21465 | HAProxy. This is enabled by sending an OpenTracing compliant request to one |
| 21466 | of the supported tracers such as Datadog, Jaeger, Lightstep and Zipkin tracers. |
| 21467 | Please note: tracers are not listed by any preference, but alphabetically. |
| 21468 | |
| 21469 | This feature is only enabled when haproxy was built with USE_OT=1. |
| 21470 | |
| 21471 | The OpenTracing filter activation is done explicitly by specifying it in the |
| 21472 | HAProxy configuration. If this is not done, the OpenTracing filter in no way |
| 21473 | participates in the work of HAProxy. |
| 21474 | |
| 21475 | filter opentracing [id <id>] config <file> |
| 21476 | |
| 21477 | Arguments : |
| 21478 | |
| 21479 | <id> is the OpenTracing filter id that will be used to find the |
| 21480 | right scope in the configuration file. If no filter id is |
| 21481 | specified, 'ot-filter' is used as default. If scope is not |
| 21482 | specified in the configuration file, it applies to all defined |
| 21483 | OpenTracing filters. |
| 21484 | |
| 21485 | <file> is the path of the OpenTracing configuration file. The same |
| 21486 | file can contain configurations for multiple OpenTracing |
| 21487 | filters simultaneously. In that case we do not need to define |
| 21488 | scope so the same configuration applies to all filters or each |
| 21489 | filter must have its own scope defined. |
| 21490 | |
| 21491 | More detailed documentation related to the operation, configuration and use |
Willy Tarreau | a63d1a0 | 2021-04-02 17:16:46 +0200 | [diff] [blame] | 21492 | of the filter can be found in the addons/ot directory. |
Miroslav Zagorac | dc32cd9 | 2020-12-13 18:32:57 +0100 | [diff] [blame] | 21493 | |
| 21494 | |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21495 | 10. FastCGI applications |
| 21496 | ------------------------- |
| 21497 | |
| 21498 | HAProxy is able to send HTTP requests to Responder FastCGI applications. This |
| 21499 | feature was added in HAProxy 2.1. To do so, servers must be configured to use |
| 21500 | the FastCGI protocol (using the keyword "proto fcgi" on the server line) and a |
| 21501 | FastCGI application must be configured and used by the backend managing these |
| 21502 | servers (using the keyword "use-fcgi-app" into the proxy section). Several |
| 21503 | FastCGI applications may be defined, but only one can be used at a time by a |
| 21504 | backend. |
| 21505 | |
| 21506 | HAProxy implements all features of the FastCGI specification for Responder |
| 21507 | application. Especially it is able to multiplex several requests on a simple |
| 21508 | connection. |
| 21509 | |
| 21510 | 10.1. Setup |
| 21511 | ----------- |
| 21512 | |
| 21513 | 10.1.1. Fcgi-app section |
| 21514 | -------------------------- |
| 21515 | |
| 21516 | fcgi-app <name> |
| 21517 | Declare a FastCGI application named <name>. To be valid, at least the |
| 21518 | document root must be defined. |
| 21519 | |
| 21520 | acl <aclname> <criterion> [flags] [operator] <value> ... |
| 21521 | Declare or complete an access list. |
| 21522 | |
| 21523 | See "acl" keyword in section 4.2 and section 7 about ACL usage for |
| 21524 | details. ACLs defined for a FastCGI application are private. They cannot be |
| 21525 | used by any other application or by any proxy. In the same way, ACLs defined |
| 21526 | in any other section are not usable by a FastCGI application. However, |
| 21527 | Pre-defined ACLs are available. |
| 21528 | |
| 21529 | docroot <path> |
| 21530 | Define the document root on the remote host. <path> will be used to build |
| 21531 | the default value of FastCGI parameters SCRIPT_FILENAME and |
| 21532 | PATH_TRANSLATED. It is a mandatory setting. |
| 21533 | |
| 21534 | index <script-name> |
| 21535 | Define the script name that will be appended after an URI that ends with a |
| 21536 | slash ("/") to set the default value of the FastCGI parameter SCRIPT_NAME. It |
| 21537 | is an optional setting. |
| 21538 | |
| 21539 | Example : |
| 21540 | index index.php |
| 21541 | |
| 21542 | log-stderr global |
| 21543 | log-stderr <address> [len <length>] [format <format>] |
Jan Wagner | 3e67860 | 2020-12-17 22:22:32 +0100 | [diff] [blame] | 21544 | [sample <ranges>:<sample_size>] <facility> [<level> [<minlevel>]] |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21545 | Enable logging of STDERR messages reported by the FastCGI application. |
| 21546 | |
| 21547 | See "log" keyword in section 4.2 for details. It is an optional setting. By |
| 21548 | default STDERR messages are ignored. |
| 21549 | |
| 21550 | pass-header <name> [ { if | unless } <condition> ] |
| 21551 | Specify the name of a request header which will be passed to the FastCGI |
| 21552 | application. It may optionally be followed by an ACL-based condition, in |
| 21553 | which case it will only be evaluated if the condition is true. |
| 21554 | |
| 21555 | Most request headers are already available to the FastCGI application, |
| 21556 | prefixed with "HTTP_". Thus, this directive is only required to pass headers |
| 21557 | that are purposefully omitted. Currently, the headers "Authorization", |
| 21558 | "Proxy-Authorization" and hop-by-hop headers are omitted. |
| 21559 | |
| 21560 | Note that the headers "Content-type" and "Content-length" are never passed to |
| 21561 | the FastCGI application because they are already converted into parameters. |
| 21562 | |
| 21563 | path-info <regex> |
Christopher Faulet | 28cb366 | 2020-02-14 14:47:37 +0100 | [diff] [blame] | 21564 | Define a regular expression to extract the script-name and the path-info from |
Christopher Faulet | 6c57f2d | 2020-02-14 16:55:52 +0100 | [diff] [blame] | 21565 | the URL-decoded path. Thus, <regex> may have two captures: the first one to |
| 21566 | capture the script name and the second one to capture the path-info. The |
| 21567 | first one is mandatory, the second one is optional. This way, it is possible |
| 21568 | to extract the script-name from the path ignoring the path-info. It is an |
| 21569 | optional setting. If it is not defined, no matching is performed on the |
| 21570 | path. and the FastCGI parameters PATH_INFO and PATH_TRANSLATED are not |
| 21571 | filled. |
Christopher Faulet | 28cb366 | 2020-02-14 14:47:37 +0100 | [diff] [blame] | 21572 | |
| 21573 | For security reason, when this regular expression is defined, the newline and |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 21574 | the null characters are forbidden from the path, once URL-decoded. The reason |
Christopher Faulet | 28cb366 | 2020-02-14 14:47:37 +0100 | [diff] [blame] | 21575 | to such limitation is because otherwise the matching always fails (due to a |
| 21576 | limitation one the way regular expression are executed in HAProxy). So if one |
| 21577 | of these two characters is found in the URL-decoded path, an error is |
| 21578 | returned to the client. The principle of least astonishment is applied here. |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21579 | |
| 21580 | Example : |
Christopher Faulet | 6c57f2d | 2020-02-14 16:55:52 +0100 | [diff] [blame] | 21581 | path-info ^(/.+\.php)(/.*)?$ # both script-name and path-info may be set |
| 21582 | path-info ^(/.+\.php) # the path-info is ignored |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21583 | |
| 21584 | option get-values |
| 21585 | no option get-values |
| 21586 | Enable or disable the retrieve of variables about connection management. |
| 21587 | |
Daniel Corbett | 67a8271 | 2020-07-06 23:01:19 -0400 | [diff] [blame] | 21588 | HAProxy is able to send the record FCGI_GET_VALUES on connection |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21589 | establishment to retrieve the value for following variables: |
| 21590 | |
| 21591 | * FCGI_MAX_REQS The maximum number of concurrent requests this |
| 21592 | application will accept. |
| 21593 | |
William Lallemand | 93e548e | 2019-09-30 13:54:02 +0200 | [diff] [blame] | 21594 | * FCGI_MPXS_CONNS "0" if this application does not multiplex connections, |
| 21595 | "1" otherwise. |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21596 | |
| 21597 | Some FastCGI applications does not support this feature. Some others close |
Ilya Shipitsin | 11057a3 | 2020-06-21 21:18:27 +0500 | [diff] [blame] | 21598 | the connection immediately after sending their response. So, by default, this |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21599 | option is disabled. |
| 21600 | |
| 21601 | Note that the maximum number of concurrent requests accepted by a FastCGI |
| 21602 | application is a connection variable. It only limits the number of streams |
| 21603 | per connection. If the global load must be limited on the application, the |
| 21604 | server parameters "maxconn" and "pool-max-conn" must be set. In addition, if |
| 21605 | an application does not support connection multiplexing, the maximum number |
| 21606 | of concurrent requests is automatically set to 1. |
| 21607 | |
| 21608 | option keep-conn |
| 21609 | no option keep-conn |
| 21610 | Instruct the FastCGI application to keep the connection open or not after |
| 21611 | sending a response. |
| 21612 | |
| 21613 | If disabled, the FastCGI application closes the connection after responding |
| 21614 | to this request. By default, this option is enabled. |
| 21615 | |
| 21616 | option max-reqs <reqs> |
| 21617 | Define the maximum number of concurrent requests this application will |
| 21618 | accept. |
| 21619 | |
| 21620 | This option may be overwritten if the variable FCGI_MAX_REQS is retrieved |
| 21621 | during connection establishment. Furthermore, if the application does not |
| 21622 | support connection multiplexing, this option will be ignored. By default set |
| 21623 | to 1. |
| 21624 | |
| 21625 | option mpxs-conns |
| 21626 | no option mpxs-conns |
| 21627 | Enable or disable the support of connection multiplexing. |
| 21628 | |
| 21629 | This option may be overwritten if the variable FCGI_MPXS_CONNS is retrieved |
| 21630 | during connection establishment. It is disabled by default. |
| 21631 | |
| 21632 | set-param <name> <fmt> [ { if | unless } <condition> ] |
| 21633 | Set a FastCGI parameter that should be passed to this application. Its |
| 21634 | value, defined by <fmt> must follows the log-format rules (see section 8.2.4 |
| 21635 | "Custom Log format"). It may optionally be followed by an ACL-based |
| 21636 | condition, in which case it will only be evaluated if the condition is true. |
| 21637 | |
| 21638 | With this directive, it is possible to overwrite the value of default FastCGI |
| 21639 | parameters. If the value is evaluated to an empty string, the rule is |
| 21640 | ignored. These directives are evaluated in their declaration order. |
| 21641 | |
| 21642 | Example : |
| 21643 | # PHP only, required if PHP was built with --enable-force-cgi-redirect |
| 21644 | set-param REDIRECT_STATUS 200 |
| 21645 | |
| 21646 | set-param PHP_AUTH_DIGEST %[req.hdr(Authorization)] |
| 21647 | |
| 21648 | |
| 21649 | 10.1.2. Proxy section |
| 21650 | --------------------- |
| 21651 | |
| 21652 | use-fcgi-app <name> |
| 21653 | Define the FastCGI application to use for the backend. |
| 21654 | |
| 21655 | Arguments : |
| 21656 | <name> is the name of the FastCGI application to use. |
| 21657 | |
| 21658 | This keyword is only available for HTTP proxies with the backend capability |
| 21659 | and with at least one FastCGI server. However, FastCGI servers can be mixed |
| 21660 | with HTTP servers. But except there is a good reason to do so, it is not |
| 21661 | recommended (see section 10.3 about the limitations for details). Only one |
| 21662 | application may be defined at a time per backend. |
| 21663 | |
| 21664 | Note that, once a FastCGI application is referenced for a backend, depending |
| 21665 | on the configuration some processing may be done even if the request is not |
| 21666 | sent to a FastCGI server. Rules to set parameters or pass headers to an |
| 21667 | application are evaluated. |
| 21668 | |
| 21669 | |
| 21670 | 10.1.3. Example |
| 21671 | --------------- |
| 21672 | |
| 21673 | frontend front-http |
| 21674 | mode http |
| 21675 | bind *:80 |
| 21676 | bind *: |
| 21677 | |
| 21678 | use_backend back-dynamic if { path_reg ^/.+\.php(/.*)?$ } |
| 21679 | default_backend back-static |
| 21680 | |
| 21681 | backend back-static |
| 21682 | mode http |
| 21683 | server www A.B.C.D:80 |
| 21684 | |
| 21685 | backend back-dynamic |
| 21686 | mode http |
| 21687 | use-fcgi-app php-fpm |
| 21688 | server php-fpm A.B.C.D:9000 proto fcgi |
| 21689 | |
| 21690 | fcgi-app php-fpm |
| 21691 | log-stderr global |
| 21692 | option keep-conn |
| 21693 | |
| 21694 | docroot /var/www/my-app |
| 21695 | index index.php |
| 21696 | path-info ^(/.+\.php)(/.*)?$ |
| 21697 | |
| 21698 | |
| 21699 | 10.2. Default parameters |
| 21700 | ------------------------ |
| 21701 | |
| 21702 | A Responder FastCGI application has the same purpose as a CGI/1.1 program. In |
| 21703 | the CGI/1.1 specification (RFC3875), several variables must be passed to the |
Ilya Shipitsin | 8525fd9 | 2020-02-29 12:34:59 +0500 | [diff] [blame] | 21704 | script. So HAProxy set them and some others commonly used by FastCGI |
Christopher Faulet | b30b310 | 2019-09-12 23:03:09 +0200 | [diff] [blame] | 21705 | applications. All these variables may be overwritten, with caution though. |
| 21706 | |
| 21707 | +-------------------+-----------------------------------------------------+ |
| 21708 | | AUTH_TYPE | Identifies the mechanism, if any, used by HAProxy | |
| 21709 | | | to authenticate the user. Concretely, only the | |
| 21710 | | | BASIC authentication mechanism is supported. | |
| 21711 | | | | |
| 21712 | +-------------------+-----------------------------------------------------+ |
| 21713 | | CONTENT_LENGTH | Contains the size of the message-body attached to | |
| 21714 | | | the request. It means only requests with a known | |
| 21715 | | | size are considered as valid and sent to the | |
| 21716 | | | application. | |
| 21717 | | | | |
| 21718 | +-------------------+-----------------------------------------------------+ |
| 21719 | | CONTENT_TYPE | Contains the type of the message-body attached to | |
| 21720 | | | the request. It may not be set. | |
| 21721 | | | | |
| 21722 | +-------------------+-----------------------------------------------------+ |
| 21723 | | DOCUMENT_ROOT | Contains the document root on the remote host under | |
| 21724 | | | which the script should be executed, as defined in | |
| 21725 | | | the application's configuration. | |
| 21726 | | | | |
| 21727 | +-------------------+-----------------------------------------------------+ |
| 21728 | | GATEWAY_INTERFACE | Contains the dialect of CGI being used by HAProxy | |
| 21729 | | | to communicate with the FastCGI application. | |
| 21730 | | | Concretely, it is set to "CGI/1.1". | |
| 21731 | | | | |
| 21732 | +-------------------+-----------------------------------------------------+ |
| 21733 | | PATH_INFO | Contains the portion of the URI path hierarchy | |
| 21734 | | | following the part that identifies the script | |
| 21735 | | | itself. To be set, the directive "path-info" must | |
| 21736 | | | be defined. | |
| 21737 | | | | |
| 21738 | +-------------------+-----------------------------------------------------+ |
| 21739 | | PATH_TRANSLATED | If PATH_INFO is set, it is its translated version. | |
| 21740 | | | It is the concatenation of DOCUMENT_ROOT and | |
| 21741 | | | PATH_INFO. If PATH_INFO is not set, this parameters | |
| 21742 | | | is not set too. | |
| 21743 | | | | |
| 21744 | +-------------------+-----------------------------------------------------+ |
| 21745 | | QUERY_STRING | Contains the request's query string. It may not be | |
| 21746 | | | set. | |
| 21747 | | | | |
| 21748 | +-------------------+-----------------------------------------------------+ |
| 21749 | | REMOTE_ADDR | Contains the network address of the client sending | |
| 21750 | | | the request. | |
| 21751 | | | | |
| 21752 | +-------------------+-----------------------------------------------------+ |
| 21753 | | REMOTE_USER | Contains the user identification string supplied by | |
| 21754 | | | client as part of user authentication. | |
| 21755 | | | | |
| 21756 | +-------------------+-----------------------------------------------------+ |
| 21757 | | REQUEST_METHOD | Contains the method which should be used by the | |
| 21758 | | | script to process the request. | |
| 21759 | | | | |
| 21760 | +-------------------+-----------------------------------------------------+ |
| 21761 | | REQUEST_URI | Contains the request's URI. | |
| 21762 | | | | |
| 21763 | +-------------------+-----------------------------------------------------+ |
| 21764 | | SCRIPT_FILENAME | Contains the absolute pathname of the script. it is | |
| 21765 | | | the concatenation of DOCUMENT_ROOT and SCRIPT_NAME. | |
| 21766 | | | | |
| 21767 | +-------------------+-----------------------------------------------------+ |
| 21768 | | SCRIPT_NAME | Contains the name of the script. If the directive | |
| 21769 | | | "path-info" is defined, it is the first part of the | |
| 21770 | | | URI path hierarchy, ending with the script name. | |
| 21771 | | | Otherwise, it is the entire URI path. | |
| 21772 | | | | |
| 21773 | +-------------------+-----------------------------------------------------+ |
| 21774 | | SERVER_NAME | Contains the name of the server host to which the | |
| 21775 | | | client request is directed. It is the value of the | |
| 21776 | | | header "Host", if defined. Otherwise, the | |
| 21777 | | | destination address of the connection on the client | |
| 21778 | | | side. | |
| 21779 | | | | |
| 21780 | +-------------------+-----------------------------------------------------+ |
| 21781 | | SERVER_PORT | Contains the destination TCP port of the connection | |
| 21782 | | | on the client side, which is the port the client | |
| 21783 | | | connected to. | |
| 21784 | | | | |
| 21785 | +-------------------+-----------------------------------------------------+ |
| 21786 | | SERVER_PROTOCOL | Contains the request's protocol. | |
| 21787 | | | | |
| 21788 | +-------------------+-----------------------------------------------------+ |
| 21789 | | HTTPS | Set to a non-empty value ("on") if the script was | |
| 21790 | | | queried through the HTTPS protocol. | |
| 21791 | | | | |
| 21792 | +-------------------+-----------------------------------------------------+ |
| 21793 | |
| 21794 | |
| 21795 | 10.3. Limitations |
| 21796 | ------------------ |
| 21797 | |
| 21798 | The current implementation have some limitations. The first one is about the |
| 21799 | way some request headers are hidden to the FastCGI applications. This happens |
| 21800 | during the headers analysis, on the backend side, before the connection |
| 21801 | establishment. At this stage, HAProxy know the backend is using a FastCGI |
| 21802 | application but it don't know if the request will be routed to a FastCGI server |
| 21803 | or not. But to hide request headers, it simply removes them from the HTX |
| 21804 | message. So, if the request is finally routed to an HTTP server, it never see |
| 21805 | these headers. For this reason, it is not recommended to mix FastCGI servers |
| 21806 | and HTTP servers under the same backend. |
| 21807 | |
| 21808 | Similarly, the rules "set-param" and "pass-header" are evaluated during the |
| 21809 | request headers analysis. So the evaluation is always performed, even if the |
| 21810 | requests is finally forwarded to an HTTP server. |
| 21811 | |
| 21812 | About the rules "set-param", when a rule is applied, a pseudo header is added |
| 21813 | into the HTX message. So, the same way than for HTTP header rewrites, it may |
| 21814 | fail if the buffer is full. The rules "set-param" will compete with |
| 21815 | "http-request" ones. |
| 21816 | |
| 21817 | Finally, all FastCGI params and HTTP headers are sent into a unique record |
| 21818 | FCGI_PARAM. Encoding of this record must be done in one pass, otherwise a |
| 21819 | processing error is returned. It means the record FCGI_PARAM, once encoded, |
| 21820 | must not exceeds the size of a buffer. However, there is no reserve to respect |
| 21821 | here. |
William Lallemand | 86d0df0 | 2017-11-24 21:36:45 +0100 | [diff] [blame] | 21822 | |
Emeric Brun | ce325c4 | 2021-04-02 17:05:09 +0200 | [diff] [blame] | 21823 | |
| 21824 | 11. Address formats |
| 21825 | ------------------- |
| 21826 | |
| 21827 | Several statements as "bind, "server", "nameserver" and "log" requires an |
| 21828 | address. |
| 21829 | |
| 21830 | This address can be a host name, an IPv4 address, an IPv6 address, or '*'. |
| 21831 | The '*' is equal to the special address "0.0.0.0" and can be used, in the case |
| 21832 | of "bind" or "dgram-bind" to listen on all IPv4 of the system.The IPv6 |
| 21833 | equivalent is '::'. |
| 21834 | |
| 21835 | Depending of the statement, a port or port range follows the IP address. This |
| 21836 | is mandatory on 'bind' statement, optional on 'server'. |
| 21837 | |
| 21838 | This address can also begin with a slash '/'. It is considered as the "unix" |
| 21839 | family, and '/' and following characters must be present the path. |
| 21840 | |
| 21841 | Default socket type or transport method "datagram" or "stream" depends on the |
| 21842 | configuration statement showing the address. Indeed, 'bind' and 'server' will |
| 21843 | use a "stream" socket type by default whereas 'log', 'nameserver' or |
| 21844 | 'dgram-bind' will use a "datagram". |
| 21845 | |
| 21846 | Optionally, a prefix could be used to force the address family and/or the |
| 21847 | socket type and the transport method. |
| 21848 | |
| 21849 | |
| 21850 | 11.1 Address family prefixes |
| 21851 | ---------------------------- |
| 21852 | |
| 21853 | 'abns@<name>' following <name> is an abstract namespace (Linux only). |
| 21854 | |
| 21855 | 'fd@<n>' following address is a file descriptor <n> inherited from the |
| 21856 | parent. The fd must be bound and may or may not already be |
| 21857 | listening. |
| 21858 | |
| 21859 | 'ip@<address>[:port1[-port2]]' following <address> is considered as an IPv4 or |
| 21860 | IPv6 address depending on the syntax. Depending |
| 21861 | on the statement using this address, a port or |
| 21862 | a port range may or must be specified. |
| 21863 | |
| 21864 | 'ipv4@<address>[:port1[-port2]]' following <address> is always considered as |
| 21865 | an IPv4 address. Depending on the statement |
| 21866 | using this address, a port or a port range |
| 21867 | may or must be specified. |
| 21868 | |
| 21869 | 'ipv6@<address>[:port1[-port2]]' following <address> is always considered as |
| 21870 | an IPv6 address. Depending on the statement |
| 21871 | using this address, a port or a port range |
| 21872 | may or must be specified. |
| 21873 | |
| 21874 | 'sockpair@<n>' following address is the file descriptor of a connected unix |
| 21875 | socket or of a socketpair. During a connection, the initiator |
| 21876 | creates a pair of connected sockets, and passes one of them |
| 21877 | over the FD to the other end. The listener waits to receive |
| 21878 | the FD from the unix socket and uses it as if it were the FD |
| 21879 | of an accept(). Should be used carefully. |
| 21880 | |
| 21881 | 'unix@<path>' following string is considered as a UNIX socket <path>. this |
| 21882 | prefix is useful to declare an UNIX socket path which don't |
| 21883 | start by slash '/'. |
| 21884 | |
| 21885 | |
| 21886 | 11.2 Socket type prefixes |
| 21887 | ------------------------- |
| 21888 | |
| 21889 | Previous "Address family prefixes" can also be prefixed to force the socket |
| 21890 | type and the transport method. The default depends of the statement using |
| 21891 | this address but in some cases the user may force it to a different one. |
| 21892 | This is the case for "log" statement where the default is syslog over UDP |
| 21893 | but we could force to use syslog over TCP. |
| 21894 | |
| 21895 | Those prefixes were designed for internal purpose and users should |
| 21896 | instead use aliases of the next section "11.5.3 Protocol prefixes". |
| 21897 | |
| 21898 | If users need one those prefixes to perform what they expect because |
| 21899 | they can not configure the same using the protocol prefixes, they should |
| 21900 | report this to the maintainers. |
| 21901 | |
| 21902 | 'stream+<family>@<address>' forces socket type and transport method |
| 21903 | to "stream" |
| 21904 | |
| 21905 | 'dgram+<family>@<address>' forces socket type and transport method |
| 21906 | to "datagram". |
| 21907 | |
| 21908 | |
| 21909 | 11.3 Protocol prefixes |
| 21910 | ---------------------- |
| 21911 | |
| 21912 | 'tcp@<address>[:port1[-port2]]' following <address> is considered as an IPv4 |
| 21913 | or IPv6 address depending of the syntax but |
| 21914 | socket type and transport method is forced to |
| 21915 | "stream". Depending on the statement using |
| 21916 | this address, a port or a port range can or |
| 21917 | must be specified. It is considered as an alias |
| 21918 | of 'stream+ip@'. |
| 21919 | |
| 21920 | 'tcp4@<address>[:port1[-port2]]' following <address> is always considered as |
| 21921 | an IPv4 address but socket type and transport |
| 21922 | method is forced to "stream". Depending on the |
| 21923 | statement using this address, a port or port |
| 21924 | range can or must be specified. |
| 21925 | It is considered as an alias of 'stream+ipv4@'. |
| 21926 | |
| 21927 | 'tcp6@<address>[:port1[-port2]]' following <address> is always considered as |
| 21928 | an IPv6 address but socket type and transport |
| 21929 | method is forced to "stream". Depending on the |
| 21930 | statement using this address, a port or port |
| 21931 | range can or must be specified. |
| 21932 | It is considered as an alias of 'stream+ipv4@'. |
| 21933 | |
| 21934 | 'udp@<address>[:port1[-port2]]' following <address> is considered as an IPv4 |
| 21935 | or IPv6 address depending of the syntax but |
| 21936 | socket type and transport method is forced to |
| 21937 | "datagram". Depending on the statement using |
| 21938 | this address, a port or a port range can or |
| 21939 | must be specified. It is considered as an alias |
| 21940 | of 'dgram+ip@'. |
| 21941 | |
| 21942 | 'udp4@<address>[:port1[-port2]]' following <address> is always considered as |
| 21943 | an IPv4 address but socket type and transport |
| 21944 | method is forced to "datagram". Depending on |
| 21945 | the statement using this address, a port or |
| 21946 | port range can or must be specified. |
| 21947 | It is considered as an alias of 'stream+ipv4@'. |
| 21948 | |
| 21949 | 'udp6@<address>[:port1[-port2]]' following <address> is always considered as |
| 21950 | an IPv6 address but socket type and transport |
| 21951 | method is forced to "datagram". Depending on |
| 21952 | the statement using this address, a port or |
| 21953 | port range can or must be specified. |
| 21954 | It is considered as an alias of 'stream+ipv4@'. |
| 21955 | |
| 21956 | 'uxdg@<path>' following string is considered as a unix socket <path> but |
| 21957 | transport method is forced to "datagram". It is considered as |
| 21958 | an alias of 'dgram+unix@'. |
| 21959 | |
| 21960 | 'uxst@<path>' following string is considered as a unix socket <path> but |
| 21961 | transport method is forced to "stream". It is considered as |
| 21962 | an alias of 'stream+unix@'. |
| 21963 | |
| 21964 | In future versions, other prefixes could be used to specify protocols like |
| 21965 | QUIC which proposes stream transport based on socket of type "datagram". |
| 21966 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 21967 | /* |
| 21968 | * Local variables: |
| 21969 | * fill-column: 79 |
| 21970 | * End: |
| 21971 | */ |