blob: ce7bdf109d0dfc29d43b2e5e9dece18ebb1e6669 [file] [log] [blame]
Willy Tarreau6a06a402007-07-15 20:15:28 +02001 ----------------------
Willy Tarreau8317b282014-04-23 01:49:41 +02002 HAProxy
Willy Tarreau6a06a402007-07-15 20:15:28 +02003 Configuration Manual
4 ----------------------
Willy Tarreau33205c22020-07-07 16:35:28 +02005 version 2.3
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
Willy Tarreau253c4dc2020-09-11 17:05:59 +02007 2020/09/11
Willy Tarreau6a06a402007-07-15 20:15:28 +02008
9
10This document covers the configuration language as implemented in the version
Davor Ocelice9ed2812017-12-25 17:49:28 +010011specified above. It does not provide any hints, examples, or advice. For such
Willy Tarreau0ba27502007-12-24 16:55:16 +010012documentation, please refer to the Reference Manual or the Architecture Manual.
Davor Ocelice9ed2812017-12-25 17:49:28 +010013The summary below is meant to help you find sections by name and navigate
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014through the document.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016Note to documentation contributors :
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017 This document is formatted with 80 columns per line, with even number of
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018 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 Tarreau62a36c42010-08-17 15:53:10 +020021 ('\') and continue on next line, indented by two characters. It is also
Davor Ocelice9ed2812017-12-25 17:49:28 +010022 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 Tarreau62a36c42010-08-17 15:53:10 +020025 please update the summary below for easier searching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020026
27
28Summary
29-------
30
311. Quick reminder about HTTP
321.1. The HTTP transaction model
331.2. HTTP request
Davor Ocelice9ed2812017-12-25 17:49:28 +0100341.2.1. The request line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200351.2.2. The request headers
361.3. HTTP response
Davor Ocelice9ed2812017-12-25 17:49:28 +0100371.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200381.3.2. The response headers
39
402. Configuring HAProxy
412.1. Configuration file format
William Lallemandf9873ba2015-05-05 17:37:14 +0200422.2. Quoting and escaping
William Lallemandb2f07452015-05-12 14:27:13 +0200432.3. Environment variables
442.4. Time format
452.5. Examples
Willy Tarreauc57f0e22009-05-10 13:12:33 +020046
473. Global parameters
483.1. Process management and security
493.2. Performance tuning
503.3. Debugging
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +0100513.4. Userlists
Cyril Bontédc4d9032012-04-08 21:57:39 +0200523.5. Peers
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200533.6. Mailers
William Lallemandc9515522019-06-12 16:32:11 +0200543.7. Programs
Christopher Faulet76edc0f2020-01-13 15:52:01 +0100553.8. HTTP-errors
Emeric Brun99c453d2020-05-25 15:01:04 +0200563.9. Rings
Willy Tarreauc57f0e22009-05-10 13:12:33 +020057
584. Proxies
594.1. Proxy keywords matrix
604.2. Alphabetically sorted keywords reference
61
Davor Ocelice9ed2812017-12-25 17:49:28 +0100625. Bind and server options
Willy Tarreau086fbf52012-09-24 20:34:51 +0200635.1. Bind options
645.2. Server and default-server options
Baptiste Assmann1fa66662015-04-14 00:28:47 +0200655.3. Server DNS resolution
665.3.1. Global overview
675.3.2. The resolvers section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020068
Julien Pivotto6ccee412019-11-27 15:49:54 +0100696. Cache
706.1. Limitation
716.2. Setup
726.2.1. Cache section
736.2.2. Proxy section
74
Willy Tarreau74ca5042013-06-11 23:12:07 +0200757. Using ACLs and fetching samples
767.1. ACL basics
777.1.1. Matching booleans
787.1.2. Matching integers
797.1.3. Matching strings
807.1.4. Matching regular expressions (regexes)
817.1.5. Matching arbitrary data blocks
827.1.6. Matching IPv4 and IPv6 addresses
837.2. Using ACLs to form conditions
847.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200857.3.1. Converters
867.3.2. Fetching samples from internal states
877.3.3. Fetching samples at Layer 4
887.3.4. Fetching samples at Layer 5
897.3.5. Fetching samples from buffer contents (Layer 6)
907.3.6. Fetching HTTP samples (Layer 7)
Christopher Faulete596d182020-05-05 17:46:34 +0200917.3.7. Fetching samples for developers
Willy Tarreau74ca5042013-06-11 23:12:07 +0200927.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020093
948. Logging
958.1. Log levels
968.2. Log formats
978.2.1. Default log format
988.2.2. TCP log format
998.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +01001008.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +01001018.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +02001028.3. Advanced logging options
1038.3.1. Disabling logging of external tests
1048.3.2. Logging before waiting for the session to terminate
1058.3.3. Raising log level upon errors
1068.3.4. Disabling logging of successful connections
1078.4. Timing events
1088.5. Session state at disconnection
1098.6. Non-printable characters
1108.7. Capturing HTTP cookies
1118.8. Capturing HTTP headers
1128.9. Examples of logs
113
Christopher Fauletc3fe5332016-04-07 15:30:10 +02001149. Supported filters
1159.1. Trace
1169.2. HTTP compression
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001179.3. Stream Processing Offload Engine (SPOE)
Christopher Faulet99a17a22018-12-11 09:18:27 +01001189.4. Cache
Christopher Fauletb30b3102019-09-12 23:03:09 +02001199.5. fcgi-app
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200120
Christopher Fauletb30b3102019-09-12 23:03:09 +020012110. FastCGI applications
12210.1. Setup
12310.1.1. Fcgi-app section
12410.1.2. Proxy section
12510.1.3. Example
12610.2. Default parameters
12710.3. Limitations
128
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200129
1301. Quick reminder about HTTP
131----------------------------
132
Davor Ocelice9ed2812017-12-25 17:49:28 +0100133When HAProxy is running in HTTP mode, both the request and the response are
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200134fully analyzed and indexed, thus it becomes possible to build matching criteria
135on almost anything found in the contents.
136
137However, it is important to understand how HTTP requests and responses are
138formed, and how HAProxy decomposes them. It will then become easier to write
139correct rules and to debug existing configurations.
140
141
1421.1. The HTTP transaction model
143-------------------------------
144
145The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100146to one and only one response. Traditionally, a TCP connection is established
Davor Ocelice9ed2812017-12-25 17:49:28 +0100147from the client to the server, a request is sent by the client through the
148connection, the server responds, and the connection is closed. A new request
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200149will involve a new connection :
150
151 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
152
153In this mode, called the "HTTP close" mode, there are as many connection
154establishments as there are HTTP transactions. Since the connection is closed
155by the server after the response, the client does not need to know the content
156length.
157
158Due to the transactional nature of the protocol, it was possible to improve it
159to avoid closing a connection between two subsequent transactions. In this mode
160however, it is mandatory that the server indicates the content length for each
161response so that the client does not wait indefinitely. For this, a special
162header is used: "Content-length". This mode is called the "keep-alive" mode :
163
164 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
165
166Its advantages are a reduced latency between transactions, and less processing
167power required on the server side. It is generally better than the close mode,
168but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200169a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170
Willy Tarreau95c4e142017-11-26 12:18:55 +0100171Another improvement in the communications is the pipelining mode. It still uses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172keep-alive, but the client does not wait for the first response to send the
173second request. This is useful for fetching large number of images composing a
174page :
175
176 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
177
178This can obviously have a tremendous benefit on performance because the network
179latency is eliminated between subsequent requests. Many HTTP agents do not
180correctly support pipelining since there is no way to associate a response with
181the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100182server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200183
Willy Tarreau95c4e142017-11-26 12:18:55 +0100184The next improvement is the multiplexed mode, as implemented in HTTP/2. This
185time, each transaction is assigned a single stream identifier, and all streams
186are multiplexed over an existing connection. Many requests can be sent in
187parallel by the client, and responses can arrive in any order since they also
188carry the stream identifier.
189
Willy Tarreau70dffda2014-01-30 03:07:23 +0100190By default HAProxy operates in keep-alive mode with regards to persistent
191connections: for each connection it processes each request and response, and
192leaves the connection idle on both sides between the end of a response and the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100193start of a new request. When it receives HTTP/2 connections from a client, it
194processes all the requests in parallel and leaves the connection idling,
195waiting for new requests, just as if it was a keep-alive HTTP connection.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200196
Christopher Faulet315b39c2018-09-21 16:26:19 +0200197HAProxy supports 4 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +0100198 - keep alive : all requests and responses are processed (default)
199 - tunnel : only the first request and response are processed,
Christopher Faulet6c9bbb22019-03-26 21:37:23 +0100200 everything else is forwarded with no analysis (deprecated).
Willy Tarreau70dffda2014-01-30 03:07:23 +0100201 - server close : the server-facing connection is closed after the response.
Christopher Faulet315b39c2018-09-21 16:26:19 +0200202 - close : the connection is actively closed after end of response.
Willy Tarreau70dffda2014-01-30 03:07:23 +0100203
Willy Tarreau95c4e142017-11-26 12:18:55 +0100204
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200205
2061.2. HTTP request
207-----------------
208
209First, let's consider this HTTP request :
210
211 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100212 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200213 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
214 2 Host: www.mydomain.com
215 3 User-agent: my small browser
216 4 Accept: image/jpeg, image/gif
217 5 Accept: image/png
218
219
2201.2.1. The Request line
221-----------------------
222
223Line 1 is the "request line". It is always composed of 3 fields :
224
225 - a METHOD : GET
226 - a URI : /serv/login.php?lang=en&profile=2
227 - a version tag : HTTP/1.1
228
229All of them are delimited by what the standard calls LWS (linear white spaces),
230which are commonly spaces, but can also be tabs or line feeds/carriage returns
231followed by spaces/tabs. The method itself cannot contain any colon (':') and
232is limited to alphabetic letters. All those various combinations make it
233desirable that HAProxy performs the splitting itself rather than leaving it to
234the user to write a complex or inaccurate regular expression.
235
236The URI itself can have several forms :
237
238 - A "relative URI" :
239
240 /serv/login.php?lang=en&profile=2
241
242 It is a complete URL without the host part. This is generally what is
243 received by servers, reverse proxies and transparent proxies.
244
245 - An "absolute URI", also called a "URL" :
246
247 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
248
249 It is composed of a "scheme" (the protocol name followed by '://'), a host
250 name or address, optionally a colon (':') followed by a port number, then
251 a relative URI beginning at the first slash ('/') after the address part.
252 This is generally what proxies receive, but a server supporting HTTP/1.1
253 must accept this form too.
254
255 - a star ('*') : this form is only accepted in association with the OPTIONS
256 method and is not relayable. It is used to inquiry a next hop's
257 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100258
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200259 - an address:port combination : 192.168.0.12:80
260 This is used with the CONNECT method, which is used to establish TCP
261 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
262 other protocols too.
263
264In a relative URI, two sub-parts are identified. The part before the question
265mark is called the "path". It is typically the relative path to static objects
266on the server. The part after the question mark is called the "query string".
267It is mostly used with GET requests sent to dynamic scripts and is very
268specific to the language, framework or application in use.
269
Willy Tarreau95c4e142017-11-26 12:18:55 +0100270HTTP/2 doesn't convey a version information with the request, so the version is
Davor Ocelice9ed2812017-12-25 17:49:28 +0100271assumed to be the same as the one of the underlying protocol (i.e. "HTTP/2").
Willy Tarreau95c4e142017-11-26 12:18:55 +0100272
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200273
2741.2.2. The request headers
275--------------------------
276
277The headers start at the second line. They are composed of a name at the
278beginning of the line, immediately followed by a colon (':'). Traditionally,
279an LWS is added after the colon but that's not required. Then come the values.
280Multiple identical headers may be folded into one single line, delimiting the
281values with commas, provided that their order is respected. This is commonly
282encountered in the "Cookie:" field. A header may span over multiple lines if
283the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
284define a total of 3 values for the "Accept:" header.
285
Davor Ocelice9ed2812017-12-25 17:49:28 +0100286Contrary to a common misconception, header names are not case-sensitive, and
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200287their values are not either if they refer to other header names (such as the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100288"Connection:" header). In HTTP/2, header names are always sent in lower case,
Willy Tarreau253c2512020-07-07 15:55:23 +0200289as can be seen when running in debug mode. Internally, all header names are
290normalized to lower case so that HTTP/1.x and HTTP/2 use the exact same
291representation, and they are sent as-is on the other side. This explains why an
292HTTP/1.x request typed with camel case is delivered in lower case.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200293
294The end of the headers is indicated by the first empty line. People often say
295that it's a double line feed, which is not exact, even if a double line feed
296is one valid form of empty line.
297
298Fortunately, HAProxy takes care of all these complex combinations when indexing
299headers, checking values and counting them, so there is no reason to worry
300about the way they could be written, but it is important not to accuse an
301application of being buggy if it does unusual, valid things.
302
303Important note:
Lukas Tribus23953682017-04-28 13:24:30 +0000304 As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200305 in the middle of headers by LWS in order to join multi-line headers. This
306 is necessary for proper analysis and helps less capable HTTP parsers to work
307 correctly and not to be fooled by such complex constructs.
308
309
3101.3. HTTP response
311------------------
312
313An HTTP response looks very much like an HTTP request. Both are called HTTP
314messages. Let's consider this HTTP response :
315
316 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100317 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200318 1 HTTP/1.1 200 OK
319 2 Content-length: 350
320 3 Content-Type: text/html
321
Willy Tarreau816b9792009-09-15 21:25:21 +0200322As a special case, HTTP supports so called "Informational responses" as status
323codes 1xx. These messages are special in that they don't convey any part of the
324response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100325continue to post its request for instance. In the case of a status 100 response
326the requested information will be carried by the next non-100 response message
327following the informational one. This implies that multiple responses may be
328sent to a single request, and that this only works when keep-alive is enabled
329(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
330correctly forward and skip them, and only process the next non-100 response. As
331such, these messages are neither logged nor transformed, unless explicitly
332state otherwise. Status 101 messages indicate that the protocol is changing
333over the same connection and that haproxy must switch to tunnel mode, just as
334if a CONNECT had occurred. Then the Upgrade header would contain additional
335information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200336
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200337
Davor Ocelice9ed2812017-12-25 17:49:28 +01003381.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200339------------------------
340
341Line 1 is the "response line". It is always composed of 3 fields :
342
343 - a version tag : HTTP/1.1
344 - a status code : 200
345 - a reason : OK
346
347The status code is always 3-digit. The first digit indicates a general status :
Davor Ocelice9ed2812017-12-25 17:49:28 +0100348 - 1xx = informational message to be skipped (e.g. 100, 101)
349 - 2xx = OK, content is following (e.g. 200, 206)
350 - 3xx = OK, no content following (e.g. 302, 304)
351 - 4xx = error caused by the client (e.g. 401, 403, 404)
352 - 5xx = error caused by the server (e.g. 500, 502, 503)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200353
Lukas Tribus23953682017-04-28 13:24:30 +0000354Please refer to RFC7231 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100355"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200356found there, but it's a common practice to respect the well-established
357messages. It can be composed of one or multiple words, such as "OK", "Found",
358or "Authentication Required".
359
Davor Ocelice9ed2812017-12-25 17:49:28 +0100360HAProxy may emit the following status codes by itself :
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200361
362 Code When / reason
363 200 access to stats page, and when replying to monitoring requests
364 301 when performing a redirection, depending on the configured code
365 302 when performing a redirection, depending on the configured code
366 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100367 307 when performing a redirection, depending on the configured code
368 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200369 400 for an invalid or too large request
370 401 when an authentication is required to perform the action (when
371 accessing the stats page)
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200372 403 when a request is forbidden by a "http-request deny" rule
Florian Tham9205fea2020-01-08 13:35:30 +0100373 404 when the requested resource could not be found
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200374 408 when the request timeout strikes before the request is complete
Florian Tham272e29b2020-01-08 10:19:05 +0100375 410 when the requested resource is no longer available and will not
376 be available again
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200377 500 when haproxy encounters an unrecoverable internal error, such as a
378 memory allocation failure, which should never happen
379 502 when the server returns an empty, invalid or incomplete response, or
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200380 when an "http-response deny" rule blocks the response.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200381 503 when no server was available to handle the request, or in response to
382 monitoring requests which match the "monitor fail" condition
383 504 when the response timeout strikes before the server responds
384
385The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3864.2).
387
388
3891.3.2. The response headers
390---------------------------
391
392Response headers work exactly like request headers, and as such, HAProxy uses
393the same parsing function for both. Please refer to paragraph 1.2.2 for more
394details.
395
396
3972. Configuring HAProxy
398----------------------
399
4002.1. Configuration file format
401------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200402
403HAProxy's configuration process involves 3 major sources of parameters :
404
405 - the arguments from the command-line, which always take precedence
406 - the "global" section, which sets process-wide parameters
407 - the proxies sections which can take form of "defaults", "listen",
408 "frontend" and "backend".
409
Willy Tarreau0ba27502007-12-24 16:55:16 +0100410The configuration file syntax consists in lines beginning with a keyword
411referenced in this manual, optionally followed by one or several parameters
William Lallemandf9873ba2015-05-05 17:37:14 +0200412delimited by spaces.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100413
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200414
William Lallemandf9873ba2015-05-05 17:37:14 +02004152.2. Quoting and escaping
416-------------------------
417
418HAProxy's configuration introduces a quoting and escaping system similar to
419many programming languages. The configuration file supports 3 types: escaping
420with a backslash, weak quoting with double quotes, and strong quoting with
421single quotes.
422
423If spaces have to be entered in strings, then they must be escaped by preceding
424them by a backslash ('\') or by quoting them. Backslashes also have to be
425escaped by doubling or strong quoting them.
426
427Escaping is achieved by preceding a special character by a backslash ('\'):
428
429 \ to mark a space and differentiate it from a delimiter
430 \# to mark a hash and differentiate it from a comment
431 \\ to use a backslash
432 \' to use a single quote and differentiate it from strong quoting
433 \" to use a double quote and differentiate it from weak quoting
434
435Weak quoting is achieved by using double quotes (""). Weak quoting prevents
436the interpretation of:
437
438 space as a parameter separator
439 ' single quote as a strong quoting delimiter
440 # hash as a comment start
441
William Lallemandb2f07452015-05-12 14:27:13 +0200442Weak quoting permits the interpretation of variables, if you want to use a non
443-interpreted dollar within a double quoted string, you should escape it with a
444backslash ("\$"), it does not work outside weak quoting.
445
446Interpretation of escaping and special characters are not prevented by weak
William Lallemandf9873ba2015-05-05 17:37:14 +0200447quoting.
448
449Strong quoting is achieved by using single quotes (''). Inside single quotes,
450nothing is interpreted, it's the efficient way to quote regexes.
451
452Quoted and escaped strings are replaced in memory by their interpreted
453equivalent, it allows you to perform concatenation.
454
455 Example:
456 # those are equivalents:
457 log-format %{+Q}o\ %t\ %s\ %{-Q}r
458 log-format "%{+Q}o %t %s %{-Q}r"
459 log-format '%{+Q}o %t %s %{-Q}r'
460 log-format "%{+Q}o %t"' %s %{-Q}r'
461 log-format "%{+Q}o %t"' %s'\ %{-Q}r
462
463 # those are equivalents:
464 reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2
465 reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2'
466 reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2"
467 reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2"
468
469
William Lallemandb2f07452015-05-12 14:27:13 +02004702.3. Environment variables
471--------------------------
472
473HAProxy's configuration supports environment variables. Those variables are
474interpreted only within double quotes. Variables are expanded during the
475configuration parsing. Variable names must be preceded by a dollar ("$") and
476optionally enclosed with braces ("{}") similarly to what is done in Bourne
477shell. Variable names can contain alphanumerical characters or the character
478underscore ("_") but should not start with a digit.
479
480 Example:
481
482 bind "fd@${FD_APP1}"
483
484 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
485
486 user "$HAPROXY_USER"
487
William Lallemand4d03e432019-06-14 15:35:37 +0200488Some variables are defined by HAProxy, they can be used in the configuration
489file, or could be inherited by a program (See 3.7. Programs):
William Lallemanddaf4cd22018-04-17 16:46:13 +0200490
William Lallemand4d03e432019-06-14 15:35:37 +0200491* HAPROXY_LOCALPEER: defined at the startup of the process which contains the
492 name of the local peer. (See "-L" in the management guide.)
493
494* HAPROXY_CFGFILES: list of the configuration files loaded by HAProxy,
495 separated by semicolons. Can be useful in the case you specified a
496 directory.
497
498* HAPROXY_MWORKER: In master-worker mode, this variable is set to 1.
499
John Roeslerfb2fce12019-07-10 15:45:51 -0500500* HAPROXY_CLI: configured listeners addresses of the stats socket for every
William Lallemand4d03e432019-06-14 15:35:37 +0200501 processes, separated by semicolons.
502
John Roeslerfb2fce12019-07-10 15:45:51 -0500503* HAPROXY_MASTER_CLI: In master-worker mode, listeners addresses of the master
William Lallemand4d03e432019-06-14 15:35:37 +0200504 CLI, separated by semicolons.
505
506See also "external-check command" for other variables.
William Lallemandb2f07452015-05-12 14:27:13 +0200507
5082.4. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200509----------------
510
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100511Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100512values are generally expressed in milliseconds (unless explicitly stated
513otherwise) but may be expressed in any other unit by suffixing the unit to the
514numeric value. It is important to consider this because it will not be repeated
515for every keyword. Supported units are :
516
517 - us : microseconds. 1 microsecond = 1/1000000 second
518 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
519 - s : seconds. 1s = 1000ms
520 - m : minutes. 1m = 60s = 60000ms
521 - h : hours. 1h = 60m = 3600s = 3600000ms
522 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
523
524
Lukas Tribusaa83a312017-03-21 09:25:09 +00005252.5. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200526-------------
527
528 # Simple configuration for an HTTP proxy listening on port 80 on all
529 # interfaces and forwarding requests to a single backend "servers" with a
530 # single server "server1" listening on 127.0.0.1:8000
531 global
532 daemon
533 maxconn 256
534
535 defaults
536 mode http
537 timeout connect 5000ms
538 timeout client 50000ms
539 timeout server 50000ms
540
541 frontend http-in
542 bind *:80
543 default_backend servers
544
545 backend servers
546 server server1 127.0.0.1:8000 maxconn 32
547
548
549 # The same configuration defined with a single listen block. Shorter but
550 # less expressive, especially in HTTP mode.
551 global
552 daemon
553 maxconn 256
554
555 defaults
556 mode http
557 timeout connect 5000ms
558 timeout client 50000ms
559 timeout server 50000ms
560
561 listen http-in
562 bind *:80
563 server server1 127.0.0.1:8000 maxconn 32
564
565
566Assuming haproxy is in $PATH, test these configurations in a shell with:
567
Willy Tarreauccb289d2010-12-11 20:19:38 +0100568 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200569
570
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005713. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200572--------------------
573
574Parameters in the "global" section are process-wide and often OS-specific. They
575are generally set once for all and do not need being changed once correct. Some
576of them have command-line equivalents.
577
578The following keywords are supported in the "global" section :
579
580 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200581 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200582 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200583 - crt-base
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200584 - cpu-map
Willy Tarreau6a06a402007-07-15 20:15:28 +0200585 - daemon
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200586 - description
587 - deviceatlas-json-file
588 - deviceatlas-log-level
589 - deviceatlas-separator
590 - deviceatlas-properties-cookie
Simon Horman98637e52014-06-20 12:30:16 +0900591 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200592 - gid
593 - group
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100594 - hard-stop-after
Christopher Faulet98fbe952019-07-22 16:18:24 +0200595 - h1-case-adjust
596 - h1-case-adjust-file
Willy Tarreaud96f1122019-12-03 07:07:36 +0100597 - insecure-fork-wanted
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100598 - insecure-setuid-wanted
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +0100599 - issuers-chain-path
Dragan Dosen13cd54c2020-06-18 18:24:05 +0200600 - localpeer
Willy Tarreau6a06a402007-07-15 20:15:28 +0200601 - log
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200602 - log-tag
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100603 - log-send-hostname
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200604 - lua-load
Tim Duesterhusdd74b5f2020-01-12 13:55:40 +0100605 - lua-prepend-path
William Lallemand27edc4b2019-05-07 17:49:33 +0200606 - mworker-max-reloads
Willy Tarreau6a06a402007-07-15 20:15:28 +0200607 - nbproc
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200608 - nbthread
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200609 - node
Willy Tarreau6a06a402007-07-15 20:15:28 +0200610 - pidfile
Willy Tarreau119e50e2020-05-22 13:53:29 +0200611 - pp2-never-send-local
Willy Tarreau1d549722016-02-16 12:41:57 +0100612 - presetenv
613 - resetenv
Willy Tarreau6a06a402007-07-15 20:15:28 +0200614 - uid
615 - ulimit-n
616 - user
Willy Tarreau636848a2019-04-15 19:38:50 +0200617 - set-dumpable
Willy Tarreau1d549722016-02-16 12:41:57 +0100618 - setenv
Willy Tarreaufbee7132007-10-18 13:53:22 +0200619 - stats
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200620 - ssl-default-bind-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200621 - ssl-default-bind-ciphersuites
Jerome Magninb203ff62020-04-03 15:28:22 +0200622 - ssl-default-bind-curves
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200623 - ssl-default-bind-options
624 - ssl-default-server-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200625 - ssl-default-server-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200626 - ssl-default-server-options
627 - ssl-dh-param-file
Emeric Brun850efd52014-01-29 12:24:34 +0100628 - ssl-server-verify
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +0200629 - ssl-skip-self-issued-ca
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100630 - unix-bind
Willy Tarreau1d549722016-02-16 12:41:57 +0100631 - unsetenv
Thomas Holmesdb04f192015-05-18 13:21:39 +0100632 - 51degrees-data-file
633 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +0200634 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200635 - 51degrees-cache-size
Willy Tarreaub3cc9f22019-04-19 16:03:32 +0200636 - wurfl-data-file
637 - wurfl-information-list
638 - wurfl-information-list-separator
Willy Tarreaub3cc9f22019-04-19 16:03:32 +0200639 - wurfl-cache-size
William Dauchy0fec3ab2019-10-27 20:08:11 +0100640 - strict-limits
Willy Tarreaud72758d2010-01-12 10:42:19 +0100641
Willy Tarreau6a06a402007-07-15 20:15:28 +0200642 * Performance tuning
William Dauchy0a8824f2019-10-27 20:08:09 +0100643 - busy-polling
Willy Tarreau1746eec2014-04-25 10:46:47 +0200644 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200645 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200646 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100647 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100648 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100649 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200650 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200651 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200652 - maxsslrate
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200653 - maxzlibmem
Willy Tarreau6a06a402007-07-15 20:15:28 +0200654 - noepoll
655 - nokqueue
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +0000656 - noevports
Willy Tarreau6a06a402007-07-15 20:15:28 +0200657 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100658 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300659 - nogetaddrinfo
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +0000660 - noreuseport
Willy Tarreau75c62c22018-11-22 11:02:09 +0100661 - profiling.tasks
Willy Tarreaufe255b72007-10-14 23:09:26 +0200662 - spread-checks
Baptiste Assmann5626f482015-08-23 10:00:10 +0200663 - server-state-base
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200664 - server-state-file
Grant Zhang872f9c22017-01-21 01:10:18 +0000665 - ssl-engine
Grant Zhangfa6c7ee2017-01-14 01:42:15 +0000666 - ssl-mode-async
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200667 - tune.buffers.limit
668 - tune.buffers.reserve
Willy Tarreau27a674e2009-08-17 07:23:33 +0200669 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200670 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100671 - tune.comp.maxlevel
Willy Tarreaubc52bec2020-06-18 08:58:47 +0200672 - tune.fd.edge-triggered
Willy Tarreaufe20e5b2017-07-27 11:42:14 +0200673 - tune.h2.header-table-size
Willy Tarreaue6baec02017-07-27 11:45:11 +0200674 - tune.h2.initial-window-size
Willy Tarreau5242ef82017-07-27 11:47:28 +0200675 - tune.h2.max-concurrent-streams
Willy Tarreau193b8c62012-11-22 00:17:38 +0100676 - tune.http.cookielen
Stéphane Cottin23e9e932017-05-18 08:58:41 +0200677 - tune.http.logurilen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200678 - tune.http.maxhdr
Willy Tarreau76cc6992020-07-01 18:49:24 +0200679 - tune.idle-pool.shared
Willy Tarreau7e312732014-02-12 16:35:14 +0100680 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100681 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +0100682 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100683 - tune.lua.session-timeout
684 - tune.lua.task-timeout
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +0200685 - tune.lua.service-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100686 - tune.maxaccept
687 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200688 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +0200689 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200690 - tune.pipesize
Willy Tarreaua8e2d972020-07-01 18:27:16 +0200691 - tune.pool-high-fd-ratio
692 - tune.pool-low-fd-ratio
Willy Tarreaue803de22010-01-21 17:43:04 +0100693 - tune.rcvbuf.client
694 - tune.rcvbuf.server
Willy Tarreaub22fc302015-12-14 12:04:35 +0100695 - tune.recv_enough
Olivier Houchard1599b802018-05-24 18:59:04 +0200696 - tune.runqueue-depth
Willy Tarreaue7723bd2020-06-24 11:11:02 +0200697 - tune.sched.low-latency
Willy Tarreaue803de22010-01-21 17:43:04 +0100698 - tune.sndbuf.client
699 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100700 - tune.ssl.cachesize
William Lallemand7d42ef52020-07-06 11:41:30 +0200701 - tune.ssl.keylog
Willy Tarreaubfd59462013-02-21 07:46:09 +0100702 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200703 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100704 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200705 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +0200706 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER5bf77322017-02-25 12:45:22 +0100707 - tune.ssl.capture-cipherlist-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200708 - tune.vars.global-max-size
Christopher Fauletff2613e2016-11-09 11:36:17 +0100709 - tune.vars.proc-max-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200710 - tune.vars.reqres-max-size
711 - tune.vars.sess-max-size
712 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +0100713 - tune.zlib.memlevel
714 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100715
Willy Tarreau6a06a402007-07-15 20:15:28 +0200716 * Debugging
717 - debug
718 - quiet
Willy Tarreau3eb10b82020-04-15 16:42:39 +0200719 - zero-warning
Willy Tarreau6a06a402007-07-15 20:15:28 +0200720
721
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007223.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200723------------------------------------
724
Emeric Brunc8e8d122012-10-02 18:42:10 +0200725ca-base <dir>
726 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emmanuel Hocdet842e94e2019-12-16 16:39:17 +0100727 relative path is used with "ca-file", "ca-verify-file" or "crl-file"
728 directives. Absolute locations specified in "ca-file", "ca-verify-file" and
729 "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200730
Willy Tarreau6a06a402007-07-15 20:15:28 +0200731chroot <jail dir>
732 Changes current directory to <jail dir> and performs a chroot() there before
733 dropping privileges. This increases the security level in case an unknown
734 vulnerability would be exploited, since it would make it very hard for the
735 attacker to exploit the system. This only works when the process is started
736 with superuser privileges. It is important to ensure that <jail_dir> is both
Davor Ocelice9ed2812017-12-25 17:49:28 +0100737 empty and non-writable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100738
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100739cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>...
740 On Linux 2.6 and above, it is possible to bind a process or a thread to a
741 specific CPU set. This means that the process or the thread will never run on
742 other CPUs. The "cpu-map" directive specifies CPU sets for process or thread
743 sets. The first argument is a process set, eventually followed by a thread
744 set. These sets have the format
745
746 all | odd | even | number[-[number]]
747
748 <number>> must be a number between 1 and 32 or 64, depending on the machine's
Davor Ocelice9ed2812017-12-25 17:49:28 +0100749 word size. Any process IDs above nbproc and any thread IDs above nbthread are
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100750 ignored. It is possible to specify a range with two such number delimited by
751 a dash ('-'). It also is possible to specify all processes at once using
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100752 "all", only odd numbers using "odd" or even numbers using "even", just like
753 with the "bind-process" directive. The second and forthcoming arguments are
Davor Ocelice9ed2812017-12-25 17:49:28 +0100754 CPU sets. Each CPU set is either a unique number between 0 and 31 or 63 or a
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100755 range with two such numbers delimited by a dash ('-'). Multiple CPU numbers
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100756 or ranges may be specified, and the processes or threads will be allowed to
Davor Ocelice9ed2812017-12-25 17:49:28 +0100757 bind to all of them. Obviously, multiple "cpu-map" directives may be
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100758 specified. Each "cpu-map" directive will replace the previous ones when they
759 overlap. A thread will be bound on the intersection of its mapping and the
760 one of the process on which it is attached. If the intersection is null, no
761 specific binding will be set for the thread.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100762
Christopher Fauletff4121f2017-11-22 16:38:49 +0100763 Ranges can be partially defined. The higher bound can be omitted. In such
764 case, it is replaced by the corresponding maximum value, 32 or 64 depending
765 on the machine's word size.
766
Christopher Faulet26028f62017-11-22 15:01:51 +0100767 The prefix "auto:" can be added before the process set to let HAProxy
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100768 automatically bind a process or a thread to a CPU by incrementing
769 process/thread and CPU sets. To be valid, both sets must have the same
770 size. No matter the declaration order of the CPU sets, it will be bound from
771 the lowest to the highest bound. Having a process and a thread range with the
772 "auto:" prefix is not supported. Only one range is supported, the other one
773 must be a fixed number.
Christopher Faulet26028f62017-11-22 15:01:51 +0100774
775 Examples:
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100776 cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs
777
778 cpu-map 1/all 0-3 # bind all threads of the first process on the
779 # first 4 CPUs
780
781 cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63"
782 # or "cpu-map 1-32 0-31" depending on the machine's
783 # word size.
784
Christopher Faulet26028f62017-11-22 15:01:51 +0100785 # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100786 # and so on.
Christopher Faulet26028f62017-11-22 15:01:51 +0100787 cpu-map auto:1-4 0-3
788 cpu-map auto:1-4 0-1 2-3
789 cpu-map auto:1-4 3 2 1 0
790
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100791 # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
792 # and so on.
793 cpu-map auto:1/1-4 0-3
794 cpu-map auto:1/1-4 0-1 2-3
795 cpu-map auto:1/1-4 3 2 1 0
796
Davor Ocelice9ed2812017-12-25 17:49:28 +0100797 # bind each process to exactly one CPU using all/odd/even keyword
Christopher Faulet26028f62017-11-22 15:01:51 +0100798 cpu-map auto:all 0-63
799 cpu-map auto:even 0-31
800 cpu-map auto:odd 32-63
801
802 # invalid cpu-map because process and CPU sets have different sizes.
803 cpu-map auto:1-4 0 # invalid
804 cpu-map auto:1 0-3 # invalid
805
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100806 # invalid cpu-map because automatic binding is used with a process range
807 # and a thread range.
808 cpu-map auto:all/all 0 # invalid
809 cpu-map auto:all/1-4 0 # invalid
810 cpu-map auto:1-4/all 0 # invalid
811
Emeric Brunc8e8d122012-10-02 18:42:10 +0200812crt-base <dir>
813 Assigns a default directory to fetch SSL certificates from when a relative
William Dauchy238ea3b2020-01-11 13:09:12 +0100814 path is used with "crtfile" or "crt" directives. Absolute locations specified
815 prevail and ignore "crt-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200816
Willy Tarreau6a06a402007-07-15 20:15:28 +0200817daemon
818 Makes the process fork into background. This is the recommended mode of
819 operation. It is equivalent to the command line "-D" argument. It can be
Lukas Tribusf46bf952017-11-21 12:39:34 +0100820 disabled by the command line "-db" argument. This option is ignored in
821 systemd mode.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200822
David Carlier8167f302015-06-01 13:50:06 +0200823deviceatlas-json-file <path>
824 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
Davor Ocelice9ed2812017-12-25 17:49:28 +0100825 The path must be a valid JSON data file and accessible by HAProxy process.
David Carlier8167f302015-06-01 13:50:06 +0200826
827deviceatlas-log-level <value>
Davor Ocelice9ed2812017-12-25 17:49:28 +0100828 Sets the level of information returned by the API. This directive is
David Carlier8167f302015-06-01 13:50:06 +0200829 optional and set to 0 by default if not set.
830
831deviceatlas-separator <char>
832 Sets the character separator for the API properties results. This directive
833 is optional and set to | by default if not set.
834
Cyril Bonté0306c4a2015-10-26 22:37:38 +0100835deviceatlas-properties-cookie <name>
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200836 Sets the client cookie's name used for the detection if the DeviceAtlas
837 Client-side component was used during the request. This directive is optional
838 and set to DAPROPS by default if not set.
David Carlier29b3ca32015-09-25 14:09:21 +0100839
Simon Horman98637e52014-06-20 12:30:16 +0900840external-check
Willy Tarreaud96f1122019-12-03 07:07:36 +0100841 Allows the use of an external agent to perform health checks. This is
842 disabled by default as a security precaution, and even when enabled, checks
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100843 may still fail unless "insecure-fork-wanted" is enabled as well. If the
844 program launched makes use of a setuid executable (it should really not),
845 you may also need to set "insecure-setuid-wanted" in the global section.
846 See "option external-check", and "insecure-fork-wanted", and
847 "insecure-setuid-wanted".
Simon Horman98637e52014-06-20 12:30:16 +0900848
Willy Tarreau6a06a402007-07-15 20:15:28 +0200849gid <number>
850 Changes the process' group ID to <number>. It is recommended that the group
851 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
852 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100853 Note that if haproxy is started from a user having supplementary groups, it
854 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200855 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100856
Willy Tarreau11770ce2019-12-03 08:29:22 +0100857group <group name>
858 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
859 See also "gid" and "user".
860
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100861hard-stop-after <time>
862 Defines the maximum time allowed to perform a clean soft-stop.
863
864 Arguments :
865 <time> is the maximum time (by default in milliseconds) for which the
866 instance will remain alive when a soft-stop is received via the
867 SIGUSR1 signal.
868
869 This may be used to ensure that the instance will quit even if connections
870 remain opened during a soft-stop (for example with long timeouts for a proxy
871 in tcp mode). It applies both in TCP and HTTP mode.
872
873 Example:
874 global
875 hard-stop-after 30s
876
Christopher Faulet98fbe952019-07-22 16:18:24 +0200877h1-case-adjust <from> <to>
878 Defines the case adjustment to apply, when enabled, to the header name
879 <from>, to change it to <to> before sending it to HTTP/1 clients or
880 servers. <from> must be in lower case, and <from> and <to> must not differ
881 except for their case. It may be repeated if several header names need to be
Ilya Shipitsin8525fd92020-02-29 12:34:59 +0500882 adjusted. Duplicate entries are not allowed. If a lot of header names have to
Christopher Faulet98fbe952019-07-22 16:18:24 +0200883 be adjusted, it might be more convenient to use "h1-case-adjust-file".
884 Please note that no transformation will be applied unless "option
885 h1-case-adjust-bogus-client" or "option h1-case-adjust-bogus-server" is
886 specified in a proxy.
887
888 There is no standard case for header names because, as stated in RFC7230,
889 they are case-insensitive. So applications must handle them in a case-
890 insensitive manner. But some bogus applications violate the standards and
891 erroneously rely on the cases most commonly used by browsers. This problem
892 becomes critical with HTTP/2 because all header names must be exchanged in
893 lower case, and HAProxy follows the same convention. All header names are
894 sent in lower case to clients and servers, regardless of the HTTP version.
895
896 Applications which fail to properly process requests or responses may require
897 to temporarily use such workarounds to adjust header names sent to them for
898 the time it takes the application to be fixed. Please note that an
899 application which requires such workarounds might be vulnerable to content
900 smuggling attacks and must absolutely be fixed.
901
902 Example:
903 global
904 h1-case-adjust content-length Content-Length
905
906 See "h1-case-adjust-file", "option h1-case-adjust-bogus-client" and
907 "option h1-case-adjust-bogus-server".
908
909h1-case-adjust-file <hdrs-file>
910 Defines a file containing a list of key/value pairs used to adjust the case
911 of some header names before sending them to HTTP/1 clients or servers. The
912 file <hdrs-file> must contain 2 header names per line. The first one must be
913 in lower case and both must not differ except for their case. Lines which
914 start with '#' are ignored, just like empty lines. Leading and trailing tabs
915 and spaces are stripped. Duplicate entries are not allowed. Please note that
916 no transformation will be applied unless "option h1-case-adjust-bogus-client"
917 or "option h1-case-adjust-bogus-server" is specified in a proxy.
918
919 If this directive is repeated, only the last one will be processed. It is an
920 alternative to the directive "h1-case-adjust" if a lot of header names need
921 to be adjusted. Please read the risks associated with using this.
922
923 See "h1-case-adjust", "option h1-case-adjust-bogus-client" and
924 "option h1-case-adjust-bogus-server".
925
Willy Tarreaud96f1122019-12-03 07:07:36 +0100926insecure-fork-wanted
927 By default haproxy tries hard to prevent any thread and process creation
928 after it starts. Doing so is particularly important when using Lua files of
929 uncertain origin, and when experimenting with development versions which may
930 still contain bugs whose exploitability is uncertain. And generally speaking
931 it's good hygiene to make sure that no unexpected background activity can be
932 triggered by traffic. But this prevents external checks from working, and may
933 break some very specific Lua scripts which actively rely on the ability to
934 fork. This option is there to disable this protection. Note that it is a bad
935 idea to disable it, as a vulnerability in a library or within haproxy itself
936 will be easier to exploit once disabled. In addition, forking from Lua or
937 anywhere else is not reliable as the forked process may randomly embed a lock
938 set by another thread and never manage to finish an operation. As such it is
939 highly recommended that this option is never used and that any workload
940 requiring such a fork be reconsidered and moved to a safer solution (such as
941 agents instead of external checks). This option supports the "no" prefix to
942 disable it.
943
Willy Tarreaua45a8b52019-12-06 16:31:45 +0100944insecure-setuid-wanted
945 HAProxy doesn't need to call executables at run time (except when using
946 external checks which are strongly recommended against), and is even expected
947 to isolate itself into an empty chroot. As such, there basically is no valid
948 reason to allow a setuid executable to be called without the user being fully
949 aware of the risks. In a situation where haproxy would need to call external
950 checks and/or disable chroot, exploiting a vulnerability in a library or in
951 haproxy itself could lead to the execution of an external program. On Linux
952 it is possible to lock the process so that any setuid bit present on such an
953 executable is ignored. This significantly reduces the risk of privilege
954 escalation in such a situation. This is what haproxy does by default. In case
955 this causes a problem to an external check (for example one which would need
956 the "ping" command), then it is possible to disable this protection by
957 explicitly adding this directive in the global section. If enabled, it is
958 possible to turn it back off by prefixing it with the "no" keyword.
959
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +0100960issuers-chain-path <dir>
961 Assigns a directory to load certificate chain for issuer completion. All
962 files must be in PEM format. For certificates loaded with "crt" or "crt-list",
963 if certificate chain is not included in PEM (also commonly known as
964 intermediate certificate), haproxy will complete chain if the issuer of the
965 certificate corresponds to the first certificate of the chain loaded with
966 "issuers-chain-path".
967 A "crt" file with PrivateKey+Certificate+IntermediateCA2+IntermediateCA1
968 could be replaced with PrivateKey+Certificate. HAProxy will complete the
969 chain if a file with IntermediateCA2+IntermediateCA1 is present in
970 "issuers-chain-path" directory. All other certificates with the same issuer
971 will share the chain in memory.
972
Dragan Dosen13cd54c2020-06-18 18:24:05 +0200973localpeer <name>
974 Sets the local instance's peer name. It will be ignored if the "-L"
975 command line argument is specified or if used after "peers" section
976 definitions. In such cases, a warning message will be emitted during
977 the configuration parsing.
978
979 This option will also set the HAPROXY_LOCALPEER environment variable.
980 See also "-L" in the management guide and "peers" section below.
981
Frédéric Lécailled690dfa2019-04-25 10:52:17 +0200982log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
983 <facility> [max level [min level]]
Cyril Bonté3e954872018-03-20 23:30:27 +0100984 Adds a global syslog server. Several global servers can be defined. They
Davor Ocelice9ed2812017-12-25 17:49:28 +0100985 will receive logs for starts and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100986 configured with "log global".
987
988 <address> can be one of:
989
Willy Tarreau2769aa02007-12-27 18:26:09 +0100990 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100991 no port is specified, 514 is used by default (the standard syslog
992 port).
993
David du Colombier24bb5f52011-03-17 10:40:23 +0100994 - An IPv6 address followed by a colon and optionally a UDP port. If
995 no port is specified, 514 is used by default (the standard syslog
996 port).
997
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100998 - A filesystem path to a datagram UNIX domain socket, keeping in mind
Robert Tsai81ae1952007-12-05 10:47:29 +0100999 considerations for chroot (be sure the path is accessible inside
1000 the chroot) and uid/gid (be sure the path is appropriately
Davor Ocelice9ed2812017-12-25 17:49:28 +01001001 writable).
Robert Tsai81ae1952007-12-05 10:47:29 +01001002
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01001003 - A file descriptor number in the form "fd@<number>", which may point
1004 to a pipe, terminal, or socket. In this case unbuffered logs are used
1005 and one writev() call per log is performed. This is a bit expensive
1006 but acceptable for most workloads. Messages sent this way will not be
1007 truncated but may be dropped, in which case the DroppedLogs counter
1008 will be incremented. The writev() call is atomic even on pipes for
1009 messages up to PIPE_BUF size, which POSIX recommends to be at least
1010 512 and which is 4096 bytes on most modern operating systems. Any
1011 larger message may be interleaved with messages from other processes.
1012 Exceptionally for debugging purposes the file descriptor may also be
1013 directed to a file, but doing so will significantly slow haproxy down
1014 as non-blocking calls will be ignored. Also there will be no way to
1015 purge nor rotate this file without restarting the process. Note that
1016 the configured syslog format is preserved, so the output is suitable
Willy Tarreauc1b06452018-11-12 11:57:56 +01001017 for use with a TCP syslog server. See also the "short" and "raw"
1018 format below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01001019
1020 - "stdout" / "stderr", which are respectively aliases for "fd@1" and
1021 "fd@2", see above.
1022
Willy Tarreauc046d162019-08-30 15:24:59 +02001023 - A ring buffer in the form "ring@<name>", which will correspond to an
1024 in-memory ring buffer accessible over the CLI using the "show events"
1025 command, which will also list existing rings and their sizes. Such
1026 buffers are lost on reload or restart but when used as a complement
1027 this can help troubleshooting by having the logs instantly available.
1028
William Lallemandb2f07452015-05-12 14:27:13 +02001029 You may want to reference some environment variables in the address
1030 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01001031
Willy Tarreau18324f52014-06-27 18:10:07 +02001032 <length> is an optional maximum line length. Log lines larger than this value
1033 will be truncated before being sent. The reason is that syslog
1034 servers act differently on log line length. All servers support the
1035 default value of 1024, but some servers simply drop larger lines
1036 while others do log them. If a server supports long lines, it may
1037 make sense to set this value here in order to avoid truncating long
1038 lines. Similarly, if a server drops long lines, it is preferable to
1039 truncate them before sending them. Accepted values are 80 to 65535
1040 inclusive. The default value of 1024 is generally fine for all
1041 standard usages. Some specific cases of long captures or
Davor Ocelice9ed2812017-12-25 17:49:28 +01001042 JSON-formatted logs may require larger values. You may also need to
1043 increase "tune.http.logurilen" if your request URIs are truncated.
Willy Tarreau18324f52014-06-27 18:10:07 +02001044
Dragan Dosen7ad31542015-09-28 17:16:47 +02001045 <format> is the log format used when generating syslog messages. It may be
1046 one of the following :
1047
1048 rfc3164 The RFC3164 syslog message format. This is the default.
1049 (https://tools.ietf.org/html/rfc3164)
1050
1051 rfc5424 The RFC5424 syslog message format.
1052 (https://tools.ietf.org/html/rfc5424)
1053
Emeric Brun54648852020-07-06 15:54:06 +02001054 priority A message containing only a level plus syslog facility between
1055 angle brackets such as '<63>', followed by the text. The PID,
1056 date, time, process name and system name are omitted. This is
1057 designed to be used with a local log server.
1058
Willy Tarreaue8746a02018-11-12 08:45:00 +01001059 short A message containing only a level between angle brackets such as
1060 '<3>', followed by the text. The PID, date, time, process name
1061 and system name are omitted. This is designed to be used with a
1062 local log server. This format is compatible with what the systemd
1063 logger consumes.
1064
Emeric Brun54648852020-07-06 15:54:06 +02001065 timed A message containing only a level between angle brackets such as
1066 '<3>', followed by ISO date and by the text. The PID, process
1067 name and system name are omitted. This is designed to be
1068 used with a local log server.
1069
1070 iso A message containing only the ISO date, followed by the text.
1071 The PID, process name and system name are omitted. This is
1072 designed to be used with a local log server.
1073
Willy Tarreauc1b06452018-11-12 11:57:56 +01001074 raw A message containing only the text. The level, PID, date, time,
1075 process name and system name are omitted. This is designed to be
1076 used in containers or during development, where the severity only
1077 depends on the file descriptor used (stdout/stderr).
1078
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02001079 <ranges> A list of comma-separated ranges to identify the logs to sample.
1080 This is used to balance the load of the logs to send to the log
1081 server. The limits of the ranges cannot be null. They are numbered
1082 from 1. The size or period (in number of logs) of the sample must be
1083 set with <sample_size> parameter.
1084
1085 <sample_size>
1086 The size of the sample in number of logs to consider when balancing
1087 their logging loads. It is used to balance the load of the logs to
1088 send to the syslog server. This size must be greater or equal to the
1089 maximum of the high limits of the ranges.
1090 (see also <ranges> parameter).
1091
Robert Tsai81ae1952007-12-05 10:47:29 +01001092 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001093
Willy Tarreaue8746a02018-11-12 08:45:00 +01001094 kern user mail daemon auth syslog lpr news
1095 uucp cron auth2 ftp ntp audit alert cron2
1096 local0 local1 local2 local3 local4 local5 local6 local7
1097
Willy Tarreauc1b06452018-11-12 11:57:56 +01001098 Note that the facility is ignored for the "short" and "raw"
1099 formats, but still required as a positional field. It is
1100 recommended to use "daemon" in this case to make it clear that
1101 it's only supposed to be used locally.
Willy Tarreau6a06a402007-07-15 20:15:28 +02001102
1103 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001104 all messages are sent. If a maximum level is specified, only messages with a
1105 severity at least as important as this level will be sent. An optional minimum
1106 level can be specified. If it is set, logs emitted with a more severe level
1107 than this one will be capped to this level. This is used to avoid sending
1108 "emerg" messages on all terminals on some default syslog configurations.
1109 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001110
Cyril Bontédc4d9032012-04-08 21:57:39 +02001111 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +02001112
Joe Williamsdf5b38f2010-12-29 17:05:48 +01001113log-send-hostname [<string>]
1114 Sets the hostname field in the syslog header. If optional "string" parameter
1115 is set the header is set to the string contents, otherwise uses the hostname
1116 of the system. Generally used if one is not relaying logs through an
1117 intermediate syslog server or for simply customizing the hostname printed in
1118 the logs.
1119
Kevinm48936af2010-12-22 16:08:21 +00001120log-tag <string>
1121 Sets the tag field in the syslog header to this string. It defaults to the
1122 program name as launched from the command line, which usually is "haproxy".
1123 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +01001124 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +00001125
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001126lua-load <file>
1127 This global directive loads and executes a Lua file. This directive can be
1128 used multiple times.
1129
Tim Duesterhusdd74b5f2020-01-12 13:55:40 +01001130lua-prepend-path <string> [<type>]
1131 Prepends the given string followed by a semicolon to Lua's package.<type>
1132 variable.
1133 <type> must either be "path" or "cpath". If <type> is not given it defaults
1134 to "path".
1135
1136 Lua's paths are semicolon delimited lists of patterns that specify how the
1137 `require` function attempts to find the source file of a library. Question
1138 marks (?) within a pattern will be replaced by module name. The path is
1139 evaluated left to right. This implies that paths that are prepended later
1140 will be checked earlier.
1141
1142 As an example by specifying the following path:
1143
1144 lua-prepend-path /usr/share/haproxy-lua/?/init.lua
1145 lua-prepend-path /usr/share/haproxy-lua/?.lua
1146
1147 When `require "example"` is being called Lua will first attempt to load the
1148 /usr/share/haproxy-lua/example.lua script, if that does not exist the
1149 /usr/share/haproxy-lua/example/init.lua will be attempted and the default
1150 paths if that does not exist either.
1151
1152 See https://www.lua.org/pil/8.1.html for the details within the Lua
1153 documentation.
1154
William Lallemand4cfede82017-11-24 22:02:34 +01001155master-worker [no-exit-on-failure]
William Lallemande202b1e2017-06-01 17:38:56 +02001156 Master-worker mode. It is equivalent to the command line "-W" argument.
1157 This mode will launch a "master" which will monitor the "workers". Using
1158 this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001159 the master. The master-worker mode is compatible either with the foreground
William Lallemande202b1e2017-06-01 17:38:56 +02001160 or daemon mode. It is recommended to use this mode with multiprocess and
1161 systemd.
William Lallemand4cfede82017-11-24 22:02:34 +01001162 By default, if a worker exits with a bad return code, in the case of a
1163 segfault for example, all workers will be killed, and the master will leave.
1164 It is convenient to combine this behavior with Restart=on-failure in a
1165 systemd unit file in order to relaunch the whole process. If you don't want
1166 this behavior, you must use the keyword "no-exit-on-failure".
William Lallemande202b1e2017-06-01 17:38:56 +02001167
William Lallemand4cfede82017-11-24 22:02:34 +01001168 See also "-W" in the management guide.
William Lallemande202b1e2017-06-01 17:38:56 +02001169
William Lallemand27edc4b2019-05-07 17:49:33 +02001170mworker-max-reloads <number>
1171 In master-worker mode, this option limits the number of time a worker can
John Roeslerfb2fce12019-07-10 15:45:51 -05001172 survive to a reload. If the worker did not leave after a reload, once its
William Lallemand27edc4b2019-05-07 17:49:33 +02001173 number of reloads is greater than this number, the worker will receive a
1174 SIGTERM. This option helps to keep under control the number of workers.
1175 See also "show proc" in the Management Guide.
1176
Willy Tarreau6a06a402007-07-15 20:15:28 +02001177nbproc <number>
1178 Creates <number> processes when going daemon. This requires the "daemon"
1179 mode. By default, only one process is created, which is the recommended mode
1180 of operation. For systems limited to small sets of file descriptors per
Willy Tarreau149ab772019-01-26 14:27:06 +01001181 process, it may be needed to fork multiple daemons. When set to a value
1182 larger than 1, threads are automatically disabled. USING MULTIPLE PROCESSES
Willy Tarreau1f672a82019-01-26 14:20:55 +01001183 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon" and
1184 "nbthread".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001185
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001186nbthread <number>
1187 This setting is only available when support for threads was built in. It
Willy Tarreau26f6ae12019-02-02 12:56:15 +01001188 makes haproxy run on <number> threads. This is exclusive with "nbproc". While
1189 "nbproc" historically used to be the only way to use multiple processors, it
1190 also involved a number of shortcomings related to the lack of synchronization
1191 between processes (health-checks, peers, stick-tables, stats, ...) which do
1192 not affect threads. As such, any modern configuration is strongly encouraged
Willy Tarreau149ab772019-01-26 14:27:06 +01001193 to migrate away from "nbproc" to "nbthread". "nbthread" also works when
1194 HAProxy is started in foreground. On some platforms supporting CPU affinity,
1195 when nbproc is not used, the default "nbthread" value is automatically set to
1196 the number of CPUs the process is bound to upon startup. This means that the
1197 thread count can easily be adjusted from the calling process using commands
1198 like "taskset" or "cpuset". Otherwise, this value defaults to 1. The default
1199 value is reported in the output of "haproxy -vv". See also "nbproc".
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001200
Willy Tarreau6a06a402007-07-15 20:15:28 +02001201pidfile <pidfile>
MIZUTA Takeshic32f3942020-08-26 13:46:19 +09001202 Writes PIDs of all daemons into file <pidfile> when daemon mode or writes PID
1203 of master process into file <pidfile> when master-worker mode. This option is
1204 equivalent to the "-p" command line argument. The file must be accessible to
1205 the user starting the process. See also "daemon" and "master-worker".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001206
Willy Tarreau119e50e2020-05-22 13:53:29 +02001207pp2-never-send-local
1208 A bug in the PROXY protocol v2 implementation was present in HAProxy up to
1209 version 2.1, causing it to emit a PROXY command instead of a LOCAL command
1210 for health checks. This is particularly minor but confuses some servers'
1211 logs. Sadly, the bug was discovered very late and revealed that some servers
1212 which possibly only tested their PROXY protocol implementation against
1213 HAProxy fail to properly handle the LOCAL command, and permanently remain in
1214 the "down" state when HAProxy checks them. When this happens, it is possible
1215 to enable this global option to revert to the older (bogus) behavior for the
1216 time it takes to contact the affected components' vendors and get them fixed.
1217 This option is disabled by default and acts on all servers having the
1218 "send-proxy-v2" statement.
1219
Willy Tarreau1d549722016-02-16 12:41:57 +01001220presetenv <name> <value>
1221 Sets environment variable <name> to value <value>. If the variable exists, it
1222 is NOT overwritten. The changes immediately take effect so that the next line
1223 in the configuration file sees the new value. See also "setenv", "resetenv",
1224 and "unsetenv".
1225
1226resetenv [<name> ...]
1227 Removes all environment variables except the ones specified in argument. It
1228 allows to use a clean controlled environment before setting new values with
1229 setenv or unsetenv. Please note that some internal functions may make use of
1230 some environment variables, such as time manipulation functions, but also
1231 OpenSSL or even external checks. This must be used with extreme care and only
1232 after complete validation. The changes immediately take effect so that the
1233 next line in the configuration file sees the new environment. See also
1234 "setenv", "presetenv", and "unsetenv".
1235
Christopher Fauletff4121f2017-11-22 16:38:49 +01001236stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +02001237 Limits the stats socket to a certain set of processes numbers. By default the
1238 stats socket is bound to all processes, causing a warning to be emitted when
1239 nbproc is greater than 1 because there is no way to select the target process
1240 when connecting. However, by using this setting, it becomes possible to pin
1241 the stats socket to a specific set of processes, typically the first one. The
1242 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001243 the number of processes used. The maximum process ID depends on the machine's
Christopher Fauletff4121f2017-11-22 16:38:49 +01001244 word size (32 or 64). Ranges can be partially defined. The higher bound can
1245 be omitted. In such case, it is replaced by the corresponding maximum
1246 value. A better option consists in using the "process" setting of the "stats
1247 socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +02001248
Baptiste Assmann5626f482015-08-23 10:00:10 +02001249server-state-base <directory>
1250 Specifies the directory prefix to be prepended in front of all servers state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001251 file names which do not start with a '/'. See also "server-state-file",
1252 "load-server-state-from-file" and "server-state-file-name".
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +02001253
1254server-state-file <file>
1255 Specifies the path to the file containing state of servers. If the path starts
1256 with a slash ('/'), it is considered absolute, otherwise it is considered
1257 relative to the directory specified using "server-state-base" (if set) or to
1258 the current directory. Before reloading HAProxy, it is possible to save the
1259 servers' current state using the stats command "show servers state". The
1260 output of this command must be written in the file pointed by <file>. When
1261 starting up, before handling traffic, HAProxy will read, load and apply state
1262 for each server found in the file and available in its current running
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001263 configuration. See also "server-state-base" and "show servers state",
1264 "load-server-state-from-file" and "server-state-file-name"
Baptiste Assmann5626f482015-08-23 10:00:10 +02001265
Willy Tarreau1d549722016-02-16 12:41:57 +01001266setenv <name> <value>
1267 Sets environment variable <name> to value <value>. If the variable exists, it
1268 is overwritten. The changes immediately take effect so that the next line in
1269 the configuration file sees the new value. See also "presetenv", "resetenv",
1270 and "unsetenv".
1271
Willy Tarreau636848a2019-04-15 19:38:50 +02001272set-dumpable
1273 This option is better left disabled by default and enabled only upon a
William Dauchyec730982019-10-27 20:08:10 +01001274 developer's request. If it has been enabled, it may still be forcibly
1275 disabled by prefixing it with the "no" keyword. It has no impact on
1276 performance nor stability but will try hard to re-enable core dumps that were
1277 possibly disabled by file size limitations (ulimit -f), core size limitations
1278 (ulimit -c), or "dumpability" of a process after changing its UID/GID (such
1279 as /proc/sys/fs/suid_dumpable on Linux). Core dumps might still be limited by
1280 the current directory's permissions (check what directory the file is started
1281 from), the chroot directory's permission (it may be needed to temporarily
1282 disable the chroot directive or to move it to a dedicated writable location),
1283 or any other system-specific constraint. For example, some Linux flavours are
1284 notorious for replacing the default core file with a path to an executable
1285 not even installed on the system (check /proc/sys/kernel/core_pattern). Often,
1286 simply writing "core", "core.%p" or "/var/log/core/core.%p" addresses the
1287 issue. When trying to enable this option waiting for a rare issue to
1288 re-appear, it's often a good idea to first try to obtain such a dump by
1289 issuing, for example, "kill -11" to the haproxy process and verify that it
1290 leaves a core where expected when dying.
Willy Tarreau636848a2019-04-15 19:38:50 +02001291
Willy Tarreau610f04b2014-02-13 11:36:41 +01001292ssl-default-bind-ciphers <ciphers>
1293 This setting is only available when support for OpenSSL was built in. It sets
1294 the default string describing the list of cipher algorithms ("cipher suite")
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001295 that are negotiated during the SSL/TLS handshake up to TLSv1.2 for all
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001296 "bind" lines which do not explicitly define theirs. The format of the string
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001297 is defined in "man 1 ciphers" from OpenSSL man pages. For background
1298 information and recommendations see e.g.
1299 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1300 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
1301 cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword.
1302 Please check the "bind" keyword for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001303
1304ssl-default-bind-ciphersuites <ciphersuites>
1305 This setting is only available when support for OpenSSL was built in and
1306 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
1307 describing the list of cipher algorithms ("cipher suite") that are negotiated
1308 during the TLSv1.3 handshake for all "bind" lines which do not explicitly define
1309 theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001310 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1311 cipher configuration for TLSv1.2 and earlier, please check the
1312 "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001313 information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001314
Jerome Magninb203ff62020-04-03 15:28:22 +02001315ssl-default-bind-curves <curves>
1316 This setting is only available when support for OpenSSL was built in. It sets
1317 the default string describing the list of elliptic curves algorithms ("curve
1318 suite") that are negotiated during the SSL/TLS handshake with ECDHE. The format
1319 of the string is a colon-delimited list of curve name.
1320 Please check the "bind" keyword for more information.
1321
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001322ssl-default-bind-options [<option>]...
1323 This setting is only available when support for OpenSSL was built in. It sets
1324 default ssl-options to force on all "bind" lines. Please check the "bind"
1325 keyword to see available options.
1326
1327 Example:
1328 global
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +02001329 ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001330
Willy Tarreau610f04b2014-02-13 11:36:41 +01001331ssl-default-server-ciphers <ciphers>
1332 This setting is only available when support for OpenSSL was built in. It
1333 sets the default string describing the list of cipher algorithms that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001334 negotiated during the SSL/TLS handshake up to TLSv1.2 with the server,
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001335 for all "server" lines which do not explicitly define theirs. The format of
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001336 the string is defined in "man 1 ciphers" from OpenSSL man pages. For background
1337 information and recommendations see e.g.
1338 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1339 (https://mozilla.github.io/server-side-tls/ssl-config-generator/).
1340 For TLSv1.3 cipher configuration, please check the
1341 "ssl-default-server-ciphersuites" keyword. Please check the "server" keyword
1342 for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001343
1344ssl-default-server-ciphersuites <ciphersuites>
1345 This setting is only available when support for OpenSSL was built in and
1346 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
1347 string describing the list of cipher algorithms that are negotiated during
1348 the TLSv1.3 handshake with the server, for all "server" lines which do not
1349 explicitly define theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001350 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1351 cipher configuration for TLSv1.2 and earlier, please check the
1352 "ssl-default-server-ciphers" keyword. Please check the "server" keyword for
1353 more information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001354
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001355ssl-default-server-options [<option>]...
1356 This setting is only available when support for OpenSSL was built in. It sets
1357 default ssl-options to force on all "server" lines. Please check the "server"
1358 keyword to see available options.
1359
Remi Gacogne47783ef2015-05-29 15:53:22 +02001360ssl-dh-param-file <file>
1361 This setting is only available when support for OpenSSL was built in. It sets
1362 the default DH parameters that are used during the SSL/TLS handshake when
1363 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
Davor Ocelice9ed2812017-12-25 17:49:28 +01001364 which do not explicitly define theirs. It will be overridden by custom DH
Remi Gacogne47783ef2015-05-29 15:53:22 +02001365 parameters found in a bind certificate file if any. If custom DH parameters
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001366 are not specified either by using ssl-dh-param-file or by setting them
1367 directly in the certificate file, pre-generated DH parameters of the size
1368 specified by tune.ssl.default-dh-param will be used. Custom parameters are
1369 known to be more secure and therefore their use is recommended.
Remi Gacogne47783ef2015-05-29 15:53:22 +02001370 Custom DH parameters may be generated by using the OpenSSL command
1371 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
1372 parameters should not be considered secure anymore.
1373
William Lallemand4c5adbf2020-02-24 14:23:22 +01001374ssl-load-extra-files <none|all|bundle|sctl|ocsp|issuer|key>*
William Lallemand3af48e72020-02-03 17:15:52 +01001375 This setting alters the way HAProxy will look for unspecified files during
Jerome Magnin587be9c2020-09-07 11:55:57 +02001376 the loading of the SSL certificates associated to "bind" lines. It does not
1377 apply to certificates used for client authentication on "server" lines.
William Lallemand3af48e72020-02-03 17:15:52 +01001378
1379 By default, HAProxy discovers automatically a lot of files not specified in
1380 the configuration, and you may want to disable this behavior if you want to
1381 optimize the startup time.
1382
1383 "none": Only load the files specified in the configuration. Don't try to load
1384 a certificate bundle if the file does not exist. In the case of a directory,
1385 it won't try to bundle the certificates if they have the same basename.
1386
1387 "all": This is the default behavior, it will try to load everything,
William Lallemand4c5adbf2020-02-24 14:23:22 +01001388 bundles, sctl, ocsp, issuer, key.
William Lallemand3af48e72020-02-03 17:15:52 +01001389
1390 "bundle": When a file specified in the configuration does not exist, HAProxy
1391 will try to load a certificate bundle. This is done by looking for
William Lallemand98d215e2020-09-16 17:42:37 +02001392 <basename>.rsa, .ecdsa and .dsa.
1393 The multi-certificates bundles were introduced with OpenSSL 1.0.2 and were
1394 the only way back then to serve an ECDSA certificate and a RSA one with the
1395 same SNI. Since HAProxy 2.3 it does not use the OpenSSL bundle but it
1396 loads every certificates separately to emulate this behavior. At least
1397 OpenSSL 1.1.1 is required. It is recommended to specify all the certificates
1398 in the configuration instead of using the bundle feature.
William Lallemand3af48e72020-02-03 17:15:52 +01001399
1400 "sctl": Try to load "<basename>.sctl" for each crt keyword.
1401
1402 "ocsp": Try to load "<basename>.ocsp" for each crt keyword.
1403
1404 "issuer": Try to load "<basename>.issuer" if the issuer of the OCSP file is
1405 not provided in the PEM file.
1406
William Lallemand4c5adbf2020-02-24 14:23:22 +01001407 "key": If the private key was not provided by the PEM file, try to load a
1408 file "<basename>.key" containing a private key.
1409
William Lallemand3af48e72020-02-03 17:15:52 +01001410 The default behavior is "all".
1411
1412 Example:
1413 ssl-load-extra-files bundle sctl
1414 ssl-load-extra-files sctl ocsp issuer
1415 ssl-load-extra-files none
1416
1417 See also: "crt", section 5.1 about bind options.
1418
Emeric Brun850efd52014-01-29 12:24:34 +01001419ssl-server-verify [none|required]
1420 The default behavior for SSL verify on servers side. If specified to 'none',
1421 servers certificates are not verified. The default is 'required' except if
1422 forced using cmdline option '-dV'.
1423
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001424ssl-skip-self-issued-ca
Daniel Corbett67a82712020-07-06 23:01:19 -04001425 Self issued CA, aka x509 root CA, is the anchor for chain validation: as a
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001426 server is useless to send it, client must have it. Standard configuration
1427 need to not include such CA in PEM file. This option allows you to keep such
1428 CA in PEM file without sending it to the client. Use case is to provide
1429 issuer for ocsp without the need for '.issuer' file and be able to share it
1430 with 'issuers-chain-path'. This concerns all certificates without intermediate
1431 certificates. It's useless for BoringSSL, .issuer is ignored because ocsp
William Lallemand9a1d8392020-08-10 17:28:23 +02001432 bits does not need it. Requires at least OpenSSL 1.0.2.
Emmanuel Hocdetc3b7e742020-04-22 11:06:19 +02001433
Willy Tarreauabb175f2012-09-24 12:43:26 +02001434stats socket [<address:port>|<path>] [param*]
1435 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
1436 Connections to this socket will return various statistics outputs and even
1437 allow some commands to be issued to change some runtime settings. Please
Willy Tarreau1af20c72017-06-23 16:01:14 +02001438 consult section 9.3 "Unix Socket commands" of Management Guide for more
Kevin Decherf949c7202015-10-13 23:26:44 +02001439 details.
Willy Tarreau6162db22009-10-10 17:13:00 +02001440
Willy Tarreauabb175f2012-09-24 12:43:26 +02001441 All parameters supported by "bind" lines are supported, for instance to
1442 restrict access to some users or their access rights. Please consult
1443 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001444
1445stats timeout <timeout, in milliseconds>
1446 The default timeout on the stats socket is set to 10 seconds. It is possible
1447 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +01001448 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001449
1450stats maxconn <connections>
1451 By default, the stats socket is limited to 10 concurrent connections. It is
1452 possible to change this value with "stats maxconn".
1453
Willy Tarreau6a06a402007-07-15 20:15:28 +02001454uid <number>
1455 Changes the process' user ID to <number>. It is recommended that the user ID
1456 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
1457 be started with superuser privileges in order to be able to switch to another
1458 one. See also "gid" and "user".
1459
1460ulimit-n <number>
1461 Sets the maximum number of per-process file-descriptors to <number>. By
1462 default, it is automatically computed, so it is recommended not to use this
1463 option.
1464
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001465unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
1466 [ group <group> ] [ gid <gid> ]
1467
1468 Fixes common settings to UNIX listening sockets declared in "bind" statements.
1469 This is mainly used to simplify declaration of those UNIX sockets and reduce
1470 the risk of errors, since those settings are most commonly required but are
1471 also process-specific. The <prefix> setting can be used to force all socket
1472 path to be relative to that directory. This might be needed to access another
1473 component's chroot. Note that those paths are resolved before haproxy chroots
1474 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
1475 all have the same meaning as their homonyms used by the "bind" statement. If
1476 both are specified, the "bind" statement has priority, meaning that the
1477 "unix-bind" settings may be seen as process-wide default settings.
1478
Willy Tarreau1d549722016-02-16 12:41:57 +01001479unsetenv [<name> ...]
1480 Removes environment variables specified in arguments. This can be useful to
1481 hide some sensitive information that are occasionally inherited from the
1482 user's environment during some operations. Variables which did not exist are
1483 silently ignored so that after the operation, it is certain that none of
1484 these variables remain. The changes immediately take effect so that the next
1485 line in the configuration file will not see these variables. See also
1486 "setenv", "presetenv", and "resetenv".
1487
Willy Tarreau6a06a402007-07-15 20:15:28 +02001488user <user name>
1489 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
1490 See also "uid" and "group".
1491
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02001492node <name>
1493 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
1494
1495 This statement is useful in HA configurations where two or more processes or
1496 servers share the same IP address. By setting a different node-name on all
1497 nodes, it becomes easy to immediately spot what server is handling the
1498 traffic.
1499
1500description <text>
1501 Add a text that describes the instance.
1502
1503 Please note that it is required to escape certain characters (# for example)
1504 and this text is inserted into a html page so you should avoid using
1505 "<" and ">" characters.
1506
Thomas Holmesdb04f192015-05-18 13:21:39 +0100150751degrees-data-file <file path>
1508 The path of the 51Degrees data file to provide device detection services. The
Davor Ocelice9ed2812017-12-25 17:49:28 +01001509 file should be unzipped and accessible by HAProxy with relevant permissions.
Thomas Holmesdb04f192015-05-18 13:21:39 +01001510
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001511 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001512 compiled with USE_51DEGREES.
1513
Ben Shillitof25e8e52016-12-02 14:25:37 +0000151451degrees-property-name-list [<string> ...]
Thomas Holmesdb04f192015-05-18 13:21:39 +01001515 A list of 51Degrees property names to be load from the dataset. A full list
1516 of names is available on the 51Degrees website:
1517 https://51degrees.com/resources/property-dictionary
1518
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001519 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001520 compiled with USE_51DEGREES.
1521
Dragan Dosen93b38d92015-06-29 16:43:25 +0200152251degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +01001523 A char that will be appended to every property value in a response header
1524 containing 51Degrees results. If not set that will be set as ','.
1525
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001526 Please note that this option is only available when haproxy has been
1527 compiled with USE_51DEGREES.
1528
152951degrees-cache-size <number>
1530 Sets the size of the 51Degrees converter cache to <number> entries. This
1531 is an LRU cache which reminds previous device detections and their results.
1532 By default, this cache is disabled.
1533
1534 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001535 compiled with USE_51DEGREES.
1536
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001537wurfl-data-file <file path>
1538 The path of the WURFL data file to provide device detection services. The
1539 file should be accessible by HAProxy with relevant permissions.
1540
1541 Please note that this option is only available when haproxy has been compiled
1542 with USE_WURFL=1.
1543
1544wurfl-information-list [<capability>]*
1545 A space-delimited list of WURFL capabilities, virtual capabilities, property
1546 names we plan to use in injected headers. A full list of capability and
1547 virtual capability names is available on the Scientiamobile website :
1548
1549 https://www.scientiamobile.com/wurflCapability
1550
1551 Valid WURFL properties are:
1552 - wurfl_id Contains the device ID of the matched device.
1553
1554 - wurfl_root_id Contains the device root ID of the matched
1555 device.
1556
1557 - wurfl_isdevroot Tells if the matched device is a root device.
1558 Possible values are "TRUE" or "FALSE".
1559
1560 - wurfl_useragent The original useragent coming with this
1561 particular web request.
1562
1563 - wurfl_api_version Contains a string representing the currently
1564 used Libwurfl API version.
1565
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001566 - wurfl_info A string containing information on the parsed
1567 wurfl.xml and its full path.
1568
1569 - wurfl_last_load_time Contains the UNIX timestamp of the last time
1570 WURFL has been loaded successfully.
1571
1572 - wurfl_normalized_useragent The normalized useragent.
1573
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001574 Please note that this option is only available when haproxy has been compiled
1575 with USE_WURFL=1.
1576
1577wurfl-information-list-separator <char>
1578 A char that will be used to separate values in a response header containing
1579 WURFL results. If not set that a comma (',') will be used by default.
1580
1581 Please note that this option is only available when haproxy has been compiled
1582 with USE_WURFL=1.
1583
1584wurfl-patch-file [<file path>]
1585 A list of WURFL patch file paths. Note that patches are loaded during startup
1586 thus before the chroot.
1587
1588 Please note that this option is only available when haproxy has been compiled
1589 with USE_WURFL=1.
1590
paulborilebad132c2019-04-18 11:57:04 +02001591wurfl-cache-size <size>
1592 Sets the WURFL Useragent cache size. For faster lookups, already processed user
1593 agents are kept in a LRU cache :
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001594 - "0" : no cache is used.
paulborilebad132c2019-04-18 11:57:04 +02001595 - <size> : size of lru cache in elements.
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001596
1597 Please note that this option is only available when haproxy has been compiled
1598 with USE_WURFL=1.
1599
William Dauchy0fec3ab2019-10-27 20:08:11 +01001600strict-limits
William Dauchya5194602020-03-28 19:29:58 +01001601 Makes process fail at startup when a setrlimit fails. Haproxy tries to set the
1602 best setrlimit according to what has been calculated. If it fails, it will
1603 emit a warning. This option is here to guarantee an explicit failure of
1604 haproxy when those limits fail. It is enabled by default. It may still be
1605 forcibly disabled by prefixing it with the "no" keyword.
William Dauchy0fec3ab2019-10-27 20:08:11 +01001606
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016073.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +02001608-----------------------
1609
Willy Tarreaubeb859a2018-11-22 18:07:59 +01001610busy-polling
1611 In some situations, especially when dealing with low latency on processors
1612 supporting a variable frequency or when running inside virtual machines, each
1613 time the process waits for an I/O using the poller, the processor goes back
1614 to sleep or is offered to another VM for a long time, and it causes
1615 excessively high latencies. This option provides a solution preventing the
1616 processor from sleeping by always using a null timeout on the pollers. This
1617 results in a significant latency reduction (30 to 100 microseconds observed)
1618 at the expense of a risk to overheat the processor. It may even be used with
1619 threads, in which case improperly bound threads may heavily conflict,
1620 resulting in a worse performance and high values for the CPU stolen fields
1621 in "show info" output, indicating which threads are misconfigured. It is
1622 important not to let the process run on the same processor as the network
1623 interrupts when this option is used. It is also better to avoid using it on
1624 multiple CPU threads sharing the same core. This option is disabled by
1625 default. If it has been enabled, it may still be forcibly disabled by
1626 prefixing it with the "no" keyword. It is ignored by the "select" and
1627 "poll" pollers.
1628
William Dauchy3894d972019-12-28 15:36:02 +01001629 This option is automatically disabled on old processes in the context of
1630 seamless reload; it avoids too much cpu conflicts when multiple processes
1631 stay around for some time waiting for the end of their current connections.
1632
Willy Tarreau1746eec2014-04-25 10:46:47 +02001633max-spread-checks <delay in milliseconds>
1634 By default, haproxy tries to spread the start of health checks across the
1635 smallest health check interval of all the servers in a farm. The principle is
1636 to avoid hammering services running on the same server. But when using large
1637 check intervals (10 seconds or more), the last servers in the farm take some
1638 time before starting to be tested, which can be a problem. This parameter is
1639 used to enforce an upper bound on delay between the first and the last check,
1640 even if the servers' check intervals are larger. When servers run with
1641 shorter intervals, their intervals will be respected though.
1642
Willy Tarreau6a06a402007-07-15 20:15:28 +02001643maxconn <number>
1644 Sets the maximum per-process number of concurrent connections to <number>. It
1645 is equivalent to the command-line argument "-n". Proxies will stop accepting
1646 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +02001647 automatically adjusted according to this value. See also "ulimit-n". Note:
1648 the "select" poller cannot reliably use more than 1024 file descriptors on
1649 some platforms. If your platform only supports select and reports "select
1650 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaub28f3442019-03-04 08:13:43 +01001651 below 500 in general). If this value is not set, it will automatically be
1652 calculated based on the current file descriptors limit reported by the
1653 "ulimit -n" command, possibly reduced to a lower value if a memory limit
1654 is enforced, based on the buffer size, memory allocated to compression, SSL
1655 cache size, and use or not of SSL and the associated maxsslconn (which can
1656 also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +02001657
Willy Tarreau81c25d02011-09-07 15:17:21 +02001658maxconnrate <number>
1659 Sets the maximum per-process number of connections per second to <number>.
1660 Proxies will stop accepting connections when this limit is reached. It can be
1661 used to limit the global capacity regardless of each frontend capacity. It is
1662 important to note that this can only be used as a service protection measure,
1663 as there will not necessarily be a fair share between frontends when the
1664 limit is reached, so it's a good idea to also limit each frontend to some
1665 value close to its expected share. Also, lowering tune.maxaccept can improve
1666 fairness.
1667
William Lallemandd85f9172012-11-09 17:05:39 +01001668maxcomprate <number>
1669 Sets the maximum per-process input compression rate to <number> kilobytes
Davor Ocelice9ed2812017-12-25 17:49:28 +01001670 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +01001671 level will be decreased during the session. If the maximum is reached at the
1672 beginning of a session, the session will not compress at all. If the maximum
1673 is not reached, the compression level will be increased up to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001674 tune.comp.maxlevel. A value of zero means there is no limit, this is the
William Lallemandd85f9172012-11-09 17:05:39 +01001675 default value.
1676
William Lallemand072a2bf2012-11-20 17:01:01 +01001677maxcompcpuusage <number>
1678 Sets the maximum CPU usage HAProxy can reach before stopping the compression
1679 for new requests or decreasing the compression level of current requests.
1680 It works like 'maxcomprate' but measures CPU usage instead of incoming data
1681 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
1682 case of multiple processes (nbproc > 1), each process manages its individual
1683 usage. A value of 100 disable the limit. The default value is 100. Setting
1684 a lower value will prevent the compression work from slowing the whole
1685 process down and from introducing high latencies.
1686
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001687maxpipes <number>
1688 Sets the maximum per-process number of pipes to <number>. Currently, pipes
1689 are only used by kernel-based tcp splicing. Since a pipe contains two file
1690 descriptors, the "ulimit-n" value will be increased accordingly. The default
1691 value is maxconn/4, which seems to be more than enough for most heavy usages.
1692 The splice code dynamically allocates and releases pipes, and can fall back
1693 to standard copy, so setting this value too low may only impact performance.
1694
Willy Tarreau93e7c002013-10-07 18:51:07 +02001695maxsessrate <number>
1696 Sets the maximum per-process number of sessions per second to <number>.
1697 Proxies will stop accepting connections when this limit is reached. It can be
1698 used to limit the global capacity regardless of each frontend capacity. It is
1699 important to note that this can only be used as a service protection measure,
1700 as there will not necessarily be a fair share between frontends when the
1701 limit is reached, so it's a good idea to also limit each frontend to some
1702 value close to its expected share. Also, lowering tune.maxaccept can improve
1703 fairness.
1704
Willy Tarreau403edff2012-09-06 11:58:37 +02001705maxsslconn <number>
1706 Sets the maximum per-process number of concurrent SSL connections to
1707 <number>. By default there is no SSL-specific limit, which means that the
1708 global maxconn setting will apply to all connections. Setting this limit
1709 avoids having openssl use too much memory and crash when malloc returns NULL
1710 (since it unfortunately does not reliably check for such conditions). Note
1711 that the limit applies both to incoming and outgoing connections, so one
1712 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +01001713 If this value is not set, but a memory limit is enforced, this value will be
1714 automatically computed based on the memory limit, maxconn, the buffer size,
1715 memory allocated to compression, SSL cache size, and use of SSL in either
1716 frontends, backends or both. If neither maxconn nor maxsslconn are specified
1717 when there is a memory limit, haproxy will automatically adjust these values
1718 so that 100% of the connections can be made over SSL with no risk, and will
1719 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +02001720
Willy Tarreaue43d5322013-10-07 20:01:52 +02001721maxsslrate <number>
1722 Sets the maximum per-process number of SSL sessions per second to <number>.
1723 SSL listeners will stop accepting connections when this limit is reached. It
1724 can be used to limit the global SSL CPU usage regardless of each frontend
1725 capacity. It is important to note that this can only be used as a service
1726 protection measure, as there will not necessarily be a fair share between
1727 frontends when the limit is reached, so it's a good idea to also limit each
1728 frontend to some value close to its expected share. It is also important to
1729 note that the sessions are accounted before they enter the SSL stack and not
1730 after, which also protects the stack against bad handshakes. Also, lowering
1731 tune.maxaccept can improve fairness.
1732
William Lallemand9d5f5482012-11-07 16:12:57 +01001733maxzlibmem <number>
1734 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
1735 When the maximum amount is reached, future sessions will not compress as long
1736 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01001737 The default value is 0. The value is available in bytes on the UNIX socket
1738 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
1739 "ZlibMemUsage" in bytes.
1740
Willy Tarreau6a06a402007-07-15 20:15:28 +02001741noepoll
1742 Disables the use of the "epoll" event polling system on Linux. It is
1743 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001744 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001745
1746nokqueue
1747 Disables the use of the "kqueue" event polling system on BSD. It is
1748 equivalent to the command-line argument "-dk". The next polling system
1749 used will generally be "poll". See also "nopoll".
1750
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001751noevports
1752 Disables the use of the event ports event polling system on SunOS systems
1753 derived from Solaris 10 and later. It is equivalent to the command-line
1754 argument "-dv". The next polling system used will generally be "poll". See
1755 also "nopoll".
1756
Willy Tarreau6a06a402007-07-15 20:15:28 +02001757nopoll
1758 Disables the use of the "poll" event polling system. It is equivalent to the
1759 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001760 It should never be needed to disable "poll" since it's available on all
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001761 platforms supported by HAProxy. See also "nokqueue", "noepoll" and
1762 "noevports".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001763
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001764nosplice
1765 Disables the use of kernel tcp splicing between sockets on Linux. It is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001766 equivalent to the command line argument "-dS". Data will then be copied
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001767 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001768 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001769 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
1770 be used. This option makes it easier to globally disable kernel splicing in
1771 case of doubt. See also "option splice-auto", "option splice-request" and
1772 "option splice-response".
1773
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001774nogetaddrinfo
1775 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
1776 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
1777
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00001778noreuseport
1779 Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the
1780 command line argument "-dR".
1781
Willy Tarreaud2d33482019-04-25 17:09:07 +02001782profiling.tasks { auto | on | off }
1783 Enables ('on') or disables ('off') per-task CPU profiling. When set to 'auto'
1784 the profiling automatically turns on a thread when it starts to suffer from
1785 an average latency of 1000 microseconds or higher as reported in the
1786 "avg_loop_us" activity field, and automatically turns off when the latency
John Roeslerfb2fce12019-07-10 15:45:51 -05001787 returns below 990 microseconds (this value is an average over the last 1024
Willy Tarreaud2d33482019-04-25 17:09:07 +02001788 loops so it does not vary quickly and tends to significantly smooth short
1789 spikes). It may also spontaneously trigger from time to time on overloaded
1790 systems, containers, or virtual machines, or when the system swaps (which
1791 must absolutely never happen on a load balancer).
1792
1793 CPU profiling per task can be very convenient to report where the time is
1794 spent and which requests have what effect on which other request. Enabling
1795 it will typically affect the overall's performance by less than 1%, thus it
1796 is recommended to leave it to the default 'auto' value so that it only
1797 operates when a problem is identified. This feature requires a system
Willy Tarreau75c62c22018-11-22 11:02:09 +01001798 supporting the clock_gettime(2) syscall with clock identifiers
1799 CLOCK_MONOTONIC and CLOCK_THREAD_CPUTIME_ID, otherwise the reported time will
1800 be zero. This option may be changed at run time using "set profiling" on the
1801 CLI.
1802
Willy Tarreaufe255b72007-10-14 23:09:26 +02001803spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09001804 Sometimes it is desirable to avoid sending agent and health checks to
1805 servers at exact intervals, for instance when many logical servers are
1806 located on the same physical server. With the help of this parameter, it
1807 becomes possible to add some randomness in the check interval between 0
1808 and +/- 50%. A value between 2 and 5 seems to show good results. The
1809 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02001810
Davor Ocelice9ed2812017-12-25 17:49:28 +01001811ssl-engine <name> [algo <comma-separated list of algorithms>]
Grant Zhang872f9c22017-01-21 01:10:18 +00001812 Sets the OpenSSL engine to <name>. List of valid values for <name> may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01001813 obtained using the command "openssl engine". This statement may be used
Grant Zhang872f9c22017-01-21 01:10:18 +00001814 multiple times, it will simply enable multiple crypto engines. Referencing an
1815 unsupported engine will prevent haproxy from starting. Note that many engines
1816 will lead to lower HTTPS performance than pure software with recent
1817 processors. The optional command "algo" sets the default algorithms an ENGINE
1818 will supply using the OPENSSL function ENGINE_set_default_string(). A value
Davor Ocelice9ed2812017-12-25 17:49:28 +01001819 of "ALL" uses the engine for all cryptographic operations. If no list of
1820 algo is specified then the value of "ALL" is used. A comma-separated list
Grant Zhang872f9c22017-01-21 01:10:18 +00001821 of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND,
1822 CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that
1823 openssl configuration file uses:
1824 https://www.openssl.org/docs/man1.0.2/apps/config.html
1825
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001826ssl-mode-async
1827 Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS
Emeric Brun3854e012017-05-17 20:42:48 +02001828 I/O operations if asynchronous capable SSL engines are used. The current
Emeric Brunb5e42a82017-06-06 12:35:14 +00001829 implementation supports a maximum of 32 engines. The Openssl ASYNC API
1830 doesn't support moving read/write buffers and is not compliant with
1831 haproxy's buffer management. So the asynchronous mode is disabled on
John Roeslerfb2fce12019-07-10 15:45:51 -05001832 read/write operations (it is only enabled during initial and renegotiation
Emeric Brunb5e42a82017-06-06 12:35:14 +00001833 handshakes).
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001834
Willy Tarreau33cb0652014-12-23 22:52:37 +01001835tune.buffers.limit <number>
1836 Sets a hard limit on the number of buffers which may be allocated per process.
1837 The default value is zero which means unlimited. The minimum non-zero value
1838 will always be greater than "tune.buffers.reserve" and should ideally always
1839 be about twice as large. Forcing this value can be particularly useful to
1840 limit the amount of memory a process may take, while retaining a sane
Davor Ocelice9ed2812017-12-25 17:49:28 +01001841 behavior. When this limit is reached, sessions which need a buffer wait for
Willy Tarreau33cb0652014-12-23 22:52:37 +01001842 another one to be released by another session. Since buffers are dynamically
1843 allocated and released, the waiting time is very short and not perceptible
1844 provided that limits remain reasonable. In fact sometimes reducing the limit
1845 may even increase performance by increasing the CPU cache's efficiency. Tests
1846 have shown good results on average HTTP traffic with a limit to 1/10 of the
1847 expected global maxconn setting, which also significantly reduces memory
1848 usage. The memory savings come from the fact that a number of connections
1849 will not allocate 2*tune.bufsize. It is best not to touch this value unless
1850 advised to do so by an haproxy core developer.
1851
Willy Tarreau1058ae72014-12-23 22:40:40 +01001852tune.buffers.reserve <number>
1853 Sets the number of buffers which are pre-allocated and reserved for use only
1854 during memory shortage conditions resulting in failed memory allocations. The
1855 minimum value is 2 and is also the default. There is no reason a user would
1856 want to change this value, it's mostly aimed at haproxy core developers.
1857
Willy Tarreau27a674e2009-08-17 07:23:33 +02001858tune.bufsize <number>
1859 Sets the buffer size to this size (in bytes). Lower values allow more
1860 sessions to coexist in the same amount of RAM, and higher values allow some
1861 applications with very large cookies to work. The default value is 16384 and
1862 can be changed at build time. It is strongly recommended not to change this
1863 from the default value, as very low values will break some services such as
1864 statistics, and values larger than default size will increase memory usage,
1865 possibly causing the system to run out of memory. At least the global maxconn
Willy Tarreau45a66cc2017-11-24 11:28:00 +01001866 parameter should be decreased by the same factor as this one is increased. In
1867 addition, use of HTTP/2 mandates that this value must be 16384 or more. If an
1868 HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04001869 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
Willy Tarreauc77d3642018-12-12 06:19:42 +01001870 than this size, haproxy will return HTTP 502 (Bad Gateway). Note that the
1871 value set using this parameter will automatically be rounded up to the next
1872 multiple of 8 on 32-bit machines and 16 on 64-bit machines.
Willy Tarreau27a674e2009-08-17 07:23:33 +02001873
Willy Tarreau43961d52010-10-04 20:39:20 +02001874tune.chksize <number>
1875 Sets the check buffer size to this size (in bytes). Higher values may help
1876 find string or regex patterns in very large pages, though doing so may imply
1877 more memory and CPU usage. The default value is 16384 and can be changed at
1878 build time. It is not recommended to change this value, but to use better
1879 checks whenever possible.
1880
William Lallemandf3747832012-11-09 12:33:10 +01001881tune.comp.maxlevel <number>
1882 Sets the maximum compression level. The compression level affects CPU
1883 usage during compression. This value affects CPU usage during compression.
1884 Each session using compression initializes the compression algorithm with
1885 this value. The default value is 1.
1886
Willy Tarreauc299e1e2019-02-27 11:35:12 +01001887tune.fail-alloc
1888 If compiled with DEBUG_FAIL_ALLOC, gives the percentage of chances an
1889 allocation attempt fails. Must be between 0 (no failure) and 100 (no
1890 success). This is useful to debug and make sure memory failures are handled
1891 gracefully.
1892
Willy Tarreaubc52bec2020-06-18 08:58:47 +02001893tune.fd.edge-triggered { on | off } [ EXPERIMENTAL ]
1894 Enables ('on') or disables ('off') the edge-triggered polling mode for FDs
1895 that support it. This is currently only support with epoll. It may noticeably
1896 reduce the number of epoll_ctl() calls and slightly improve performance in
1897 certain scenarios. This is still experimental, it may result in frozen
1898 connections if bugs are still present, and is disabled by default.
1899
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02001900tune.h2.header-table-size <number>
1901 Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and
1902 cannot be larger than 65536 bytes. A larger value may help certain clients
1903 send more compact requests, depending on their capabilities. This amount of
1904 memory is consumed for each HTTP/2 connection. It is recommended not to
1905 change it.
1906
Willy Tarreaue6baec02017-07-27 11:45:11 +02001907tune.h2.initial-window-size <number>
1908 Sets the HTTP/2 initial window size, which is the number of bytes the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01001909 can upload before waiting for an acknowledgment from haproxy. This setting
1910 only affects payload contents (i.e. the body of POST requests), not headers.
Willy Tarreaue6baec02017-07-27 11:45:11 +02001911 The default value is 65535, which roughly allows up to 5 Mbps of upload
1912 bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps
1913 over a 1-ms local network. It can make sense to increase this value to allow
1914 faster uploads, or to reduce it to increase fairness when dealing with many
1915 clients. It doesn't affect resource usage.
1916
Willy Tarreau5242ef82017-07-27 11:47:28 +02001917tune.h2.max-concurrent-streams <number>
1918 Sets the HTTP/2 maximum number of concurrent streams per connection (ie the
1919 number of outstanding requests on a single connection). The default value is
1920 100. A larger one may slightly improve page load time for complex sites when
1921 visited over high latency networks, but increases the amount of resources a
1922 single client may allocate. A value of zero disables the limit so a single
1923 client may create as many streams as allocatable by haproxy. It is highly
1924 recommended not to change this value.
1925
Willy Tarreaua24b35c2019-02-21 13:24:36 +01001926tune.h2.max-frame-size <number>
1927 Sets the HTTP/2 maximum frame size that haproxy announces it is willing to
1928 receive to its peers. The default value is the largest between 16384 and the
1929 buffer size (tune.bufsize). In any case, haproxy will not announce support
1930 for frame sizes larger than buffers. The main purpose of this setting is to
1931 allow to limit the maximum frame size setting when using large buffers. Too
1932 large frame sizes might have performance impact or cause some peers to
1933 misbehave. It is highly recommended not to change this value.
1934
Willy Tarreau193b8c62012-11-22 00:17:38 +01001935tune.http.cookielen <number>
1936 Sets the maximum length of captured cookies. This is the maximum value that
1937 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
1938 will automatically be truncated to this one. It is important not to set too
1939 high a value because all cookie captures still allocate this size whatever
1940 their configured value (they share a same pool). This value is per request
1941 per response, so the memory allocated is twice this value per connection.
1942 When not specified, the limit is set to 63 characters. It is recommended not
1943 to change this value.
1944
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001945tune.http.logurilen <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001946 Sets the maximum length of request URI in logs. This prevents truncating long
1947 request URIs with valuable query strings in log lines. This is not related
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001948 to syslog limits. If you increase this limit, you may also increase the
Davor Ocelice9ed2812017-12-25 17:49:28 +01001949 'log ... len yyy' parameter. Your syslog daemon may also need specific
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001950 configuration directives too.
1951 The default value is 1024.
1952
Willy Tarreauac1932d2011-10-24 19:14:41 +02001953tune.http.maxhdr <number>
1954 Sets the maximum number of headers in a request. When a request comes with a
1955 number of headers greater than this value (including the first line), it is
1956 rejected with a "400 Bad Request" status code. Similarly, too large responses
1957 are blocked with "502 Bad Gateway". The default value is 101, which is enough
1958 for all usages, considering that the widely deployed Apache server uses the
1959 same limit. It can be useful to push this limit further to temporarily allow
Christopher Faulet50174f32017-06-21 16:31:35 +02001960 a buggy application to work by the time it gets fixed. The accepted range is
1961 1..32767. Keep in mind that each new header consumes 32bits of memory for
1962 each session, so don't push this limit too high.
Willy Tarreauac1932d2011-10-24 19:14:41 +02001963
Willy Tarreau76cc6992020-07-01 18:49:24 +02001964tune.idle-pool.shared { on | off }
1965 Enables ('on') or disables ('off') sharing of idle connection pools between
1966 threads for a same server. The default is to share them between threads in
1967 order to minimize the number of persistent connections to a server, and to
1968 optimize the connection reuse rate. But to help with debugging or when
1969 suspecting a bug in HAProxy around connection reuse, it can be convenient to
1970 forcefully disable this idle pool sharing between multiple threads, and force
1971 this option to "off". The default is on.
1972
Willy Tarreau7e312732014-02-12 16:35:14 +01001973tune.idletimer <timeout>
1974 Sets the duration after which haproxy will consider that an empty buffer is
1975 probably associated with an idle stream. This is used to optimally adjust
1976 some packet sizes while forwarding large and small data alternatively. The
1977 decision to use splice() or to send large buffers in SSL is modulated by this
1978 parameter. The value is in milliseconds between 0 and 65535. A value of zero
1979 means that haproxy will not try to detect idle streams. The default is 1000,
Davor Ocelice9ed2812017-12-25 17:49:28 +01001980 which seems to correctly detect end user pauses (e.g. read a page before
John Roeslerfb2fce12019-07-10 15:45:51 -05001981 clicking). There should be no reason for changing this value. Please check
Willy Tarreau7e312732014-02-12 16:35:14 +01001982 tune.ssl.maxrecord below.
1983
Willy Tarreau7ac908b2019-02-27 12:02:18 +01001984tune.listener.multi-queue { on | off }
1985 Enables ('on') or disables ('off') the listener's multi-queue accept which
1986 spreads the incoming traffic to all threads a "bind" line is allowed to run
1987 on instead of taking them for itself. This provides a smoother traffic
1988 distribution and scales much better, especially in environments where threads
1989 may be unevenly loaded due to external activity (network interrupts colliding
1990 with one thread for example). This option is enabled by default, but it may
1991 be forcefully disabled for troubleshooting or for situations where it is
1992 estimated that the operating system already provides a good enough
1993 distribution and connections are extremely short-lived.
1994
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001995tune.lua.forced-yield <number>
1996 This directive forces the Lua engine to execute a yield each <number> of
Tim Düsterhus4896c442016-11-29 02:15:19 +01001997 instructions executed. This permits interrupting a long script and allows the
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001998 HAProxy scheduler to process other tasks like accepting connections or
1999 forwarding traffic. The default value is 10000 instructions. If HAProxy often
Davor Ocelice9ed2812017-12-25 17:49:28 +01002000 executes some Lua code but more responsiveness is required, this value can be
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002001 lowered. If the Lua code is quite long and its result is absolutely required
2002 to process the data, the <number> can be increased.
2003
Willy Tarreau32f61e22015-03-18 17:54:59 +01002004tune.lua.maxmem
2005 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
2006 default it is zero which means unlimited. It is important to set a limit to
2007 ensure that a bug in a script will not result in the system running out of
2008 memory.
2009
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002010tune.lua.session-timeout <timeout>
2011 This is the execution timeout for the Lua sessions. This is useful for
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02002012 preventing infinite loops or spending too much time in Lua. This timeout
2013 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002014 not taken in account. The default timeout is 4s.
Thierry FOURNIER90da1912015-03-05 11:17:06 +01002015
2016tune.lua.task-timeout <timeout>
2017 Purpose is the same as "tune.lua.session-timeout", but this timeout is
2018 dedicated to the tasks. By default, this timeout isn't set because a task may
2019 remain alive during of the lifetime of HAProxy. For example, a task used to
2020 check servers.
2021
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02002022tune.lua.service-timeout <timeout>
2023 This is the execution timeout for the Lua services. This is useful for
2024 preventing infinite loops or spending too much time in Lua. This timeout
2025 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002026 not taken in account. The default timeout is 4s.
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02002027
Willy Tarreaua0250ba2008-01-06 11:22:57 +01002028tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01002029 Sets the maximum number of consecutive connections a process may accept in a
2030 row before switching to other work. In single process mode, higher numbers
2031 give better performance at high connection rates. However in multi-process
2032 modes, keeping a bit of fairness between processes generally is better to
2033 increase performance. This value applies individually to each listener, so
2034 that the number of processes a listener is bound to is taken into account.
2035 This value defaults to 64. In multi-process mode, it is divided by twice
2036 the number of processes the listener is bound to. Setting this value to -1
2037 completely disables the limitation. It should normally not be needed to tweak
2038 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01002039
2040tune.maxpollevents <number>
2041 Sets the maximum amount of events that can be processed at once in a call to
2042 the polling system. The default value is adapted to the operating system. It
2043 has been noticed that reducing it below 200 tends to slightly decrease
2044 latency at the expense of network bandwidth, and increasing it above 200
2045 tends to trade latency for slightly increased bandwidth.
2046
Willy Tarreau27a674e2009-08-17 07:23:33 +02002047tune.maxrewrite <number>
2048 Sets the reserved buffer space to this size in bytes. The reserved space is
2049 used for header rewriting or appending. The first reads on sockets will never
2050 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
2051 bufsize, though that does not make much sense since there are rarely large
2052 numbers of headers to add. Setting it too high prevents processing of large
2053 requests or responses. Setting it too low prevents addition of new headers
2054 to already large requests or to POST requests. It is generally wise to set it
2055 to about 1024. It is automatically readjusted to half of bufsize if it is
2056 larger than that. This means you don't have to worry about it when changing
2057 bufsize.
2058
Willy Tarreauf3045d22015-04-29 16:24:50 +02002059tune.pattern.cache-size <number>
2060 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
2061 cache which reminds previous lookups and their results. It is used by ACLs
2062 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
2063 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
2064 strings. It applies to pattern expressions which means that it will be able
2065 to memorize the result of a lookup among all the patterns specified on a
2066 configuration line (including all those loaded from files). It automatically
2067 invalidates entries which are updated using HTTP actions or on the CLI. The
2068 default cache size is set to 10000 entries, which limits its footprint to
Willy Tarreau403bfbb2019-10-23 06:59:31 +02002069 about 5 MB per process/thread on 32-bit systems and 8 MB per process/thread
2070 on 64-bit systems, as caches are thread/process local. There is a very low
Willy Tarreauf3045d22015-04-29 16:24:50 +02002071 risk of collision in this cache, which is in the order of the size of the
2072 cache divided by 2^64. Typically, at 10000 requests per second with the
2073 default cache size of 10000 entries, there's 1% chance that a brute force
2074 attack could cause a single collision after 60 years, or 0.1% after 6 years.
2075 This is considered much lower than the risk of a memory corruption caused by
2076 aging components. If this is not acceptable, the cache can be disabled by
2077 setting this parameter to 0.
2078
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02002079tune.pipesize <number>
2080 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
2081 are the default size for the system. But sometimes when using TCP splicing,
2082 it can improve performance to increase pipe sizes, especially if it is
2083 suspected that pipes are not filled and that many calls to splice() are
2084 performed. This has an impact on the kernel's memory footprint, so this must
2085 not be changed if impacts are not understood.
2086
Olivier Houchard88698d92019-04-16 19:07:22 +02002087tune.pool-high-fd-ratio <number>
2088 This setting sets the max number of file descriptors (in percentage) used by
2089 haproxy globally against the maximum number of file descriptors haproxy can
2090 use before we start killing idle connections when we can't reuse a connection
2091 and we have to create a new one. The default is 25 (one quarter of the file
2092 descriptor will mean that roughly half of the maximum front connections can
2093 keep an idle connection behind, anything beyond this probably doesn't make
John Roeslerfb2fce12019-07-10 15:45:51 -05002094 much sense in the general case when targeting connection reuse).
Olivier Houchard88698d92019-04-16 19:07:22 +02002095
Willy Tarreau83ca3052020-07-01 18:30:16 +02002096tune.pool-low-fd-ratio <number>
2097 This setting sets the max number of file descriptors (in percentage) used by
2098 haproxy globally against the maximum number of file descriptors haproxy can
2099 use before we stop putting connection into the idle pool for reuse. The
2100 default is 20.
2101
Willy Tarreaue803de22010-01-21 17:43:04 +01002102tune.rcvbuf.client <number>
2103tune.rcvbuf.server <number>
2104 Forces the kernel socket receive buffer size on the client or the server side
2105 to the specified value in bytes. This value applies to all TCP/HTTP frontends
2106 and backends. It should normally never be set, and the default size (0) lets
John Roeslerfb2fce12019-07-10 15:45:51 -05002107 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01002108 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01002109 order to save kernel memory by preventing it from buffering too large amounts
2110 of received data. Lower values will significantly increase CPU usage though.
2111
Willy Tarreaub22fc302015-12-14 12:04:35 +01002112tune.recv_enough <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01002113 HAProxy uses some hints to detect that a short read indicates the end of the
Willy Tarreaub22fc302015-12-14 12:04:35 +01002114 socket buffers. One of them is that a read returns more than <recv_enough>
2115 bytes, which defaults to 10136 (7 segments of 1448 each). This default value
2116 may be changed by this setting to better deal with workloads involving lots
2117 of short messages such as telnet or SSH sessions.
2118
Olivier Houchard1599b802018-05-24 18:59:04 +02002119tune.runqueue-depth <number>
John Roeslerfb2fce12019-07-10 15:45:51 -05002120 Sets the maximum amount of task that can be processed at once when running
Olivier Houchard1599b802018-05-24 18:59:04 +02002121 tasks. The default value is 200. Increasing it may incur latency when
Willy Tarreaue7723bd2020-06-24 11:11:02 +02002122 dealing with I/Os, making it too small can incur extra overhead. When
2123 experimenting with much larger values, it may be useful to also enable
2124 tune.sched.low-latency to limit the maximum latency to the lowest possible.
2125
2126tune.sched.low-latency { on | off }
2127 Enables ('on') or disables ('off') the low-latency task scheduler. By default
2128 haproxy processes tasks from several classes one class at a time as this is
2129 the most efficient. But when running with large values of tune.runqueue-depth
2130 this can have a measurable effect on request or connection latency. When this
2131 low-latency setting is enabled, tasks of lower priority classes will always
2132 be executed before other ones if they exist. This will permit to lower the
2133 maximum latency experienced by new requests or connections in the middle of
2134 massive traffic, at the expense of a higher impact on this large traffic.
2135 For regular usage it is better to leave this off. The default value is off.
Olivier Houchard1599b802018-05-24 18:59:04 +02002136
Willy Tarreaue803de22010-01-21 17:43:04 +01002137tune.sndbuf.client <number>
2138tune.sndbuf.server <number>
2139 Forces the kernel socket send buffer size on the client or the server side to
2140 the specified value in bytes. This value applies to all TCP/HTTP frontends
2141 and backends. It should normally never be set, and the default size (0) lets
John Roeslerfb2fce12019-07-10 15:45:51 -05002142 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01002143 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01002144 order to save kernel memory by preventing it from buffering too large amounts
2145 of received data. Lower values will significantly increase CPU usage though.
2146 Another use case is to prevent write timeouts with extremely slow clients due
2147 to the kernel waiting for a large part of the buffer to be read before
2148 notifying haproxy again.
2149
Willy Tarreau6ec58db2012-11-16 16:32:15 +01002150tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01002151 Sets the size of the global SSL session cache, in a number of blocks. A block
2152 is large enough to contain an encoded session without peer certificate.
2153 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002154 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01002155 200 bytes of memory. The default value may be forced at build time, otherwise
Davor Ocelice9ed2812017-12-25 17:49:28 +01002156 defaults to 20000. When the cache is full, the most idle entries are purged
Emeric Brunaf9619d2012-11-28 18:47:52 +01002157 and reassigned. Higher values reduce the occurrence of such a purge, hence
2158 the number of CPU-intensive SSL handshakes by ensuring that all users keep
2159 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01002160 and are shared between all processes if "nbproc" is greater than 1. Setting
2161 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01002162
Emeric Brun8dc60392014-05-09 13:52:00 +02002163tune.ssl.force-private-cache
Lukas Tribus27935782018-10-01 02:00:16 +02002164 This option disables SSL session cache sharing between all processes. It
Emeric Brun8dc60392014-05-09 13:52:00 +02002165 should normally not be used since it will force many renegotiations due to
2166 clients hitting a random process. But it may be required on some operating
2167 systems where none of the SSL cache synchronization method may be used. In
2168 this case, adding a first layer of hash-based load balancing before the SSL
2169 layer might limit the impact of the lack of session sharing.
2170
William Lallemand7d42ef52020-07-06 11:41:30 +02002171tune.ssl.keylog { on | off }
2172 This option activates the logging of the TLS keys. It should be used with
2173 care as it will consume more memory per SSL session and could decrease
2174 performances. This is disabled by default.
2175
2176 These sample fetches should be used to generate the SSLKEYLOGFILE that is
2177 required to decipher traffic with wireshark.
2178
2179 https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format
2180
2181 The SSLKEYLOG is a series of lines which are formatted this way:
2182
2183 <Label> <space> <ClientRandom> <space> <Secret>
2184
2185 The ClientRandom is provided by the %[ssl_fc_client_random,hex] sample
2186 fetch, the secret and the Label could be find in the array below. You need
2187 to generate a SSLKEYLOGFILE with all the labels in this array.
2188
2189 The following sample fetches are hexadecimal strings and does not need to be
2190 converted.
2191
2192 SSLKEYLOGFILE Label | Sample fetches for the Secrets
2193 --------------------------------|-----------------------------------------
2194 CLIENT_EARLY_TRAFFIC_SECRET | %[ssl_fc_client_early_traffic_secret]
2195 CLIENT_HANDSHAKE_TRAFFIC_SECRET | %[ssl_fc_client_handshake_traffic_secret]
2196 SERVER_HANDSHAKE_TRAFFIC_SECRET | %[ssl_fc_server_handshake_traffic_secret]
2197 CLIENT_TRAFFIC_SECRET_0 | %[ssl_fc_client_traffic_secret_0]
2198 SERVER_TRAFFIC_SECRET_0 | %[ssl_fc_server_traffic_secret_0]
William Lallemandd742b6c2020-07-07 10:14:56 +02002199 EXPORTER_SECRET | %[ssl_fc_exporter_secret]
2200 EARLY_EXPORTER_SECRET | %[ssl_fc_early_exporter_secret]
William Lallemand7d42ef52020-07-06 11:41:30 +02002201
2202 This is only available with OpenSSL 1.1.1, and useful with TLS1.3 session.
2203
2204 If you want to generate the content of a SSLKEYLOGFILE with TLS < 1.3, you
2205 only need this line:
2206
2207 "CLIENT_RANDOM %[ssl_fc_client_random,hex] %[ssl_fc_session_key,hex]"
2208
Emeric Brun4f65bff2012-11-16 15:11:00 +01002209tune.ssl.lifetime <timeout>
2210 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002211 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01002212 does not guarantee that sessions will last that long, because if the cache is
2213 full, the longest idle sessions will be purged despite their configured
2214 lifetime. The real usefulness of this setting is to prevent sessions from
2215 being used for too long.
2216
Willy Tarreaubfd59462013-02-21 07:46:09 +01002217tune.ssl.maxrecord <number>
2218 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
2219 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
2220 data only once it has received a full record. With large records, it means
2221 that clients might have to download up to 16kB of data before starting to
2222 process them. Limiting the value can improve page load times on browsers
2223 located over high latency or low bandwidth networks. It is suggested to find
2224 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
2225 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
2226 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
2227 2859 gave good results during tests. Use "strace -e trace=write" to find the
Davor Ocelice9ed2812017-12-25 17:49:28 +01002228 best value. HAProxy will automatically switch to this setting after an idle
Willy Tarreau7e312732014-02-12 16:35:14 +01002229 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01002230
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002231tune.ssl.default-dh-param <number>
2232 Sets the maximum size of the Diffie-Hellman parameters used for generating
2233 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
2234 final size will try to match the size of the server's RSA (or DSA) key (e.g,
2235 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
Willy Tarreau3ba77d22020-05-08 09:31:18 +02002236 this maximum value. Default value if 2048. Only 1024 or higher values are
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002237 allowed. Higher values will increase the CPU load, and values greater than
2238 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02002239 used if static Diffie-Hellman parameters are supplied either directly
2240 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02002241
Christopher Faulet31af49d2015-06-09 17:29:50 +02002242tune.ssl.ssl-ctx-cache-size <number>
2243 Sets the size of the cache used to store generated certificates to <number>
2244 entries. This is a LRU cache. Because generating a SSL certificate
2245 dynamically is expensive, they are cached. The default cache size is set to
2246 1000 entries.
2247
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01002248tune.ssl.capture-cipherlist-size <number>
2249 Sets the maximum size of the buffer used for capturing client-hello cipher
2250 list. If the value is 0 (default value) the capture is disabled, otherwise
2251 a buffer is allocated for each SSL/TLS connection.
2252
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002253tune.vars.global-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01002254tune.vars.proc-max-size <size>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002255tune.vars.reqres-max-size <size>
2256tune.vars.sess-max-size <size>
2257tune.vars.txn-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01002258 These five tunes help to manage the maximum amount of memory used by the
2259 variables system. "global" limits the overall amount of memory available for
2260 all scopes. "proc" limits the memory for the process scope, "sess" limits the
2261 memory for the session scope, "txn" for the transaction scope, and "reqres"
2262 limits the memory for each request or response processing.
2263 Memory accounting is hierarchical, meaning more coarse grained limits include
2264 the finer grained ones: "proc" includes "sess", "sess" includes "txn", and
2265 "txn" includes "reqres".
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002266
Daniel Schneller0b547052016-03-21 20:46:57 +01002267 For example, when "tune.vars.sess-max-size" is limited to 100,
2268 "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed
2269 100 either. If we create a variable "txn.var" that contains 100 bytes,
2270 all available space is consumed.
2271 Notice that exceeding the limits at runtime will not result in an error
2272 message, but values might be cut off or corrupted. So make sure to accurately
2273 plan for the amount of space needed to store all your variables.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02002274
William Lallemanda509e4c2012-11-07 16:54:34 +01002275tune.zlib.memlevel <number>
2276 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002277 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01002278 state. A value of 1 uses minimum memory but is slow and reduces compression
Davor Ocelice9ed2812017-12-25 17:49:28 +01002279 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
William Lallemanda509e4c2012-11-07 16:54:34 +01002280 between 1 and 9. The default value is 8.
2281
2282tune.zlib.windowsize <number>
2283 Sets the window size (the size of the history buffer) as a parameter of the
2284 zlib initialization for each session. Larger values of this parameter result
Davor Ocelice9ed2812017-12-25 17:49:28 +01002285 in better compression at the expense of memory usage. Can be a value between
2286 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002287
Willy Tarreauc57f0e22009-05-10 13:12:33 +020022883.3. Debugging
2289--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02002290
Willy Tarreau1b857852020-02-25 11:27:22 +01002291debug (deprecated)
Willy Tarreau6a06a402007-07-15 20:15:28 +02002292 Enables debug mode which dumps to stdout all exchanges, and disables forking
2293 into background. It is the equivalent of the command-line argument "-d". It
2294 should never be used in a production configuration since it may prevent full
2295 system startup.
2296
2297quiet
2298 Do not display any message during startup. It is equivalent to the command-
2299 line argument "-q".
2300
Willy Tarreau3eb10b82020-04-15 16:42:39 +02002301zero-warning
2302 When this option is set, haproxy will refuse to start if any warning was
2303 emitted while processing the configuration. It is highly recommended to set
2304 this option on configurations that are not changed often, as it helps detect
2305 subtle mistakes and keep the configuration clean and forward-compatible. Note
2306 that "haproxy -c" will also report errors in such a case. This option is
2307 equivalent to command line argument "-dW".
2308
Emeric Brunf099e792010-09-27 12:05:28 +02002309
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010023103.4. Userlists
2311--------------
2312It is possible to control access to frontend/backend/listen sections or to
2313http stats by allowing only authenticated and authorized users. To do this,
2314it is required to create at least one userlist and to define users.
2315
2316userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01002317 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002318 used to store authentication & authorization data for independent customers.
2319
2320group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01002321 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002322 attach users to this group by using a comma separated list of names
2323 proceeded by "users" keyword.
2324
Cyril Bontéf0c60612010-02-06 14:44:47 +01002325user <username> [password|insecure-password <password>]
2326 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002327 Adds user <username> to the current userlist. Both secure (encrypted) and
2328 insecure (unencrypted) passwords can be used. Encrypted passwords are
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002329 evaluated using the crypt(3) function, so depending on the system's
2330 capabilities, different algorithms are supported. For example, modern Glibc
2331 based Linux systems support MD5, SHA-256, SHA-512, and, of course, the
2332 classic DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002333
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002334 Attention: Be aware that using encrypted passwords might cause significantly
2335 increased CPU usage, depending on the number of requests, and the algorithm
2336 used. For any of the hashed variants, the password for each request must
2337 be processed through the chosen algorithm, before it can be compared to the
2338 value specified in the config file. Most current algorithms are deliberately
2339 designed to be expensive to compute to achieve resistance against brute
2340 force attacks. They do not simply salt/hash the clear text password once,
2341 but thousands of times. This can quickly become a major factor in haproxy's
2342 overall CPU consumption!
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002343
2344 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01002345 userlist L1
2346 group G1 users tiger,scott
2347 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002348
Cyril Bontéf0c60612010-02-06 14:44:47 +01002349 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
2350 user scott insecure-password elgato
2351 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002352
Cyril Bontéf0c60612010-02-06 14:44:47 +01002353 userlist L2
2354 group G1
2355 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002356
Cyril Bontéf0c60612010-02-06 14:44:47 +01002357 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
2358 user scott insecure-password elgato groups G1,G2
2359 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002360
2361 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002362
Emeric Brunf099e792010-09-27 12:05:28 +02002363
23643.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02002365----------
Emeric Brun94900952015-06-11 18:25:54 +02002366It is possible to propagate entries of any data-types in stick-tables between
2367several haproxy instances over TCP connections in a multi-master fashion. Each
2368instance pushes its local updates and insertions to remote peers. The pushed
2369values overwrite remote ones without aggregation. Interrupted exchanges are
2370automatically detected and recovered from the last known point.
2371In addition, during a soft restart, the old process connects to the new one
2372using such a TCP connection to push all its entries before the new process
2373tries to connect to other peers. That ensures very fast replication during a
2374reload, it typically takes a fraction of a second even for large tables.
2375Note that Server IDs are used to identify servers remotely, so it is important
2376that configurations look similar or at least that the same IDs are forced on
2377each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02002378
2379peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002380 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02002381 which is referenced by one or more stick-tables.
2382
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002383bind [<address>]:<port_range> [, ...] [param*]
2384 Defines the binding parameters of the local peer of this "peers" section.
2385 Such lines are not supported with "peer" line in the same "peers" section.
2386
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002387disabled
2388 Disables a peers section. It disables both listening and any synchronization
2389 related to this section. This is provided to disable synchronization of stick
2390 tables without having to comment out all "peers" references.
2391
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002392default-bind [param*]
2393 Defines the binding parameters for the local peer, excepted its address.
2394
2395default-server [param*]
2396 Change default options for a server in a "peers" section.
2397
2398 Arguments:
2399 <param*> is a list of parameters for this server. The "default-server"
2400 keyword accepts an important number of options and has a complete
2401 section dedicated to it. Please refer to section 5 for more
2402 details.
2403
2404
2405 See also: "server" and section 5 about server options
2406
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002407enable
2408 This re-enables a disabled peers section which was previously disabled.
2409
Frédéric Lécailleb6f759b2019-11-05 09:57:45 +01002410log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
2411 <facility> [<level> [<minlevel>]]
2412 "peers" sections support the same "log" keyword as for the proxies to
2413 log information about the "peers" listener. See "log" option for proxies for
2414 more details.
2415
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002416peer <peername> <ip>:<port> [param*]
Emeric Brunf099e792010-09-27 12:05:28 +02002417 Defines a peer inside a peers section.
2418 If <peername> is set to the local peer name (by default hostname, or forced
Dragan Dosen13cd54c2020-06-18 18:24:05 +02002419 using "-L" command line option or "localpeer" global configuration setting),
2420 haproxy will listen for incoming remote peer connection on <ip>:<port>.
2421 Otherwise, <ip>:<port> defines where to connect to in order to join the
2422 remote peer, and <peername> is used at the protocol level to identify and
2423 validate the remote peer on the server side.
Emeric Brunf099e792010-09-27 12:05:28 +02002424
2425 During a soft restart, local peer <ip>:<port> is used by the old instance to
2426 connect the new one and initiate a complete replication (teaching process).
2427
2428 It is strongly recommended to have the exact same peers declaration on all
Dragan Dosen13cd54c2020-06-18 18:24:05 +02002429 peers and to only rely on the "-L" command line argument or the "localpeer"
2430 global configuration setting to change the local peer name. This makes it
2431 easier to maintain coherent configuration files across all peers.
Emeric Brunf099e792010-09-27 12:05:28 +02002432
William Lallemandb2f07452015-05-12 14:27:13 +02002433 You may want to reference some environment variables in the address
2434 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01002435
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002436 Note: "peer" keyword may transparently be replaced by "server" keyword (see
2437 "server" keyword explanation below).
2438
2439server <peername> [<ip>:<port>] [param*]
Michael Prokop4438c602019-05-24 10:25:45 +02002440 As previously mentioned, "peer" keyword may be replaced by "server" keyword
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002441 with a support for all "server" parameters found in 5.2 paragraph.
2442 If the underlying peer is local, <ip>:<port> parameters must not be present.
2443 These parameters must be provided on a "bind" line (see "bind" keyword
2444 of this "peers" section).
2445 Some of these parameters are irrelevant for "peers" sections.
2446
2447
Cyril Bontédc4d9032012-04-08 21:57:39 +02002448 Example:
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002449 # The old way.
Emeric Brunf099e792010-09-27 12:05:28 +02002450 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01002451 peer haproxy1 192.168.0.1:1024
2452 peer haproxy2 192.168.0.2:1024
2453 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02002454
2455 backend mybackend
2456 mode tcp
2457 balance roundrobin
2458 stick-table type ip size 20k peers mypeers
2459 stick on src
2460
Willy Tarreauf7b30a92010-12-06 22:59:17 +01002461 server srv1 192.168.0.30:80
2462 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02002463
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002464 Example:
2465 peers mypeers
2466 bind 127.0.0.11:10001 ssl crt mycerts/pem
2467 default-server ssl verify none
2468 server hostA 127.0.0.10:10000
2469 server hostB #local peer
Emeric Brunf099e792010-09-27 12:05:28 +02002470
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002471
2472table <tablename> type {ip | integer | string [len <length>] | binary [len <length>]}
2473 size <size> [expire <expire>] [nopurge] [store <data_type>]*
2474
2475 Configure a stickiness table for the current section. This line is parsed
2476 exactly the same way as the "stick-table" keyword in others section, except
John Roeslerfb2fce12019-07-10 15:45:51 -05002477 for the "peers" argument which is not required here and with an additional
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002478 mandatory first parameter to designate the stick-table. Contrary to others
2479 sections, there may be several "table" lines in "peers" sections (see also
2480 "stick-table" keyword).
2481
2482 Also be aware of the fact that "peers" sections have their own stick-table
2483 namespaces to avoid collisions between stick-table names identical in
2484 different "peers" section. This is internally handled prepending the "peers"
2485 sections names to the name of the stick-tables followed by a '/' character.
2486 If somewhere else in the configuration file you have to refer to such
2487 stick-tables declared in "peers" sections you must use the prefixed version
2488 of the stick-table name as follows:
2489
2490 peers mypeers
2491 peer A ...
2492 peer B ...
2493 table t1 ...
2494
2495 frontend fe1
2496 tcp-request content track-sc0 src table mypeers/t1
2497
2498 This is also this prefixed version of the stick-table names which must be
2499 used to refer to stick-tables through the CLI.
2500
2501 About "peers" protocol, as only "peers" belonging to the same section may
2502 communicate with each others, there is no need to do such a distinction.
2503 Several "peers" sections may declare stick-tables with the same name.
2504 This is shorter version of the stick-table name which is sent over the network.
2505 There is only a '/' character as prefix to avoid stick-table name collisions between
2506 stick-tables declared as backends and stick-table declared in "peers" sections
2507 as follows in this weird but supported configuration:
2508
2509 peers mypeers
2510 peer A ...
2511 peer B ...
2512 table t1 type string size 10m store gpc0
2513
2514 backend t1
2515 stick-table type string size 10m store gpc0 peers mypeers
2516
Daniel Corbett67a82712020-07-06 23:01:19 -04002517 Here "t1" table declared in "mypeers" section has "mypeers/t1" as global name.
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002518 "t1" table declared as a backend as "t1" as global name. But at peer protocol
2519 level the former table is named "/t1", the latter is again named "t1".
2520
Simon Horman51a1cf62015-02-03 13:00:44 +090025213.6. Mailers
2522------------
2523It is possible to send email alerts when the state of servers changes.
2524If configured email alerts are sent to each mailer that is configured
2525in a mailers section. Email is sent to mailers using SMTP.
2526
Pieter Baauw386a1272015-08-16 15:26:24 +02002527mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09002528 Creates a new mailer list with the name <mailersect>. It is an
2529 independent section which is referenced by one or more proxies.
2530
2531mailer <mailername> <ip>:<port>
2532 Defines a mailer inside a mailers section.
2533
2534 Example:
2535 mailers mymailers
2536 mailer smtp1 192.168.0.1:587
2537 mailer smtp2 192.168.0.2:587
2538
2539 backend mybackend
2540 mode tcp
2541 balance roundrobin
2542
2543 email-alert mailers mymailers
2544 email-alert from test1@horms.org
2545 email-alert to test2@horms.org
2546
2547 server srv1 192.168.0.30:80
2548 server srv2 192.168.0.31:80
2549
Pieter Baauw235fcfc2016-02-13 15:33:40 +01002550timeout mail <time>
2551 Defines the time available for a mail/connection to be made and send to
2552 the mail-server. If not defined the default value is 10 seconds. To allow
2553 for at least two SYN-ACK packets to be send during initial TCP handshake it
2554 is advised to keep this value above 4 seconds.
2555
2556 Example:
2557 mailers mymailers
2558 timeout mail 20s
2559 mailer smtp1 192.168.0.1:587
Simon Horman51a1cf62015-02-03 13:00:44 +09002560
William Lallemandc9515522019-06-12 16:32:11 +020025613.7. Programs
2562-------------
2563In master-worker mode, it is possible to launch external binaries with the
2564master, these processes are called programs. These programs are launched and
2565managed the same way as the workers.
2566
2567During a reload of HAProxy, those processes are dealing with the same
2568sequence as a worker:
2569
2570 - the master is re-executed
2571 - the master sends a SIGUSR1 signal to the program
2572 - if "option start-on-reload" is not disabled, the master launches a new
2573 instance of the program
2574
2575During a stop, or restart, a SIGTERM is sent to the programs.
2576
2577program <name>
2578 This is a new program section, this section will create an instance <name>
2579 which is visible in "show proc" on the master CLI. (See "9.4. Master CLI" in
2580 the management guide).
2581
2582command <command> [arguments*]
2583 Define the command to start with optional arguments. The command is looked
2584 up in the current PATH if it does not include an absolute path. This is a
2585 mandatory option of the program section. Arguments containing spaces must
2586 be enclosed in quotes or double quotes or be prefixed by a backslash.
2587
Andrew Heberle97236962019-07-12 11:50:26 +08002588user <user name>
2589 Changes the executed command user ID to the <user name> from /etc/passwd.
2590 See also "group".
2591
2592group <group name>
2593 Changes the executed command group ID to the <group name> from /etc/group.
2594 See also "user".
2595
William Lallemandc9515522019-06-12 16:32:11 +02002596option start-on-reload
2597no option start-on-reload
2598 Start (or not) a new instance of the program upon a reload of the master.
2599 The default is to start a new instance. This option may only be used in a
2600 program section.
2601
2602
Christopher Faulet76edc0f2020-01-13 15:52:01 +010026033.8. HTTP-errors
2604----------------
2605
2606It is possible to globally declare several groups of HTTP errors, to be
2607imported afterwards in any proxy section. Same group may be referenced at
2608several places and can be fully or partially imported.
2609
2610http-errors <name>
2611 Create a new http-errors group with the name <name>. It is an independent
2612 section that may be referenced by one or more proxies using its name.
2613
2614errorfile <code> <file>
2615 Associate a file contents to an HTTP error code
2616
2617 Arguments :
2618 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02002619 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
2620 425, 429, 500, 502, 503, and 504.
Christopher Faulet76edc0f2020-01-13 15:52:01 +01002621
2622 <file> designates a file containing the full HTTP response. It is
2623 recommended to follow the common practice of appending ".http" to
2624 the filename so that people do not confuse the response with HTML
2625 error pages, and to use absolute paths, since files are read
2626 before any chroot is performed.
2627
2628 Please referrers to "errorfile" keyword in section 4 for details.
2629
2630 Example:
2631 http-errors website-1
2632 errorfile 400 /etc/haproxy/errorfiles/site1/400.http
2633 errorfile 404 /etc/haproxy/errorfiles/site1/404.http
2634 errorfile 408 /dev/null # work around Chrome pre-connect bug
2635
2636 http-errors website-2
2637 errorfile 400 /etc/haproxy/errorfiles/site2/400.http
2638 errorfile 404 /etc/haproxy/errorfiles/site2/404.http
2639 errorfile 408 /dev/null # work around Chrome pre-connect bug
2640
Emeric Brun99c453d2020-05-25 15:01:04 +020026413.9. Rings
2642----------
2643
2644It is possible to globally declare ring-buffers, to be used as target for log
2645servers or traces.
2646
2647ring <ringname>
2648 Creates a new ring-buffer with name <ringname>.
2649
2650description <text>
Daniel Corbett67a82712020-07-06 23:01:19 -04002651 The description is an optional description string of the ring. It will
Emeric Brun99c453d2020-05-25 15:01:04 +02002652 appear on CLI. By default, <name> is reused to fill this field.
2653
2654format <format>
2655 Format used to store events into the ring buffer.
2656
2657 Arguments:
2658 <format> is the log format used when generating syslog messages. It may be
2659 one of the following :
2660
2661 iso A message containing only the ISO date, followed by the text.
2662 The PID, process name and system name are omitted. This is
2663 designed to be used with a local log server.
2664
2665 raw A message containing only the text. The level, PID, date, time,
2666 process name and system name are omitted. This is designed to be
2667 used in containers or during development, where the severity
2668 only depends on the file descriptor used (stdout/stderr). This
2669 is the default.
2670
2671 rfc3164 The RFC3164 syslog message format. This is the default.
2672 (https://tools.ietf.org/html/rfc3164)
2673
2674 rfc5424 The RFC5424 syslog message format.
2675 (https://tools.ietf.org/html/rfc5424)
2676
2677 short A message containing only a level between angle brackets such as
2678 '<3>', followed by the text. The PID, date, time, process name
2679 and system name are omitted. This is designed to be used with a
2680 local log server. This format is compatible with what the systemd
2681 logger consumes.
2682
Emeric Brun54648852020-07-06 15:54:06 +02002683 priority A message containing only a level plus syslog facility between angle
2684 brackets such as '<63>', followed by the text. The PID, date, time,
2685 process name and system name are omitted. This is designed to be used
2686 with a local log server.
2687
Emeric Brun99c453d2020-05-25 15:01:04 +02002688 timed A message containing only a level between angle brackets such as
2689 '<3>', followed by ISO date and by the text. The PID, process
2690 name and system name are omitted. This is designed to be
2691 used with a local log server.
2692
2693maxlen <length>
2694 The maximum length of an event message stored into the ring,
2695 including formatted header. If an event message is longer than
2696 <length>, it will be truncated to this length.
2697
Emeric Brun494c5052020-05-28 11:13:15 +02002698server <name> <address> [param*]
2699 Used to configure a syslog tcp server to forward messages from ring buffer.
2700 This supports for all "server" parameters found in 5.2 paragraph. Some of
2701 these parameters are irrelevant for "ring" sections. Important point: there
2702 is little reason to add more than one server to a ring, because all servers
2703 will receive the exact same copy of the ring contents, and as such the ring
2704 will progress at the speed of the slowest server. If one server does not
2705 respond, it will prevent old messages from being purged and may block new
2706 messages from being inserted into the ring. The proper way to send messages
2707 to multiple servers is to use one distinct ring per log server, not to
Emeric Brun97556472020-05-30 01:42:45 +02002708 attach multiple servers to the same ring. Note that specific server directive
2709 "log-proto" is used to set the protocol used to send messages.
Emeric Brun494c5052020-05-28 11:13:15 +02002710
Emeric Brun99c453d2020-05-25 15:01:04 +02002711size <size>
2712 This is the optional size in bytes for the ring-buffer. Default value is
2713 set to BUFSIZE.
2714
Emeric Brun494c5052020-05-28 11:13:15 +02002715timeout connect <timeout>
2716 Set the maximum time to wait for a connection attempt to a server to succeed.
2717
2718 Arguments :
2719 <timeout> is the timeout value specified in milliseconds by default, but
2720 can be in any other unit if the number is suffixed by the unit,
2721 as explained at the top of this document.
2722
2723timeout server <timeout>
2724 Set the maximum time for pending data staying into output buffer.
2725
2726 Arguments :
2727 <timeout> is the timeout value specified in milliseconds by default, but
2728 can be in any other unit if the number is suffixed by the unit,
2729 as explained at the top of this document.
2730
Emeric Brun99c453d2020-05-25 15:01:04 +02002731 Example:
2732 global
2733 log ring@myring local7
2734
2735 ring myring
2736 description "My local buffer"
2737 format rfc3164
2738 maxlen 1200
2739 size 32764
Emeric Brun494c5052020-05-28 11:13:15 +02002740 timeout connect 5s
2741 timeout server 10s
Emeric Brun97556472020-05-30 01:42:45 +02002742 server mysyslogsrv 127.0.0.1:6514 log-proto octet-count
Emeric Brun99c453d2020-05-25 15:01:04 +02002743
Emeric Brun12941c82020-07-07 14:19:42 +020027443.10. Log forwarding
2745-------------------
2746
2747It is possible to declare one or multiple log forwarding section,
2748haproxy will forward all received log messages to a log servers list.
2749
2750log-forward <name>
2751 Creates a new log forwarder proxy identified as <name>.
2752
Willy Tarreau76aaa7f2020-09-16 15:07:22 +02002753dgram-bind <addr> [param*]
2754 Used to configure a UDP log listener to receive messages to forward. Only UDP
2755 listeners are allowed, the address must be prefixed using "udp@", "udp4@" or
2756 "udp6@". This supports for some of the "bind" parameters found in 5.1
2757 paragraph among which "interface", "namespace" or "transparent", the other
2758 ones being silently ignored as irrelevant for UDP/syslog case.
Emeric Brun12941c82020-07-07 14:19:42 +02002759
2760log global
2761log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
2762 <facility> [<level> [<minlevel>]]
2763 Used to configure target log servers. See more details on proxies
2764 documentation.
2765 If no format specified, haproxy tries to keep the incoming log format.
2766 Configured facility is ignored, except if incoming message does not
2767 present a facility but one is mandatory on the outgoing format.
2768 If there is no timestamp available in the input format, but the field
2769 exists in output format, haproxy will use the local date.
2770
2771 Example:
2772 global
2773 log stderr format iso local7
2774
2775 ring myring
2776 description "My local buffer"
2777 format rfc5424
2778 maxlen 1200
2779 size 32764
2780 timeout connect 5s
2781 timeout server 10s
2782 # syslog tcp server
2783 server mysyslogsrv 127.0.0.1:514 log-proto octet-count
2784
2785 log-forward sylog-loadb
2786 bind udp4@127.0.0.1:1514
2787 # all messages on stderr
2788 log global
2789 # all messages on local tcp syslog server
2790 log ring@myring local0
2791 # load balance messages on 4 udp syslog servers
2792 log 127.0.0.1:10001 sample 1:4 local0
2793 log 127.0.0.1:10002 sample 2:4 local0
2794 log 127.0.0.1:10003 sample 3:4 local0
2795 log 127.0.0.1:10004 sample 4:4 local0
Christopher Faulet76edc0f2020-01-13 15:52:01 +01002796
Willy Tarreauc57f0e22009-05-10 13:12:33 +020027974. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02002798----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002799
Willy Tarreau6a06a402007-07-15 20:15:28 +02002800Proxy configuration can be located in a set of sections :
William Lallemand6e62fb62015-04-28 16:55:23 +02002801 - defaults [<name>]
Willy Tarreau6a06a402007-07-15 20:15:28 +02002802 - frontend <name>
2803 - backend <name>
2804 - listen <name>
2805
2806A "defaults" section sets default parameters for all other sections following
2807its declaration. Those default parameters are reset by the next "defaults"
2808section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01002809section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002810
2811A "frontend" section describes a set of listening sockets accepting client
2812connections.
2813
2814A "backend" section describes a set of servers to which the proxy will connect
2815to forward incoming connections.
2816
2817A "listen" section defines a complete proxy with its frontend and backend
2818parts combined in one section. It is generally useful for TCP-only traffic.
2819
Willy Tarreau0ba27502007-12-24 16:55:16 +01002820All proxy names must be formed from upper and lower case letters, digits,
2821'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
2822case-sensitive, which means that "www" and "WWW" are two different proxies.
2823
2824Historically, all proxy names could overlap, it just caused troubles in the
2825logs. Since the introduction of content switching, it is mandatory that two
2826proxies with overlapping capabilities (frontend/backend) have different names.
2827However, it is still permitted that a frontend and a backend share the same
2828name, as this configuration seems to be commonly encountered.
2829
2830Right now, two major proxy modes are supported : "tcp", also known as layer 4,
2831and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002832bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002833protocol, and can interact with it by allowing, blocking, switching, adding,
2834modifying, or removing arbitrary contents in requests or responses, based on
2835arbitrary criteria.
2836
Willy Tarreau70dffda2014-01-30 03:07:23 +01002837In HTTP mode, the processing applied to requests and responses flowing over
2838a connection depends in the combination of the frontend's HTTP options and
Julien Pivotto21ad3152019-12-10 13:11:17 +01002839the backend's. HAProxy supports 3 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +01002840
2841 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
2842 requests and responses are processed, and connections remain open but idle
2843 between responses and new requests.
2844
Willy Tarreau70dffda2014-01-30 03:07:23 +01002845 - SCL: server close ("option http-server-close") : the server-facing
2846 connection is closed after the end of the response is received, but the
2847 client-facing connection remains open.
2848
Christopher Faulet315b39c2018-09-21 16:26:19 +02002849 - CLO: close ("option httpclose"): the connection is closed after the end of
2850 the response and "Connection: close" appended in both directions.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002851
2852The effective mode that will be applied to a connection passing through a
2853frontend and a backend can be determined by both proxy modes according to the
2854following matrix, but in short, the modes are symmetric, keep-alive is the
Christopher Faulet315b39c2018-09-21 16:26:19 +02002855weakest option and close is the strongest.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002856
Christopher Faulet315b39c2018-09-21 16:26:19 +02002857 Backend mode
Willy Tarreau70dffda2014-01-30 03:07:23 +01002858
Christopher Faulet315b39c2018-09-21 16:26:19 +02002859 | KAL | SCL | CLO
2860 ----+-----+-----+----
2861 KAL | KAL | SCL | CLO
2862 ----+-----+-----+----
Christopher Faulet315b39c2018-09-21 16:26:19 +02002863 mode SCL | SCL | SCL | CLO
2864 ----+-----+-----+----
2865 CLO | CLO | CLO | CLO
Willy Tarreau70dffda2014-01-30 03:07:23 +01002866
Willy Tarreau0ba27502007-12-24 16:55:16 +01002867
Willy Tarreau70dffda2014-01-30 03:07:23 +01002868
Willy Tarreauc57f0e22009-05-10 13:12:33 +020028694.1. Proxy keywords matrix
2870--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002871
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002872The following list of keywords is supported. Most of them may only be used in a
2873limited set of section types. Some of them are marked as "deprecated" because
2874they are inherited from an old syntax which may be confusing or functionally
2875limited, and there are new recommended keywords to replace them. Keywords
Davor Ocelice9ed2812017-12-25 17:49:28 +01002876marked with "(*)" can be optionally inverted using the "no" prefix, e.g. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002877option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02002878and must be disabled for a specific instance. Such options may also be prefixed
2879with "default" in order to restore default settings regardless of what has been
2880specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002881
Willy Tarreau6a06a402007-07-15 20:15:28 +02002882
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002883 keyword defaults frontend listen backend
2884------------------------------------+----------+----------+---------+---------
2885acl - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002886backlog X X X -
2887balance X - X X
2888bind - X X -
2889bind-process X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002890capture cookie - X X -
2891capture request header - X X -
2892capture response header - X X -
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09002893clitcpka-cnt X X X -
2894clitcpka-idle X X X -
2895clitcpka-intvl X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02002896compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002897cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02002898declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002899default-server X - X X
2900default_backend X X X -
2901description - X X X
2902disabled X X X X
2903dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002904email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09002905email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002906email-alert mailers X X X X
2907email-alert myhostname X X X X
2908email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002909enabled X X X X
2910errorfile X X X X
Christopher Faulet76edc0f2020-01-13 15:52:01 +01002911errorfiles X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002912errorloc X X X X
2913errorloc302 X X X X
2914-- keyword -------------------------- defaults - frontend - listen -- backend -
2915errorloc303 X X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002916force-persist - - X X
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002917filter - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002918fullconn X - X X
2919grace X X X X
2920hash-type X - X X
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01002921http-after-response - X X X
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02002922http-check comment X - X X
Christopher Faulete5870d82020-04-15 11:32:03 +02002923http-check connect X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002924http-check disable-on-404 X - X X
Christopher Faulete5870d82020-04-15 11:32:03 +02002925http-check expect X - X X
Peter Gervai8912ae62020-06-11 18:26:36 +02002926http-check send X - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02002927http-check send-state X - X X
Christopher Faulete5870d82020-04-15 11:32:03 +02002928http-check set-var X - X X
2929http-check unset-var X - X X
Christopher Faulet3b967c12020-05-15 15:47:44 +02002930http-error X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002931http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02002932http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02002933http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02002934http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002935id - X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002936ignore-persist - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002937load-server-state-from-file X - X X
William Lallemand0f99e342011-10-12 17:50:54 +02002938log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01002939log-format X X X -
Dragan Dosen7ad31542015-09-28 17:16:47 +02002940log-format-sd X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01002941log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02002942max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002943maxconn X X X -
2944mode X X X X
2945monitor fail - X X -
2946monitor-net X X X -
2947monitor-uri X X X -
2948option abortonclose (*) X - X X
2949option accept-invalid-http-request (*) X X X -
2950option accept-invalid-http-response (*) X - X X
2951option allbackups (*) X - X X
2952option checkcache (*) X - X X
2953option clitcpka (*) X X X -
2954option contstats (*) X X X -
Christopher Faulet89aed322020-06-02 17:33:56 +02002955option disable-h2-upgrade (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002956option dontlog-normal (*) X X X -
2957option dontlognull (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002958-- keyword -------------------------- defaults - frontend - listen -- backend -
2959option forwardfor X X X X
Christopher Faulet98fbe952019-07-22 16:18:24 +02002960option h1-case-adjust-bogus-client (*) X X X -
2961option h1-case-adjust-bogus-server (*) X - X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02002962option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02002963option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01002964option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02002965option http-no-delay (*) X X X X
Christopher Faulet98db9762018-09-21 10:25:19 +02002966option http-pretend-keepalive (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002967option http-server-close (*) X X X X
2968option http-use-proxy-header (*) X X X -
2969option httpchk X - X X
2970option httpclose (*) X X X X
Freddy Spierenburge88b7732019-03-25 14:35:17 +01002971option httplog X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002972option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002973option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02002974option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002975option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002976option log-health-checks (*) X - X X
2977option log-separate-errors (*) X X X -
2978option logasap (*) X X X -
2979option mysql-check X - X X
2980option nolinger (*) X X X X
2981option originalto X X X X
2982option persist (*) X - X X
Baptiste Assmann809e22a2015-10-12 20:22:55 +02002983option pgsql-check X - X X
2984option prefer-last-server (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002985option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02002986option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002987option smtpchk X - X X
2988option socket-stats (*) X X X -
2989option splice-auto (*) X X X X
2990option splice-request (*) X X X X
2991option splice-response (*) X X X X
Christopher Fauletba7bc162016-11-07 21:07:38 +01002992option spop-check - - - X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002993option srvtcpka (*) X - X X
2994option ssl-hello-chk X - X X
2995-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01002996option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002997option tcp-smart-accept (*) X X X -
2998option tcp-smart-connect (*) X - X X
2999option tcpka X X X X
3000option tcplog X X X X
3001option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09003002external-check command X - X X
3003external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003004persist rdp-cookie X - X X
3005rate-limit sessions X X X -
3006redirect - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003007-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003008retries X - X X
Olivier Houcharda254a372019-04-05 15:30:12 +02003009retry-on X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003010server - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02003011server-state-file-name X - X X
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02003012server-template - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003013source X - X X
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003014srvtcpka-cnt X - X X
3015srvtcpka-idle X - X X
3016srvtcpka-intvl X - X X
Baptiste Assmann5a549212015-10-12 20:30:24 +02003017stats admin - X X X
3018stats auth X X X X
3019stats enable X X X X
3020stats hide-version X X X X
3021stats http-request - X X X
3022stats realm X X X X
3023stats refresh X X X X
3024stats scope X X X X
3025stats show-desc X X X X
3026stats show-legends X X X X
3027stats show-node X X X X
3028stats uri X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003029-- keyword -------------------------- defaults - frontend - listen -- backend -
3030stick match - - X X
3031stick on - - X X
3032stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02003033stick store-response - - X X
Adam Spiers68af3c12017-04-06 16:31:39 +01003034stick-table - X X X
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02003035tcp-check comment X - X X
Christopher Faulet404f9192020-04-09 23:13:54 +02003036tcp-check connect X - X X
3037tcp-check expect X - X X
3038tcp-check send X - X X
Christopher Fauletb50b3e62020-05-05 18:43:43 +02003039tcp-check send-lf X - X X
Christopher Faulet404f9192020-04-09 23:13:54 +02003040tcp-check send-binary X - X X
Christopher Fauletb50b3e62020-05-05 18:43:43 +02003041tcp-check send-binary-lf X - X X
Christopher Faulet404f9192020-04-09 23:13:54 +02003042tcp-check set-var X - X X
3043tcp-check unset-var X - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02003044tcp-request connection - X X -
3045tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02003046tcp-request inspect-delay - X X X
Willy Tarreau4f614292016-10-21 17:49:36 +02003047tcp-request session - X X -
Emeric Brun0a3b67f2010-09-24 15:34:53 +02003048tcp-response content - - X X
3049tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003050timeout check X - X X
3051timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02003052timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003053timeout connect X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003054timeout http-keep-alive X X X X
3055timeout http-request X X X X
3056timeout queue X - X X
3057timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02003058timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003059timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02003060timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003061transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01003062unique-id-format X X X -
3063unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003064use_backend - X X -
Christopher Fauletb30b3102019-09-12 23:03:09 +02003065use-fcgi-app - - X X
Willy Tarreau4a5cade2012-04-05 21:09:48 +02003066use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01003067------------------------------------+----------+----------+---------+---------
3068 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02003069
Willy Tarreau0ba27502007-12-24 16:55:16 +01003070
Willy Tarreauc57f0e22009-05-10 13:12:33 +020030714.2. Alphabetically sorted keywords reference
3072---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01003073
3074This section provides a description of each keyword and its usage.
3075
3076
3077acl <aclname> <criterion> [flags] [operator] <value> ...
3078 Declare or complete an access list.
3079 May be used in sections : defaults | frontend | listen | backend
3080 no | yes | yes | yes
3081 Example:
3082 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
3083 acl invalid_src src_port 0:1023
3084 acl local_dst hdr(host) -i localhost
3085
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003086 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003087
3088
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01003089backlog <conns>
3090 Give hints to the system about the approximate listen backlog desired size
3091 May be used in sections : defaults | frontend | listen | backend
3092 yes | yes | yes | no
3093 Arguments :
3094 <conns> is the number of pending connections. Depending on the operating
3095 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02003096 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01003097
3098 In order to protect against SYN flood attacks, one solution is to increase
3099 the system's SYN backlog size. Depending on the system, sometimes it is just
3100 tunable via a system parameter, sometimes it is not adjustable at all, and
3101 sometimes the system relies on hints given by the application at the time of
3102 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
3103 to the listen() syscall. On systems which can make use of this value, it can
3104 sometimes be useful to be able to specify a different value, hence this
3105 backlog parameter.
3106
3107 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
3108 used as a hint and the system accepts up to the smallest greater power of
3109 two, and never more than some limits (usually 32768).
3110
3111 See also : "maxconn" and the target operating system's tuning guide.
3112
3113
Willy Tarreau0ba27502007-12-24 16:55:16 +01003114balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02003115balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01003116 Define the load balancing algorithm to be used in a backend.
3117 May be used in sections : defaults | frontend | listen | backend
3118 yes | no | yes | yes
3119 Arguments :
3120 <algorithm> is the algorithm used to select a server when doing load
3121 balancing. This only applies when no persistence information
3122 is available, or when a connection is redispatched to another
3123 server. <algorithm> may be one of the following :
3124
3125 roundrobin Each server is used in turns, according to their weights.
3126 This is the smoothest and fairest algorithm when the server's
3127 processing time remains equally distributed. This algorithm
3128 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02003129 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08003130 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02003131 large farms, when a server becomes up after having been down
3132 for a very short time, it may sometimes take a few hundreds
3133 requests for it to be re-integrated into the farm and start
3134 receiving traffic. This is normal, though very rare. It is
3135 indicated here in case you would have the chance to observe
3136 it, so that you don't worry.
3137
3138 static-rr Each server is used in turns, according to their weights.
3139 This algorithm is as similar to roundrobin except that it is
3140 static, which means that changing a server's weight on the
3141 fly will have no effect. On the other hand, it has no design
3142 limitation on the number of servers, and when a server goes
3143 up, it is always immediately reintroduced into the farm, once
3144 the full map is recomputed. It also uses slightly less CPU to
3145 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01003146
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01003147 leastconn The server with the lowest number of connections receives the
3148 connection. Round-robin is performed within groups of servers
3149 of the same load to ensure that all servers will be used. Use
3150 of this algorithm is recommended where very long sessions are
3151 expected, such as LDAP, SQL, TSE, etc... but is not very well
3152 suited for protocols using short sessions such as HTTP. This
3153 algorithm is dynamic, which means that server weights may be
3154 adjusted on the fly for slow starts for instance.
3155
Willy Tarreauf09c6602012-02-13 17:12:08 +01003156 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03003157 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01003158 identifier to the highest (see server parameter "id"), which
3159 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02003160 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01003161 not make sense to use this algorithm without setting maxconn.
3162 The purpose of this algorithm is to always use the smallest
3163 number of servers so that extra servers can be powered off
3164 during non-intensive hours. This algorithm ignores the server
3165 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02003166 or IMAP than HTTP, though it can be useful there too. In
3167 order to use this algorithm efficiently, it is recommended
3168 that a cloud controller regularly checks server usage to turn
3169 them off when unused, and regularly checks backend queue to
3170 turn new servers on when the queue inflates. Alternatively,
3171 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01003172
Willy Tarreau0ba27502007-12-24 16:55:16 +01003173 source The source IP address is hashed and divided by the total
3174 weight of the running servers to designate which server will
3175 receive the request. This ensures that the same client IP
3176 address will always reach the same server as long as no
3177 server goes down or up. If the hash result changes due to the
3178 number of running servers changing, many clients will be
3179 directed to a different server. This algorithm is generally
3180 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003181 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01003182 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003183 static by default, which means that changing a server's
3184 weight on the fly will have no effect, but this can be
3185 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003186
Oskar Stolc8dc41842012-05-19 10:19:54 +01003187 uri This algorithm hashes either the left part of the URI (before
3188 the question mark) or the whole URI (if the "whole" parameter
3189 is present) and divides the hash value by the total weight of
3190 the running servers. The result designates which server will
3191 receive the request. This ensures that the same URI will
3192 always be directed to the same server as long as no server
3193 goes up or down. This is used with proxy caches and
3194 anti-virus proxies in order to maximize the cache hit rate.
3195 Note that this algorithm may only be used in an HTTP backend.
3196 This algorithm is static by default, which means that
3197 changing a server's weight on the fly will have no effect,
3198 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003199
Oskar Stolc8dc41842012-05-19 10:19:54 +01003200 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02003201 "depth", both followed by a positive integer number. These
3202 options may be helpful when it is needed to balance servers
3203 based on the beginning of the URI only. The "len" parameter
3204 indicates that the algorithm should only consider that many
3205 characters at the beginning of the URI to compute the hash.
3206 Note that having "len" set to 1 rarely makes sense since most
3207 URIs start with a leading "/".
3208
3209 The "depth" parameter indicates the maximum directory depth
3210 to be used to compute the hash. One level is counted for each
3211 slash in the request. If both parameters are specified, the
3212 evaluation stops when either is reached.
3213
Willy Tarreau0ba27502007-12-24 16:55:16 +01003214 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003215 the query string of each HTTP GET request.
3216
3217 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02003218 request entity will be searched for the parameter argument,
3219 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02003220 ('?') in the URL. The message body will only start to be
3221 analyzed once either the advertised amount of data has been
3222 received or the request buffer is full. In the unlikely event
3223 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02003224 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02003225 be randomly balanced if at all. This keyword used to support
3226 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003227
3228 If the parameter is found followed by an equal sign ('=') and
3229 a value, then the value is hashed and divided by the total
3230 weight of the running servers. The result designates which
3231 server will receive the request.
3232
3233 This is used to track user identifiers in requests and ensure
3234 that a same user ID will always be sent to the same server as
3235 long as no server goes up or down. If no value is found or if
3236 the parameter is not found, then a round robin algorithm is
3237 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003238 backend. This algorithm is static by default, which means
3239 that changing a server's weight on the fly will have no
3240 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003241
Cyril Bontédc4d9032012-04-08 21:57:39 +02003242 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
3243 request. Just as with the equivalent ACL 'hdr()' function,
3244 the header name in parenthesis is not case sensitive. If the
3245 header is absent or if it does not contain any value, the
3246 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01003247
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003248 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01003249 reducing the hash algorithm to the main domain part with some
3250 specific headers such as 'Host'. For instance, in the Host
3251 value "haproxy.1wt.eu", only "1wt" will be considered.
3252
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003253 This algorithm is static by default, which means that
3254 changing a server's weight on the fly will have no effect,
3255 but this can be changed using "hash-type".
3256
Willy Tarreau21c741a2019-01-14 18:14:27 +01003257 random
3258 random(<draws>)
3259 A random number will be used as the key for the consistent
Willy Tarreau760e81d2018-05-03 07:20:40 +02003260 hashing function. This means that the servers' weights are
3261 respected, dynamic weight changes immediately take effect, as
3262 well as new server additions. Random load balancing can be
3263 useful with large farms or when servers are frequently added
Willy Tarreau21c741a2019-01-14 18:14:27 +01003264 or removed as it may avoid the hammering effect that could
3265 result from roundrobin or leastconn in this situation. The
3266 hash-balance-factor directive can be used to further improve
3267 fairness of the load balancing, especially in situations
3268 where servers show highly variable response times. When an
3269 argument <draws> is present, it must be an integer value one
3270 or greater, indicating the number of draws before selecting
3271 the least loaded of these servers. It was indeed demonstrated
3272 that picking the least loaded of two servers is enough to
3273 significantly improve the fairness of the algorithm, by
3274 always avoiding to pick the most loaded server within a farm
3275 and getting rid of any bias that could be induced by the
3276 unfair distribution of the consistent list. Higher values N
3277 will take away N-1 of the highest loaded servers at the
3278 expense of performance. With very high values, the algorithm
3279 will converge towards the leastconn's result but much slower.
3280 The default value is 2, which generally shows very good
3281 distribution and performance. This algorithm is also known as
3282 the Power of Two Random Choices and is described here :
3283 http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
Willy Tarreau760e81d2018-05-03 07:20:40 +02003284
Emeric Brun736aa232009-06-30 17:56:00 +02003285 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02003286 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02003287 The RDP cookie <name> (or "mstshash" if omitted) will be
3288 looked up and hashed for each incoming TCP request. Just as
3289 with the equivalent ACL 'req_rdp_cookie()' function, the name
3290 is not case-sensitive. This mechanism is useful as a degraded
3291 persistence mode, as it makes it possible to always send the
3292 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003293 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02003294 used instead.
3295
3296 Note that for this to work, the frontend must ensure that an
3297 RDP cookie is already present in the request buffer. For this
3298 you must use 'tcp-request content accept' rule combined with
3299 a 'req_rdp_cookie_cnt' ACL.
3300
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02003301 This algorithm is static by default, which means that
3302 changing a server's weight on the fly will have no effect,
3303 but this can be changed using "hash-type".
3304
Cyril Bontédc4d9032012-04-08 21:57:39 +02003305 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09003306
Willy Tarreau0ba27502007-12-24 16:55:16 +01003307 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02003308 algorithms. Right now, only "url_param" and "uri" support an
3309 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003310
Willy Tarreau3cd9af22009-03-15 14:06:41 +01003311 The load balancing algorithm of a backend is set to roundrobin when no other
3312 algorithm, mode nor option have been set. The algorithm may only be set once
3313 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003314
Lukas Tribus80512b12018-10-27 20:07:40 +02003315 With authentication schemes that require the same connection like NTLM, URI
John Roeslerfb2fce12019-07-10 15:45:51 -05003316 based algorithms must not be used, as they would cause subsequent requests
Lukas Tribus80512b12018-10-27 20:07:40 +02003317 to be routed to different backend servers, breaking the invalid assumptions
3318 NTLM relies on.
3319
Willy Tarreau0ba27502007-12-24 16:55:16 +01003320 Examples :
3321 balance roundrobin
3322 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003323 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01003324 balance hdr(User-Agent)
3325 balance hdr(host)
3326 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003327
3328 Note: the following caveats and limitations on using the "check_post"
3329 extension with "url_param" must be considered :
3330
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003331 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003332 to determine if the parameters will be found in the body or entity which
3333 may contain binary data. Therefore another method may be required to
3334 restrict consideration of POST requests that have no URL parameters in
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02003335 the body. (see acl http_end)
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003336
3337 - using a <max_wait> value larger than the request buffer size does not
3338 make sense and is useless. The buffer size is set at build time, and
3339 defaults to 16 kB.
3340
3341 - Content-Encoding is not supported, the parameter search will probably
3342 fail; and load balancing will fall back to Round Robin.
3343
3344 - Expect: 100-continue is not supported, load balancing will fall back to
3345 Round Robin.
3346
Lukas Tribus23953682017-04-28 13:24:30 +00003347 - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003348 If the entire parameter value is not present in the first chunk, the
3349 selection of server is undefined (actually, defined by how little
3350 actually appeared in the first chunk).
3351
3352 - This feature does not support generation of a 100, 411 or 501 response.
3353
3354 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003355 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02003356 white space or control characters are found, indicating the end of what
3357 might be a URL parameter list. This is probably not a concern with SGML
3358 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003359
Willy Tarreau294d0f02015-08-10 19:40:12 +02003360 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003361
3362
Willy Tarreaub6205fd2012-09-24 12:27:33 +02003363bind [<address>]:<port_range> [, ...] [param*]
3364bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01003365 Define one or several listening addresses and/or ports in a frontend.
3366 May be used in sections : defaults | frontend | listen | backend
3367 no | yes | yes | no
3368 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01003369 <address> is optional and can be a host name, an IPv4 address, an IPv6
3370 address, or '*'. It designates the address the frontend will
3371 listen on. If unset, all IPv4 addresses of the system will be
3372 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01003373 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01003374 Optionally, an address family prefix may be used before the
3375 address to force the family regardless of the address format,
3376 which can be useful to specify a path to a unix socket with
3377 no slash ('/'). Currently supported prefixes are :
3378 - 'ipv4@' -> address is always IPv4
3379 - 'ipv6@' -> address is always IPv6
Emeric Brun3835c0d2020-07-07 09:46:09 +02003380 - 'udp@' -> address is resolved as IPv4 or IPv6 and
Emeric Brun12941c82020-07-07 14:19:42 +02003381 protocol UDP is used. Currently those listeners are
3382 supported only in log-forward sections.
Emeric Brun3835c0d2020-07-07 09:46:09 +02003383 - 'udp4@' -> address is always IPv4 and protocol UDP
Emeric Brun12941c82020-07-07 14:19:42 +02003384 is used. Currently those listeners are supported
3385 only in log-forward sections.
Emeric Brun3835c0d2020-07-07 09:46:09 +02003386 - 'udp6@' -> address is always IPv6 and protocol UDP
Emeric Brun12941c82020-07-07 14:19:42 +02003387 is used. Currently those listeners are supported
3388 only in log-forward sections.
Willy Tarreau24709282013-03-10 21:32:12 +01003389 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02003390 - 'abns@' -> address is in abstract namespace (Linux only).
3391 Note: since abstract sockets are not "rebindable", they
3392 do not cope well with multi-process mode during
3393 soft-restart, so it is better to avoid them if
3394 nbproc is greater than 1. The effect is that if the
3395 new process fails to start, only one of the old ones
3396 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01003397 - 'fd@<n>' -> use file descriptor <n> inherited from the
3398 parent. The fd must be bound and may or may not already
3399 be listening.
William Lallemand2fe7dd02018-09-11 16:51:29 +02003400 - 'sockpair@<n>'-> like fd@ but you must use the fd of a
3401 connected unix socket or of a socketpair. The bind waits
3402 to receive a FD over the unix socket and uses it as if it
3403 was the FD of an accept(). Should be used carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02003404 You may want to reference some environment variables in the
3405 address parameter, see section 2.3 about environment
3406 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01003407
Willy Tarreauc5011ca2010-03-22 11:53:56 +01003408 <port_range> is either a unique TCP port, or a port range for which the
3409 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003410 above. The port is mandatory for TCP listeners. Note that in
3411 the case of an IPv6 address, the port is always the number
3412 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01003413 - a numerical port (ex: '80')
3414 - a dash-delimited ports range explicitly stating the lower
3415 and upper bounds (ex: '2000-2100') which are included in
3416 the range.
3417
3418 Particular care must be taken against port ranges, because
3419 every <address:port> couple consumes one socket (= a file
3420 descriptor), so it's easy to consume lots of descriptors
3421 with a simple range, and to run out of sockets. Also, each
3422 <address:port> couple must be used only once among all
3423 instances running on a same system. Please note that binding
3424 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04003425 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01003426 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003427
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003428 <path> is a UNIX socket path beginning with a slash ('/'). This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01003429 alternative to the TCP listening port. HAProxy will then
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003430 receive UNIX connections on the socket located at this place.
3431 The path must begin with a slash and by default is absolute.
3432 It can be relative to the prefix defined by "unix-bind" in
3433 the global section. Note that the total length of the prefix
3434 followed by the socket path cannot exceed some system limits
3435 for UNIX sockets, which commonly are set to 107 characters.
3436
Willy Tarreaub6205fd2012-09-24 12:27:33 +02003437 <param*> is a list of parameters common to all sockets declared on the
3438 same line. These numerous parameters depend on OS and build
3439 options and have a complete section dedicated to them. Please
3440 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02003441
Willy Tarreau0ba27502007-12-24 16:55:16 +01003442 It is possible to specify a list of address:port combinations delimited by
3443 commas. The frontend will then listen on all of these addresses. There is no
3444 fixed limit to the number of addresses and ports which can be listened on in
3445 a frontend, as well as there is no limit to the number of "bind" statements
3446 in a frontend.
3447
3448 Example :
3449 listen http_proxy
3450 bind :80,:443
3451 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003452 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01003453
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02003454 listen http_https_proxy
3455 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02003456 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02003457
Willy Tarreau24709282013-03-10 21:32:12 +01003458 listen http_https_proxy_explicit
3459 bind ipv6@:80
3460 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
3461 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
3462
Willy Tarreaudad36a32013-03-11 01:20:04 +01003463 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02003464 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01003465
Willy Tarreau55dcaf62015-09-27 15:03:15 +02003466 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
3467 sun_path length is used for the address length. Some other programs
3468 such as socat use the string length only by default. Pass the option
3469 ",unix-tightsocklen=0" to any abstract socket definition in socat to
3470 make it compatible with HAProxy's.
3471
Willy Tarreauceb24bc2010-11-09 12:46:41 +01003472 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02003473 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003474
3475
Christopher Fauletff4121f2017-11-22 16:38:49 +01003476bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003477 Limit visibility of an instance to a certain set of processes numbers.
3478 May be used in sections : defaults | frontend | listen | backend
3479 yes | yes | yes | yes
3480 Arguments :
3481 all All process will see this instance. This is the default. It
3482 may be used to override a default value.
3483
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003484 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003485 option may be combined with other numbers.
3486
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003487 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003488 option may be combined with other numbers. Do not use it
3489 with less than 2 processes otherwise some instances might be
3490 missing from all processes.
3491
Christopher Fauletff4121f2017-11-22 16:38:49 +01003492 process_num The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003493 whose values must all be between 1 and 32 or 64 depending on
Christopher Fauletff4121f2017-11-22 16:38:49 +01003494 the machine's word size. Ranges can be partially defined. The
3495 higher bound can be omitted. In such case, it is replaced by
3496 the corresponding maximum value. If a proxy is bound to
3497 process numbers greater than the configured global.nbproc, it
3498 will either be forced to process #1 if a single process was
Willy Tarreau102df612014-05-07 23:56:38 +02003499 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003500
3501 This keyword limits binding of certain instances to certain processes. This
3502 is useful in order not to have too many processes listening to the same
3503 ports. For instance, on a dual-core machine, it might make sense to set
3504 'nbproc 2' in the global section, then distributes the listeners among 'odd'
3505 and 'even' instances.
3506
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003507 At the moment, it is not possible to reference more than 32 or 64 processes
3508 using this keyword, but this should be more than enough for most setups.
3509 Please note that 'all' really means all processes regardless of the machine's
3510 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003511
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02003512 Each "bind" line may further be limited to a subset of the proxy's processes,
3513 please consult the "process" bind keyword in section 5.1.
3514
Willy Tarreaub369a042014-09-16 13:21:03 +02003515 When a frontend has no explicit "bind-process" line, it tries to bind to all
3516 the processes referenced by its "bind" lines. That means that frontends can
3517 easily adapt to their listeners' processes.
3518
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003519 If some backends are referenced by frontends bound to other processes, the
3520 backend automatically inherits the frontend's processes.
3521
3522 Example :
3523 listen app_ip1
3524 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003525 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003526
3527 listen app_ip2
3528 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003529 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003530
3531 listen management
3532 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003533 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003534
Willy Tarreau110ecc12012-11-15 17:50:01 +01003535 listen management
3536 bind 10.0.0.4:80
3537 bind-process 1-4
3538
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02003539 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003540
3541
Willy Tarreau0ba27502007-12-24 16:55:16 +01003542capture cookie <name> len <length>
3543 Capture and log a cookie in the request and in the response.
3544 May be used in sections : defaults | frontend | listen | backend
3545 no | yes | yes | no
3546 Arguments :
3547 <name> is the beginning of the name of the cookie to capture. In order
3548 to match the exact name, simply suffix the name with an equal
3549 sign ('='). The full name will appear in the logs, which is
3550 useful with application servers which adjust both the cookie name
Davor Ocelice9ed2812017-12-25 17:49:28 +01003551 and value (e.g. ASPSESSIONXXX).
Willy Tarreau0ba27502007-12-24 16:55:16 +01003552
3553 <length> is the maximum number of characters to report in the logs, which
3554 include the cookie name, the equal sign and the value, all in the
3555 standard "name=value" form. The string will be truncated on the
3556 right if it exceeds <length>.
3557
3558 Only the first cookie is captured. Both the "cookie" request headers and the
3559 "set-cookie" response headers are monitored. This is particularly useful to
3560 check for application bugs causing session crossing or stealing between
3561 users, because generally the user's cookies can only change on a login page.
3562
3563 When the cookie was not presented by the client, the associated log column
3564 will report "-". When a request does not cause a cookie to be assigned by the
3565 server, a "-" is reported in the response column.
3566
3567 The capture is performed in the frontend only because it is necessary that
3568 the log format does not change for a given frontend depending on the
3569 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01003570 "capture cookie" statement in a frontend. The maximum capture length is set
3571 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
3572 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003573
3574 Example:
3575 capture cookie ASPSESSION len 32
3576
3577 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003578 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003579
3580
3581capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01003582 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003583 May be used in sections : defaults | frontend | listen | backend
3584 no | yes | yes | no
3585 Arguments :
3586 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003587 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01003588 appear in the requests, with the first letter of each word in
3589 upper case. The header name will not appear in the logs, only the
3590 value is reported, but the position in the logs is respected.
3591
3592 <length> is the maximum number of characters to extract from the value and
3593 report in the logs. The string will be truncated on the right if
3594 it exceeds <length>.
3595
Willy Tarreau4460d032012-11-21 23:37:37 +01003596 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01003597 value will be added to the logs between braces ('{}'). If multiple headers
3598 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003599 in the same order they were declared in the configuration. Non-existent
3600 headers will be logged just as an empty string. Common uses for request
3601 header captures include the "Host" field in virtual hosting environments, the
3602 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003603 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003604 environments to find where the request came from.
3605
3606 Note that when capturing headers such as "User-agent", some spaces may be
3607 logged, making the log analysis more difficult. Thus be careful about what
3608 you log if you know your log parser is not smart enough to rely on the
3609 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003610
Willy Tarreau0900abb2012-11-22 00:21:46 +01003611 There is no limit to the number of captured request headers nor to their
3612 length, though it is wise to keep them low to limit memory usage per session.
3613 In order to keep log format consistent for a same frontend, header captures
3614 can only be declared in a frontend. It is not possible to specify a capture
3615 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003616
3617 Example:
3618 capture request header Host len 15
3619 capture request header X-Forwarded-For len 15
Cyril Bontéd1b0f7c2015-10-26 22:37:39 +01003620 capture request header Referer len 15
Willy Tarreau0ba27502007-12-24 16:55:16 +01003621
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003622 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01003623 about logging.
3624
3625
3626capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01003627 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003628 May be used in sections : defaults | frontend | listen | backend
3629 no | yes | yes | no
3630 Arguments :
3631 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003632 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01003633 appear in the response, with the first letter of each word in
3634 upper case. The header name will not appear in the logs, only the
3635 value is reported, but the position in the logs is respected.
3636
3637 <length> is the maximum number of characters to extract from the value and
3638 report in the logs. The string will be truncated on the right if
3639 it exceeds <length>.
3640
Willy Tarreau4460d032012-11-21 23:37:37 +01003641 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01003642 result will be added to the logs between braces ('{}') after the captured
3643 request headers. If multiple headers are captured, they will be delimited by
3644 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003645 the configuration. Non-existent headers will be logged just as an empty
3646 string. Common uses for response header captures include the "Content-length"
3647 header which indicates how many bytes are expected to be returned, the
3648 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003649
Willy Tarreau0900abb2012-11-22 00:21:46 +01003650 There is no limit to the number of captured response headers nor to their
3651 length, though it is wise to keep them low to limit memory usage per session.
3652 In order to keep log format consistent for a same frontend, header captures
3653 can only be declared in a frontend. It is not possible to specify a capture
3654 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003655
3656 Example:
3657 capture response header Content-length len 9
3658 capture response header Location len 15
3659
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003660 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01003661 about logging.
3662
3663
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003664clitcpka-cnt <count>
3665 Sets the maximum number of keepalive probes TCP should send before dropping
3666 the connection on the client side.
3667 May be used in sections : defaults | frontend | listen | backend
3668 yes | yes | yes | no
3669 Arguments :
3670 <count> is the maximum number of keepalive probes.
3671
3672 This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword
3673 is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02003674 The availability of this setting depends on the operating system. It is
3675 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003676
3677 See also : "option clitcpka", "clitcpka-idle", "clitcpka-intvl".
3678
3679
3680clitcpka-idle <timeout>
3681 Sets the time the connection needs to remain idle before TCP starts sending
3682 keepalive probes, if enabled the sending of TCP keepalive packets on the
3683 client side.
3684 May be used in sections : defaults | frontend | listen | backend
3685 yes | yes | yes | no
3686 Arguments :
3687 <timeout> is the time the connection needs to remain idle before TCP starts
3688 sending keepalive probes. It is specified in seconds by default,
3689 but can be in any other unit if the number is suffixed by the
3690 unit, as explained at the top of this document.
3691
3692 This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword
3693 is not specified, system-wide TCP parameter (tcp_keepalive_time) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02003694 The availability of this setting depends on the operating system. It is
3695 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003696
3697 See also : "option clitcpka", "clitcpka-cnt", "clitcpka-intvl".
3698
3699
3700clitcpka-intvl <timeout>
3701 Sets the time between individual keepalive probes on the client side.
3702 May be used in sections : defaults | frontend | listen | backend
3703 yes | yes | yes | no
3704 Arguments :
3705 <timeout> is the time between individual keepalive probes. It is specified
3706 in seconds by default, but can be in any other unit if the number
3707 is suffixed by the unit, as explained at the top of this
3708 document.
3709
3710 This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword
3711 is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02003712 The availability of this setting depends on the operating system. It is
3713 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09003714
3715 See also : "option clitcpka", "clitcpka-cnt", "clitcpka-idle".
3716
3717
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003718compression algo <algorithm> ...
3719compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02003720compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02003721 Enable HTTP compression.
3722 May be used in sections : defaults | frontend | listen | backend
3723 yes | yes | yes | yes
3724 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003725 algo is followed by the list of supported compression algorithms.
3726 type is followed by the list of MIME types that will be compressed.
3727 offload makes haproxy work as a compression offloader only (see notes).
3728
3729 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01003730 identity this is mostly for debugging, and it was useful for developing
3731 the compression feature. Identity does not apply any change on
3732 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003733
Willy Tarreauc91840a2015-03-28 17:00:39 +01003734 gzip applies gzip compression. This setting is only available when
Baptiste Assmannf085d632015-12-21 17:57:32 +01003735 support for zlib or libslz was built in.
Willy Tarreauc91840a2015-03-28 17:00:39 +01003736
3737 deflate same as "gzip", but with deflate algorithm and zlib format.
3738 Note that this algorithm has ambiguous support on many
3739 browsers and no support at all from recent ones. It is
3740 strongly recommended not to use it for anything else than
3741 experimentation. This setting is only available when support
Baptiste Assmannf085d632015-12-21 17:57:32 +01003742 for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003743
Willy Tarreauc91840a2015-03-28 17:00:39 +01003744 raw-deflate same as "deflate" without the zlib wrapper, and used as an
3745 alternative when the browser wants "deflate". All major
3746 browsers understand it and despite violating the standards,
3747 it is known to work better than "deflate", at least on MSIE
3748 and some versions of Safari. Do not use it in conjunction
3749 with "deflate", use either one or the other since both react
3750 to the same Accept-Encoding token. This setting is only
Baptiste Assmannf085d632015-12-21 17:57:32 +01003751 available when support for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003752
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04003753 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003754 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04003755 If backend servers support HTTP compression, these directives
3756 will be no-op: haproxy will see the compressed response and will not
3757 compress again. If backend servers do not support HTTP compression and
3758 there is Accept-Encoding header in request, haproxy will compress the
3759 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02003760
3761 The "offload" setting makes haproxy remove the Accept-Encoding header to
3762 prevent backend servers from compressing responses. It is strongly
3763 recommended not to do this because this means that all the compression work
3764 will be done on the single point where haproxy is located. However in some
3765 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04003766 with broken HTTP compression implementation which can't be turned off.
3767 In that case haproxy can be used to prevent that gateway from emitting
3768 invalid payloads. In this case, simply removing the header in the
3769 configuration does not work because it applies before the header is parsed,
3770 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02003771 then be used for such scenarios. Note: for now, the "offload" setting is
3772 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02003773
William Lallemand05097442012-11-20 12:14:28 +01003774 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01003775 * the request does not advertise a supported compression algorithm in the
3776 "Accept-Encoding" header
3777 * the response message is not HTTP/1.1
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01003778 * HTTP status code is not one of 200, 201, 202, or 203
Baptiste Assmann650d53d2013-01-05 15:44:44 +01003779 * response contain neither a "Content-Length" header nor a
3780 "Transfer-Encoding" whose last value is "chunked"
3781 * response contains a "Content-Type" header whose first value starts with
3782 "multipart"
3783 * the response contains the "no-transform" value in the "Cache-control"
3784 header
3785 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
3786 and later
3787 * The response contains a "Content-Encoding" header, indicating that the
3788 response is already compressed (see compression offload)
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01003789 * The response contains an invalid "ETag" header or multiple ETag headers
William Lallemand05097442012-11-20 12:14:28 +01003790
Tim Duesterhusb229f012019-01-29 16:38:56 +01003791 Note: The compression does not emit the Warning header.
William Lallemand05097442012-11-20 12:14:28 +01003792
William Lallemand82fe75c2012-10-23 10:25:10 +02003793 Examples :
3794 compression algo gzip
3795 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01003796
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003797
Willy Tarreau55165fe2009-05-10 12:02:55 +02003798cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02003799 [ postonly ] [ preserve ] [ httponly ] [ secure ]
3800 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Christopher Faulet2f533902020-01-21 11:06:48 +01003801 [ dynamic ] [ attr <value> ]*
Willy Tarreau0ba27502007-12-24 16:55:16 +01003802 Enable cookie-based persistence in a backend.
3803 May be used in sections : defaults | frontend | listen | backend
3804 yes | no | yes | yes
3805 Arguments :
3806 <name> is the name of the cookie which will be monitored, modified or
3807 inserted in order to bring persistence. This cookie is sent to
3808 the client via a "Set-Cookie" header in the response, and is
3809 brought back by the client in a "Cookie" header in all requests.
3810 Special care should be taken to choose a name which does not
3811 conflict with any likely application cookie. Also, if the same
Davor Ocelice9ed2812017-12-25 17:49:28 +01003812 backends are subject to be used by the same clients (e.g.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003813 HTTP/HTTPS), care should be taken to use different cookie names
3814 between all backends if persistence between them is not desired.
3815
3816 rewrite This keyword indicates that the cookie will be provided by the
3817 server and that haproxy will have to modify its value to set the
3818 server's identifier in it. This mode is handy when the management
3819 of complex combinations of "Set-cookie" and "Cache-control"
3820 headers is left to the application. The application can then
3821 decide whether or not it is appropriate to emit a persistence
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003822 cookie. Since all responses should be monitored, this mode
3823 doesn't work in HTTP tunnel mode. Unless the application
Davor Ocelice9ed2812017-12-25 17:49:28 +01003824 behavior is very complex and/or broken, it is advised not to
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003825 start with this mode for new deployments. This keyword is
3826 incompatible with "insert" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003827
3828 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02003829 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003830
Willy Tarreaua79094d2010-08-31 22:54:15 +02003831 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003832 server. When used without the "preserve" option, if the server
Michael Prokop4438c602019-05-24 10:25:45 +02003833 emits a cookie with the same name, it will be removed before
Davor Ocelice9ed2812017-12-25 17:49:28 +01003834 processing. For this reason, this mode can be used to upgrade
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003835 existing configurations running in the "rewrite" mode. The cookie
3836 will only be a session cookie and will not be stored on the
3837 client's disk. By default, unless the "indirect" option is added,
3838 the server will see the cookies emitted by the client. Due to
3839 caching effects, it is generally wise to add the "nocache" or
3840 "postonly" keywords (see below). The "insert" keyword is not
3841 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003842
3843 prefix This keyword indicates that instead of relying on a dedicated
3844 cookie for the persistence, an existing one will be completed.
3845 This may be needed in some specific environments where the client
3846 does not support more than one single cookie and the application
3847 already needs it. In this case, whenever the server sets a cookie
3848 named <name>, it will be prefixed with the server's identifier
3849 and a delimiter. The prefix will be removed from all client
3850 requests so that the server still finds the cookie it emitted.
3851 Since all requests and responses are subject to being modified,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003852 this mode doesn't work with tunnel mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02003853 not compatible with "rewrite" and "insert". Note: it is highly
3854 recommended not to use "indirect" with "prefix", otherwise server
3855 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003856
Willy Tarreaua79094d2010-08-31 22:54:15 +02003857 indirect When this option is specified, no cookie will be emitted to a
3858 client which already has a valid one for the server which has
3859 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003860 it will be removed, unless the "preserve" option is also set. In
3861 "insert" mode, this will additionally remove cookies from the
3862 requests transmitted to the server, making the persistence
3863 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02003864 Note: it is highly recommended not to use "indirect" with
3865 "prefix", otherwise server cookie updates would not be sent to
3866 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003867
3868 nocache This option is recommended in conjunction with the insert mode
3869 when there is a cache between the client and HAProxy, as it
3870 ensures that a cacheable response will be tagged non-cacheable if
3871 a cookie needs to be inserted. This is important because if all
3872 persistence cookies are added on a cacheable home page for
3873 instance, then all customers will then fetch the page from an
3874 outer cache and will all share the same persistence cookie,
3875 leading to one server receiving much more traffic than others.
3876 See also the "insert" and "postonly" options.
3877
3878 postonly This option ensures that cookie insertion will only be performed
3879 on responses to POST requests. It is an alternative to the
3880 "nocache" option, because POST responses are not cacheable, so
3881 this ensures that the persistence cookie will never get cached.
3882 Since most sites do not need any sort of persistence before the
3883 first POST which generally is a login request, this is a very
3884 efficient method to optimize caching without risking to find a
3885 persistence cookie in the cache.
3886 See also the "insert" and "nocache" options.
3887
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003888 preserve This option may only be used with "insert" and/or "indirect". It
3889 allows the server to emit the persistence cookie itself. In this
3890 case, if a cookie is found in the response, haproxy will leave it
3891 untouched. This is useful in order to end persistence after a
3892 logout request for instance. For this, the server just has to
Davor Ocelice9ed2812017-12-25 17:49:28 +01003893 emit a cookie with an invalid value (e.g. empty) or with a date in
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003894 the past. By combining this mechanism with the "disable-on-404"
3895 check option, it is possible to perform a completely graceful
3896 shutdown because users will definitely leave the server after
3897 they logout.
3898
Willy Tarreau4992dd22012-05-31 21:02:17 +02003899 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
3900 when a cookie is inserted. This attribute is used so that a
3901 user agent doesn't share the cookie with non-HTTP components.
3902 Please check RFC6265 for more information on this attribute.
3903
3904 secure This option tells haproxy to add a "Secure" cookie attribute when
3905 a cookie is inserted. This attribute is used so that a user agent
3906 never emits this cookie over non-secure channels, which means
3907 that a cookie learned with this flag will be presented only over
3908 SSL/TLS connections. Please check RFC6265 for more information on
3909 this attribute.
3910
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003911 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003912 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01003913 name. If the domain begins with a dot, the browser is allowed to
3914 use it for any host ending with that name. It is also possible to
3915 specify several domain names by invoking this option multiple
3916 times. Some browsers might have small limits on the number of
3917 domains, so be careful when doing that. For the record, sending
3918 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003919
Willy Tarreau996a92c2010-10-13 19:30:47 +02003920 maxidle This option allows inserted cookies to be ignored after some idle
3921 time. It only works with insert-mode cookies. When a cookie is
3922 sent to the client, the date this cookie was emitted is sent too.
3923 Upon further presentations of this cookie, if the date is older
3924 than the delay indicated by the parameter (in seconds), it will
3925 be ignored. Otherwise, it will be refreshed if needed when the
3926 response is sent to the client. This is particularly useful to
3927 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003928 too long on the same server (e.g. after a farm size change). When
Willy Tarreau996a92c2010-10-13 19:30:47 +02003929 this option is set and a cookie has no date, it is always
3930 accepted, but gets refreshed in the response. This maintains the
3931 ability for admins to access their sites. Cookies that have a
3932 date in the future further than 24 hours are ignored. Doing so
3933 lets admins fix timezone issues without risking kicking users off
3934 the site.
3935
3936 maxlife This option allows inserted cookies to be ignored after some life
3937 time, whether they're in use or not. It only works with insert
3938 mode cookies. When a cookie is first sent to the client, the date
3939 this cookie was emitted is sent too. Upon further presentations
3940 of this cookie, if the date is older than the delay indicated by
3941 the parameter (in seconds), it will be ignored. If the cookie in
3942 the request has no date, it is accepted and a date will be set.
3943 Cookies that have a date in the future further than 24 hours are
3944 ignored. Doing so lets admins fix timezone issues without risking
3945 kicking users off the site. Contrary to maxidle, this value is
3946 not refreshed, only the first visit date counts. Both maxidle and
3947 maxlife may be used at the time. This is particularly useful to
3948 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003949 too long on the same server (e.g. after a farm size change). This
Willy Tarreau996a92c2010-10-13 19:30:47 +02003950 is stronger than the maxidle method in that it forces a
3951 redispatch after some absolute delay.
3952
Olivier Houchard4e694042017-03-14 20:01:29 +01003953 dynamic Activate dynamic cookies. When used, a session cookie is
3954 dynamically created for each server, based on the IP and port
3955 of the server, and a secret key, specified in the
3956 "dynamic-cookie-key" backend directive.
3957 The cookie will be regenerated each time the IP address change,
3958 and is only generated for IPv4/IPv6.
3959
Christopher Faulet2f533902020-01-21 11:06:48 +01003960 attr This option tells haproxy to add an extra attribute when a
3961 cookie is inserted. The attribute value can contain any
3962 characters except control ones or ";". This option may be
3963 repeated.
3964
Willy Tarreau0ba27502007-12-24 16:55:16 +01003965 There can be only one persistence cookie per HTTP backend, and it can be
3966 declared in a defaults section. The value of the cookie will be the value
3967 indicated after the "cookie" keyword in a "server" statement. If no cookie
3968 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02003969
Willy Tarreau0ba27502007-12-24 16:55:16 +01003970 Examples :
3971 cookie JSESSIONID prefix
3972 cookie SRV insert indirect nocache
3973 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02003974 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01003975
Willy Tarreau294d0f02015-08-10 19:40:12 +02003976 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003977
Willy Tarreau983e01e2010-01-11 18:42:06 +01003978
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003979declare capture [ request | response ] len <length>
3980 Declares a capture slot.
3981 May be used in sections : defaults | frontend | listen | backend
3982 no | yes | yes | no
3983 Arguments:
3984 <length> is the length allowed for the capture.
3985
3986 This declaration is only available in the frontend or listen section, but the
3987 reserved slot can be used in the backends. The "request" keyword allocates a
3988 capture slot for use in the request, and "response" allocates a capture slot
3989 for use in the response.
3990
3991 See also: "capture-req", "capture-res" (sample converters),
Baptiste Assmann5ac425c2015-10-21 23:13:46 +02003992 "capture.req.hdr", "capture.res.hdr" (sample fetches),
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003993 "http-request capture" and "http-response capture".
3994
3995
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003996default-server [param*]
3997 Change default options for a server in a backend
3998 May be used in sections : defaults | frontend | listen | backend
3999 yes | no | yes | yes
4000 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01004001 <param*> is a list of parameters for this server. The "default-server"
4002 keyword accepts an important number of options and has a complete
4003 section dedicated to it. Please refer to section 5 for more
4004 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004005
Willy Tarreau983e01e2010-01-11 18:42:06 +01004006 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01004007 default-server inter 1000 weight 13
4008
4009 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01004010
Willy Tarreau983e01e2010-01-11 18:42:06 +01004011
Willy Tarreau0ba27502007-12-24 16:55:16 +01004012default_backend <backend>
4013 Specify the backend to use when no "use_backend" rule has been matched.
4014 May be used in sections : defaults | frontend | listen | backend
4015 yes | yes | yes | no
4016 Arguments :
4017 <backend> is the name of the backend to use.
4018
4019 When doing content-switching between frontend and backends using the
4020 "use_backend" keyword, it is often useful to indicate which backend will be
4021 used when no rule has matched. It generally is the dynamic backend which
4022 will catch all undetermined requests.
4023
Willy Tarreau0ba27502007-12-24 16:55:16 +01004024 Example :
4025
4026 use_backend dynamic if url_dyn
4027 use_backend static if url_css url_img extension_img
4028 default_backend dynamic
4029
Willy Tarreau98d04852015-05-26 12:18:29 +02004030 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004031
Willy Tarreau0ba27502007-12-24 16:55:16 +01004032
Baptiste Assmann27f51342013-10-09 06:51:49 +02004033description <string>
4034 Describe a listen, frontend or backend.
4035 May be used in sections : defaults | frontend | listen | backend
4036 no | yes | yes | yes
4037 Arguments : string
4038
4039 Allows to add a sentence to describe the related object in the HAProxy HTML
4040 stats page. The description will be printed on the right of the object name
4041 it describes.
4042 No need to backslash spaces in the <string> arguments.
4043
4044
Willy Tarreau0ba27502007-12-24 16:55:16 +01004045disabled
4046 Disable a proxy, frontend or backend.
4047 May be used in sections : defaults | frontend | listen | backend
4048 yes | yes | yes | yes
4049 Arguments : none
4050
4051 The "disabled" keyword is used to disable an instance, mainly in order to
4052 liberate a listening port or to temporarily disable a service. The instance
4053 will still be created and its configuration will be checked, but it will be
4054 created in the "stopped" state and will appear as such in the statistics. It
4055 will not receive any traffic nor will it send any health-checks or logs. It
4056 is possible to disable many instances at once by adding the "disabled"
4057 keyword in a "defaults" section.
4058
4059 See also : "enabled"
4060
4061
Willy Tarreau5ce94572010-06-07 14:35:41 +02004062dispatch <address>:<port>
4063 Set a default server address
4064 May be used in sections : defaults | frontend | listen | backend
4065 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02004066 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02004067
4068 <address> is the IPv4 address of the default server. Alternatively, a
4069 resolvable hostname is supported, but this name will be resolved
4070 during start-up.
4071
4072 <ports> is a mandatory port specification. All connections will be sent
4073 to this port, and it is not permitted to use port offsets as is
4074 possible with normal servers.
4075
Willy Tarreau787aed52011-04-15 06:45:37 +02004076 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02004077 server can take the connection. In the past it was used to forward non
4078 persistent connections to an auxiliary load balancer. Due to its simple
4079 syntax, it has also been used for simple TCP relays. It is recommended not to
4080 use it for more clarity, and to use the "server" directive instead.
4081
4082 See also : "server"
4083
Olivier Houchard4e694042017-03-14 20:01:29 +01004084
4085dynamic-cookie-key <string>
4086 Set the dynamic cookie secret key for a backend.
4087 May be used in sections : defaults | frontend | listen | backend
4088 yes | no | yes | yes
4089 Arguments : The secret key to be used.
4090
4091 When dynamic cookies are enabled (see the "dynamic" directive for cookie),
Davor Ocelice9ed2812017-12-25 17:49:28 +01004092 a dynamic cookie is created for each server (unless one is explicitly
Olivier Houchard4e694042017-03-14 20:01:29 +01004093 specified on the "server" line), using a hash of the IP address of the
4094 server, the TCP port, and the secret key.
Davor Ocelice9ed2812017-12-25 17:49:28 +01004095 That way, we can ensure session persistence across multiple load-balancers,
Olivier Houchard4e694042017-03-14 20:01:29 +01004096 even if servers are dynamically added or removed.
Willy Tarreau5ce94572010-06-07 14:35:41 +02004097
Willy Tarreau0ba27502007-12-24 16:55:16 +01004098enabled
4099 Enable a proxy, frontend or backend.
4100 May be used in sections : defaults | frontend | listen | backend
4101 yes | yes | yes | yes
4102 Arguments : none
4103
4104 The "enabled" keyword is used to explicitly enable an instance, when the
4105 defaults has been set to "disabled". This is very rarely used.
4106
4107 See also : "disabled"
4108
4109
4110errorfile <code> <file>
4111 Return a file contents instead of errors generated by HAProxy
4112 May be used in sections : defaults | frontend | listen | backend
4113 yes | yes | yes | yes
4114 Arguments :
4115 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004116 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02004117 413, 425, 429, 500, 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004118
4119 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004120 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01004121 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01004122 error pages, and to use absolute paths, since files are read
4123 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01004124
4125 It is important to understand that this keyword is not meant to rewrite
4126 errors returned by the server, but errors detected and returned by HAProxy.
4127 This is why the list of supported errors is limited to a small set.
4128
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004129 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
4130
Christopher Faulet70170672020-05-18 17:42:48 +02004131 The files are parsed when HAProxy starts and must be valid according to the
4132 HTTP specification. They should not exceed the configured buffer size
4133 (BUFSIZE), which generally is 16 kB, otherwise an internal error will be
4134 returned. It is also wise not to put any reference to local contents
4135 (e.g. images) in order to avoid loops between the client and HAProxy when all
4136 servers are down, causing an error to be returned instead of an
4137 image. Finally, The response cannot exceed (tune.bufsize - tune.maxrewrite)
4138 so that "http-after-response" rules still have room to operate (see
4139 "tune.maxrewrite").
Willy Tarreau59140a22009-02-22 12:02:30 +01004140
Willy Tarreau0ba27502007-12-24 16:55:16 +01004141 The files are read at the same time as the configuration and kept in memory.
4142 For this reason, the errors continue to be returned even when the process is
4143 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01004144 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01004145 403 status code and interrogating a blocked URL.
4146
Christopher Faulet3b967c12020-05-15 15:47:44 +02004147 See also : "http-error", "errorloc", "errorloc302", "errorloc303"
Willy Tarreau0ba27502007-12-24 16:55:16 +01004148
Willy Tarreau59140a22009-02-22 12:02:30 +01004149 Example :
4150 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau989222a2016-01-15 10:26:26 +01004151 errorfile 408 /dev/null # work around Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01004152 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
4153 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
4154
Willy Tarreau2769aa02007-12-27 18:26:09 +01004155
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004156errorfiles <name> [<code> ...]
4157 Import, fully or partially, the error files defined in the <name> http-errors
4158 section.
4159 May be used in sections : defaults | frontend | listen | backend
4160 yes | yes | yes | yes
4161 Arguments :
4162 <name> is the name of an existing http-errors section.
4163
4164 <code> is a HTTP status code. Several status code may be listed.
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004165 Currently, HAProxy is capable of generating codes 200, 400, 401,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02004166 403, 404, 405, 407, 408, 410, 413, 425, 429, 500, 502, 503, and 504.
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004167
4168 Errors defined in the http-errors section with the name <name> are imported
4169 in the current proxy. If no status code is specified, all error files of the
4170 http-errors section are imported. Otherwise, only error files associated to
4171 the listed status code are imported. Those error files override the already
4172 defined custom errors for the proxy. And they may be overridden by following
Daniel Corbett67a82712020-07-06 23:01:19 -04004173 ones. Functionally, it is exactly the same as declaring all error files by
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004174 hand using "errorfile" directives.
4175
Christopher Faulet3b967c12020-05-15 15:47:44 +02004176 See also : "http-error", "errorfile", "errorloc", "errorloc302" ,
4177 "errorloc303" and section 3.8 about http-errors.
Christopher Faulet76edc0f2020-01-13 15:52:01 +01004178
4179 Example :
4180 errorfiles generic
4181 errorfiles site-1 403 404
4182
4183
Willy Tarreau2769aa02007-12-27 18:26:09 +01004184errorloc <code> <url>
4185errorloc302 <code> <url>
4186 Return an HTTP redirection to a URL instead of errors generated by HAProxy
4187 May be used in sections : defaults | frontend | listen | backend
4188 yes | yes | yes | yes
4189 Arguments :
4190 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004191 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02004192 413, 425, 429, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004193
4194 <url> it is the exact contents of the "Location" header. It may contain
4195 either a relative URI to an error page hosted on the same site,
4196 or an absolute URI designating an error page on another site.
4197 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01004198 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01004199
4200 It is important to understand that this keyword is not meant to rewrite
4201 errors returned by the server, but errors detected and returned by HAProxy.
4202 This is why the list of supported errors is limited to a small set.
4203
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004204 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
4205
Willy Tarreau2769aa02007-12-27 18:26:09 +01004206 Note that both keyword return the HTTP 302 status code, which tells the
4207 client to fetch the designated URL using the same HTTP method. This can be
4208 quite problematic in case of non-GET methods such as POST, because the URL
4209 sent to the client might not be allowed for something other than GET. To
Willy Tarreau989222a2016-01-15 10:26:26 +01004210 work around this problem, please use "errorloc303" which send the HTTP 303
Willy Tarreau2769aa02007-12-27 18:26:09 +01004211 status code, indicating to the client that the URL must be fetched with a GET
4212 request.
4213
Christopher Faulet3b967c12020-05-15 15:47:44 +02004214 See also : "http-error", "errorfile", "errorloc303"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004215
4216
4217errorloc303 <code> <url>
4218 Return an HTTP redirection to a URL instead of errors generated by HAProxy
4219 May be used in sections : defaults | frontend | listen | backend
4220 yes | yes | yes | yes
4221 Arguments :
4222 <code> is the HTTP status code. Currently, HAProxy is capable of
Christopher Faulet612f2ea2020-05-27 09:57:28 +02004223 generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02004224 413, 425, 429, 500, 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004225
4226 <url> it is the exact contents of the "Location" header. It may contain
4227 either a relative URI to an error page hosted on the same site,
4228 or an absolute URI designating an error page on another site.
4229 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01004230 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01004231
4232 It is important to understand that this keyword is not meant to rewrite
4233 errors returned by the server, but errors detected and returned by HAProxy.
4234 This is why the list of supported errors is limited to a small set.
4235
Willy Tarreauae94d4d2011-05-11 16:28:49 +02004236 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
4237
Willy Tarreau2769aa02007-12-27 18:26:09 +01004238 Note that both keyword return the HTTP 303 status code, which tells the
4239 client to fetch the designated URL using the same HTTP GET method. This
4240 solves the usual problems associated with "errorloc" and the 302 code. It is
4241 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01004242 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004243
Christopher Faulet3b967c12020-05-15 15:47:44 +02004244 See also : "http-error", "errorfile", "errorloc", "errorloc302"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004245
4246
Simon Horman51a1cf62015-02-03 13:00:44 +09004247email-alert from <emailaddr>
4248 Declare the from email address to be used in both the envelope and header
Davor Ocelice9ed2812017-12-25 17:49:28 +01004249 of email alerts. This is the address that email alerts are sent from.
Simon Horman51a1cf62015-02-03 13:00:44 +09004250 May be used in sections: defaults | frontend | listen | backend
4251 yes | yes | yes | yes
4252
4253 Arguments :
4254
4255 <emailaddr> is the from email address to use when sending email alerts
4256
4257 Also requires "email-alert mailers" and "email-alert to" to be set
4258 and if so sending email alerts is enabled for the proxy.
4259
Simon Horman64e34162015-02-06 11:11:57 +09004260 See also : "email-alert level", "email-alert mailers",
Cyril Bonté307ee1e2015-09-28 23:16:06 +02004261 "email-alert myhostname", "email-alert to", section 3.6 about
4262 mailers.
Simon Horman64e34162015-02-06 11:11:57 +09004263
4264
4265email-alert level <level>
4266 Declare the maximum log level of messages for which email alerts will be
4267 sent. This acts as a filter on the sending of email alerts.
4268 May be used in sections: defaults | frontend | listen | backend
4269 yes | yes | yes | yes
4270
4271 Arguments :
4272
4273 <level> One of the 8 syslog levels:
4274 emerg alert crit err warning notice info debug
4275 The above syslog levels are ordered from lowest to highest.
4276
4277 By default level is alert
4278
4279 Also requires "email-alert from", "email-alert mailers" and
4280 "email-alert to" to be set and if so sending email alerts is enabled
4281 for the proxy.
4282
Simon Horman1421e212015-04-30 13:10:35 +09004283 Alerts are sent when :
4284
4285 * An un-paused server is marked as down and <level> is alert or lower
4286 * A paused server is marked as down and <level> is notice or lower
4287 * A server is marked as up or enters the drain state and <level>
4288 is notice or lower
4289 * "option log-health-checks" is enabled, <level> is info or lower,
4290 and a health check status update occurs
4291
Simon Horman64e34162015-02-06 11:11:57 +09004292 See also : "email-alert from", "email-alert mailers",
4293 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09004294 section 3.6 about mailers.
4295
4296
4297email-alert mailers <mailersect>
4298 Declare the mailers to be used when sending email alerts
4299 May be used in sections: defaults | frontend | listen | backend
4300 yes | yes | yes | yes
4301
4302 Arguments :
4303
4304 <mailersect> is the name of the mailers section to send email alerts.
4305
4306 Also requires "email-alert from" and "email-alert to" to be set
4307 and if so sending email alerts is enabled for the proxy.
4308
Simon Horman64e34162015-02-06 11:11:57 +09004309 See also : "email-alert from", "email-alert level", "email-alert myhostname",
4310 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09004311
4312
4313email-alert myhostname <hostname>
4314 Declare the to hostname address to be used when communicating with
4315 mailers.
4316 May be used in sections: defaults | frontend | listen | backend
4317 yes | yes | yes | yes
4318
4319 Arguments :
4320
Baptiste Assmann738bad92015-12-21 15:27:53 +01004321 <hostname> is the hostname to use when communicating with mailers
Simon Horman51a1cf62015-02-03 13:00:44 +09004322
4323 By default the systems hostname is used.
4324
4325 Also requires "email-alert from", "email-alert mailers" and
4326 "email-alert to" to be set and if so sending email alerts is enabled
4327 for the proxy.
4328
Simon Horman64e34162015-02-06 11:11:57 +09004329 See also : "email-alert from", "email-alert level", "email-alert mailers",
4330 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09004331
4332
4333email-alert to <emailaddr>
Davor Ocelice9ed2812017-12-25 17:49:28 +01004334 Declare both the recipient address in the envelope and to address in the
Simon Horman51a1cf62015-02-03 13:00:44 +09004335 header of email alerts. This is the address that email alerts are sent to.
4336 May be used in sections: defaults | frontend | listen | backend
4337 yes | yes | yes | yes
4338
4339 Arguments :
4340
4341 <emailaddr> is the to email address to use when sending email alerts
4342
4343 Also requires "email-alert mailers" and "email-alert to" to be set
4344 and if so sending email alerts is enabled for the proxy.
4345
Simon Horman64e34162015-02-06 11:11:57 +09004346 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09004347 "email-alert myhostname", section 3.6 about mailers.
4348
4349
Willy Tarreau4de91492010-01-22 19:10:05 +01004350force-persist { if | unless } <condition>
4351 Declare a condition to force persistence on down servers
4352 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01004353 no | no | yes | yes
Willy Tarreau4de91492010-01-22 19:10:05 +01004354
4355 By default, requests are not dispatched to down servers. It is possible to
4356 force this using "option persist", but it is unconditional and redispatches
4357 to a valid server if "option redispatch" is set. That leaves with very little
4358 possibilities to force some requests to reach a server which is artificially
4359 marked down for maintenance operations.
4360
4361 The "force-persist" statement allows one to declare various ACL-based
4362 conditions which, when met, will cause a request to ignore the down status of
4363 a server and still try to connect to it. That makes it possible to start a
4364 server, still replying an error to the health checks, and run a specially
4365 configured browser to test the service. Among the handy methods, one could
4366 use a specific source IP address, or a specific cookie. The cookie also has
4367 the advantage that it can easily be added/removed on the browser from a test
4368 page. Once the service is validated, it is then possible to open the service
4369 to the world by returning a valid response to health checks.
4370
4371 The forced persistence is enabled when an "if" condition is met, or unless an
4372 "unless" condition is met. The final redispatch is always disabled when this
4373 is used.
4374
Cyril Bonté0d4bf012010-04-25 23:21:46 +02004375 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02004376 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01004377
Christopher Fauletc3fe5332016-04-07 15:30:10 +02004378
4379filter <name> [param*]
4380 Add the filter <name> in the filter list attached to the proxy.
4381 May be used in sections : defaults | frontend | listen | backend
4382 no | yes | yes | yes
4383 Arguments :
4384 <name> is the name of the filter. Officially supported filters are
4385 referenced in section 9.
4386
Tim Düsterhus4896c442016-11-29 02:15:19 +01004387 <param*> is a list of parameters accepted by the filter <name>. The
Christopher Fauletc3fe5332016-04-07 15:30:10 +02004388 parsing of these parameters are the responsibility of the
Tim Düsterhus4896c442016-11-29 02:15:19 +01004389 filter. Please refer to the documentation of the corresponding
4390 filter (section 9) for all details on the supported parameters.
Christopher Fauletc3fe5332016-04-07 15:30:10 +02004391
4392 Multiple occurrences of the filter line can be used for the same proxy. The
4393 same filter can be referenced many times if needed.
4394
4395 Example:
4396 listen
4397 bind *:80
4398
4399 filter trace name BEFORE-HTTP-COMP
4400 filter compression
4401 filter trace name AFTER-HTTP-COMP
4402
4403 compression algo gzip
4404 compression offload
4405
4406 server srv1 192.168.0.1:80
4407
4408 See also : section 9.
4409
Willy Tarreau4de91492010-01-22 19:10:05 +01004410
Willy Tarreau2769aa02007-12-27 18:26:09 +01004411fullconn <conns>
4412 Specify at what backend load the servers will reach their maxconn
4413 May be used in sections : defaults | frontend | listen | backend
4414 yes | no | yes | yes
4415 Arguments :
4416 <conns> is the number of connections on the backend which will make the
4417 servers use the maximal number of connections.
4418
Willy Tarreau198a7442008-01-17 12:05:32 +01004419 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01004420 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01004421 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01004422 load. The server will then always accept at least <minconn> connections,
4423 never more than <maxconn>, and the limit will be on the ramp between both
4424 values when the backend has less than <conns> concurrent connections. This
4425 makes it possible to limit the load on the servers during normal loads, but
4426 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004427 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01004428
Willy Tarreaufbb78422011-06-05 15:38:35 +02004429 Since it's hard to get this value right, haproxy automatically sets it to
4430 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01004431 backend (based on "use_backend" and "default_backend" rules). That way it's
4432 safe to leave it unset. However, "use_backend" involving dynamic names are
4433 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02004434
Willy Tarreau2769aa02007-12-27 18:26:09 +01004435 Example :
4436 # The servers will accept between 100 and 1000 concurrent connections each
4437 # and the maximum of 1000 will be reached when the backend reaches 10000
4438 # connections.
4439 backend dynamic
4440 fullconn 10000
4441 server srv1 dyn1:80 minconn 100 maxconn 1000
4442 server srv2 dyn2:80 minconn 100 maxconn 1000
4443
4444 See also : "maxconn", "server"
4445
4446
4447grace <time>
4448 Maintain a proxy operational for some time after a soft stop
4449 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01004450 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01004451 Arguments :
4452 <time> is the time (by default in milliseconds) for which the instance
4453 will remain operational with the frontend sockets still listening
4454 when a soft-stop is received via the SIGUSR1 signal.
4455
4456 This may be used to ensure that the services disappear in a certain order.
4457 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01004458 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01004459 needed by the equipment to detect the failure.
4460
4461 Note that currently, there is very little benefit in using this parameter,
4462 and it may in fact complicate the soft-reconfiguration process more than
4463 simplify it.
4464
Willy Tarreau0ba27502007-12-24 16:55:16 +01004465
Andrew Rodland17be45e2016-10-25 17:04:12 -04004466hash-balance-factor <factor>
4467 Specify the balancing factor for bounded-load consistent hashing
4468 May be used in sections : defaults | frontend | listen | backend
4469 yes | no | no | yes
4470 Arguments :
4471 <factor> is the control for the maximum number of concurrent requests to
4472 send to a server, expressed as a percentage of the average number
Frédéric Lécaille93d33162019-03-06 09:35:59 +01004473 of concurrent requests across all of the active servers.
Andrew Rodland17be45e2016-10-25 17:04:12 -04004474
4475 Specifying a "hash-balance-factor" for a server with "hash-type consistent"
4476 enables an algorithm that prevents any one server from getting too many
4477 requests at once, even if some hash buckets receive many more requests than
4478 others. Setting <factor> to 0 (the default) disables the feature. Otherwise,
4479 <factor> is a percentage greater than 100. For example, if <factor> is 150,
4480 then no server will be allowed to have a load more than 1.5 times the average.
4481 If server weights are used, they will be respected.
4482
4483 If the first-choice server is disqualified, the algorithm will choose another
4484 server based on the request hash, until a server with additional capacity is
4485 found. A higher <factor> allows more imbalance between the servers, while a
4486 lower <factor> means that more servers will be checked on average, affecting
4487 performance. Reasonable values are from 125 to 200.
4488
Willy Tarreau760e81d2018-05-03 07:20:40 +02004489 This setting is also used by "balance random" which internally relies on the
4490 consistent hashing mechanism.
4491
Andrew Rodland17be45e2016-10-25 17:04:12 -04004492 See also : "balance" and "hash-type".
4493
4494
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004495hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004496 Specify a method to use for mapping hashes to servers
4497 May be used in sections : defaults | frontend | listen | backend
4498 yes | no | yes | yes
4499 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04004500 <method> is the method used to select a server from the hash computed by
4501 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004502
Bhaskar98634f02013-10-29 23:30:51 -04004503 map-based the hash table is a static array containing all alive servers.
4504 The hashes will be very smooth, will consider weights, but
4505 will be static in that weight changes while a server is up
4506 will be ignored. This means that there will be no slow start.
4507 Also, since a server is selected by its position in the array,
4508 most mappings are changed when the server count changes. This
4509 means that when a server goes up or down, or when a server is
4510 added to a farm, most connections will be redistributed to
4511 different servers. This can be inconvenient with caches for
4512 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01004513
Bhaskar98634f02013-10-29 23:30:51 -04004514 consistent the hash table is a tree filled with many occurrences of each
4515 server. The hash key is looked up in the tree and the closest
4516 server is chosen. This hash is dynamic, it supports changing
4517 weights while the servers are up, so it is compatible with the
4518 slow start feature. It has the advantage that when a server
4519 goes up or down, only its associations are moved. When a
4520 server is added to the farm, only a few part of the mappings
4521 are redistributed, making it an ideal method for caches.
4522 However, due to its principle, the distribution will never be
4523 very smooth and it may sometimes be necessary to adjust a
4524 server's weight or its ID to get a more balanced distribution.
4525 In order to get the same distribution on multiple load
4526 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004527 same IDs. Note: consistent hash uses sdbm and avalanche if no
4528 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04004529
4530 <function> is the hash function to be used :
4531
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03004532 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04004533 reimplementation of ndbm) database library. It was found to do
4534 well in scrambling bits, causing better distribution of the keys
4535 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004536 function with good distribution, unless the total server weight
4537 is a multiple of 64, in which case applying the avalanche
4538 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04004539
4540 djb2 this function was first proposed by Dan Bernstein many years ago
4541 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004542 function provides a better distribution than sdbm. It generally
4543 works well with text-based inputs though it can perform extremely
4544 poorly with numeric-only input or when the total server weight is
4545 a multiple of 33, unless the avalanche modifier is also used.
4546
Willy Tarreaua0f42712013-11-14 14:30:35 +01004547 wt6 this function was designed for haproxy while testing other
4548 functions in the past. It is not as smooth as the other ones, but
4549 is much less sensible to the input data set or to the number of
4550 servers. It can make sense as an alternative to sdbm+avalanche or
4551 djb2+avalanche for consistent hashing or when hashing on numeric
4552 data such as a source IP address or a visitor identifier in a URL
4553 parameter.
4554
Willy Tarreau324f07f2015-01-20 19:44:50 +01004555 crc32 this is the most common CRC32 implementation as used in Ethernet,
4556 gzip, PNG, etc. It is slower than the other ones but may provide
4557 a better distribution or less predictable results especially when
4558 used on strings.
4559
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004560 <modifier> indicates an optional method applied after hashing the key :
4561
4562 avalanche This directive indicates that the result from the hash
4563 function above should not be used in its raw form but that
4564 a 4-byte full avalanche hash must be applied first. The
4565 purpose of this step is to mix the resulting bits from the
4566 previous hash in order to avoid any undesired effect when
4567 the input contains some limited values or when the number of
4568 servers is a multiple of one of the hash's components (64
4569 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
4570 result less predictable, but it's also not as smooth as when
4571 using the original function. Some testing might be needed
4572 with some workloads. This hash is one of the many proposed
4573 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004574
Bhaskar98634f02013-10-29 23:30:51 -04004575 The default hash type is "map-based" and is recommended for most usages. The
4576 default function is "sdbm", the selection of a function should be based on
4577 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004578
Andrew Rodland17be45e2016-10-25 17:04:12 -04004579 See also : "balance", "hash-balance-factor", "server"
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004580
4581
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01004582http-after-response <action> <options...> [ { if | unless } <condition> ]
4583 Access control for all Layer 7 responses (server, applet/service and internal
4584 ones).
4585
4586 May be used in sections: defaults | frontend | listen | backend
4587 no | yes | yes | yes
4588
4589 The http-after-response statement defines a set of rules which apply to layer
4590 7 processing. The rules are evaluated in their declaration order when they
4591 are met in a frontend, listen or backend section. Any rule may optionally be
4592 followed by an ACL-based condition, in which case it will only be evaluated
4593 if the condition is true. Since these rules apply on responses, the backend
4594 rules are applied first, followed by the frontend's rules.
4595
4596 Unlike http-response rules, these ones are applied on all responses, the
4597 server ones but also to all responses generated by HAProxy. These rules are
4598 evaluated at the end of the responses analysis, before the data forwarding.
4599
4600 The first keyword is the rule's action. The supported actions are described
4601 below.
4602
4603 There is no limit to the number of http-after-response statements per
4604 instance.
4605
4606 Example:
4607 http-after-response set-header Strict-Transport-Security "max-age=31536000"
4608 http-after-response set-header Cache-Control "no-store,no-cache,private"
4609 http-after-response set-header Pragma "no-cache"
4610
4611http-after-response add-header <name> <fmt> [ { if | unless } <condition> ]
4612
4613 This appends an HTTP header field whose name is specified in <name> and whose
4614 value is defined by <fmt> which follows the log-format rules (see Custom Log
4615 Format in section 8.2.4). This may be used to send a cookie to a client for
4616 example, or to pass some internal information.
4617 This rule is not final, so it is possible to add other similar rules.
4618 Note that header addition is performed immediately, so one rule might reuse
4619 the resulting header from a previous rule.
4620
4621http-after-response allow [ { if | unless } <condition> ]
4622
4623 This stops the evaluation of the rules and lets the response pass the check.
4624 No further "http-after-response" rules are evaluated.
4625
4626http-after-response del-header <name> [ { if | unless } <condition> ]
4627
4628 This removes all HTTP header fields whose name is specified in <name>.
4629
4630http-after-response replace-header <name> <regex-match> <replace-fmt>
4631 [ { if | unless } <condition> ]
4632
4633 This works like "http-response replace-header".
4634
4635 Example:
4636 http-after-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
4637
4638 # applied to:
4639 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
4640
4641 # outputs:
4642 Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
4643
4644 # assuming the backend IP is 192.168.1.20.
4645
4646http-after-response replace-value <name> <regex-match> <replace-fmt>
4647 [ { if | unless } <condition> ]
4648
4649 This works like "http-response replace-value".
4650
4651 Example:
4652 http-after-response replace-value Cache-control ^public$ private
4653
4654 # applied to:
4655 Cache-Control: max-age=3600, public
4656
4657 # outputs:
4658 Cache-Control: max-age=3600, private
4659
4660http-after-response set-header <name> <fmt> [ { if | unless } <condition> ]
4661
4662 This does the same as "add-header" except that the header name is first
4663 removed if it existed. This is useful when passing security information to
4664 the server, where the header must not be manipulated by external users.
4665
4666http-after-response set-status <status> [reason <str>]
4667 [ { if | unless } <condition> ]
4668
4669 This replaces the response status code with <status> which must be an integer
4670 between 100 and 999. Optionally, a custom reason text can be provided defined
4671 by <str>, or the default reason for the specified code will be used as a
4672 fallback.
4673
4674 Example:
4675 # return "431 Request Header Fields Too Large"
4676 http-response set-status 431
4677 # return "503 Slow Down", custom reason
4678 http-response set-status 503 reason "Slow Down"
4679
4680http-after-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
4681
4682 This is used to set the contents of a variable. The variable is declared
4683 inline.
4684
4685 Arguments:
4686 <var-name> The name of the variable starts with an indication about its
4687 scope. The scopes allowed are:
4688 "proc" : the variable is shared with the whole process
4689 "sess" : the variable is shared with the whole session
4690 "txn" : the variable is shared with the transaction
4691 (request and response)
4692 "req" : the variable is shared only during request
4693 processing
4694 "res" : the variable is shared only during response
4695 processing
4696 This prefix is followed by a name. The separator is a '.'.
4697 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
4698 and '_'.
4699
4700 <expr> Is a standard HAProxy expression formed by a sample-fetch
4701 followed by some converters.
4702
4703 Example:
4704 http-after-response set-var(sess.last_redir) res.hdr(location)
4705
4706http-after-response strict-mode { on | off }
4707
4708 This enables or disables the strict rewriting mode for following rules. It
4709 does not affect rules declared before it and it is only applicable on rules
4710 performing a rewrite on the responses. When the strict mode is enabled, any
4711 rewrite failure triggers an internal error. Otherwise, such errors are
4712 silently ignored. The purpose of the strict rewriting mode is to make some
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05004713 rewrites optional while others must be performed to continue the response
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01004714 processing.
4715
4716 By default, the strict rewriting mode is enabled. Its value is also reset
4717 when a ruleset evaluation ends. So, for instance, if you change the mode on
Daniel Corbett67a82712020-07-06 23:01:19 -04004718 the backend, the default mode is restored when HAProxy starts the frontend
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01004719 rules evaluation.
4720
4721http-after-response unset-var(<var-name>) [ { if | unless } <condition> ]
4722
4723 This is used to unset a variable. See "http-after-response set-var" for
4724 details about <var-name>.
4725
4726 Example:
4727 http-after-response unset-var(sess.last_redir)
4728
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02004729
4730http-check comment <string>
4731 Defines a comment for the following the http-check rule, reported in logs if
4732 it fails.
4733 May be used in sections : defaults | frontend | listen | backend
4734 yes | no | yes | yes
4735
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02004736 Arguments :
4737 <string> is the comment message to add in logs if the following http-check
4738 rule fails.
4739
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02004740 It only works for connect, send and expect rules. It is useful to make
4741 user-friendly error reporting.
4742
Daniel Corbett67a82712020-07-06 23:01:19 -04004743 See also : "option httpchk", "http-check connect", "http-check send" and
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02004744 "http-check expect".
4745
4746
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02004747http-check connect [default] [port <expr>] [addr <ip>] [send-proxy]
4748 [via-socks4] [ssl] [sni <sni>] [alpn <alpn>] [linger]
Christopher Fauletedc6ed92020-04-23 16:27:59 +02004749 [proto <name>] [comment <msg>]
Christopher Faulete5870d82020-04-15 11:32:03 +02004750 Opens a new connection to perform an HTTP health check
4751 May be used in sections : defaults | frontend | listen | backend
4752 yes | no | yes | yes
4753
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02004754 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02004755 comment <msg> defines a message to report if the rule evaluation fails.
4756
Christopher Faulete5870d82020-04-15 11:32:03 +02004757 default Use default options of the server line to do the health
Daniel Corbett67a82712020-07-06 23:01:19 -04004758 checks. The server options are used only if not redefined.
Christopher Faulete5870d82020-04-15 11:32:03 +02004759
4760 port <expr> if not set, check port or server port is used.
4761 It tells HAProxy where to open the connection to.
4762 <port> must be a valid TCP port source integer, from 1 to
4763 65535 or an sample-fetch expression.
4764
4765 addr <ip> defines the IP address to do the health check.
4766
4767 send-proxy send a PROXY protocol string
4768
4769 via-socks4 enables outgoing health checks using upstream socks4 proxy.
4770
4771 ssl opens a ciphered connection
4772
4773 sni <sni> specifies the SNI to use to do health checks over SSL.
4774
4775 alpn <alpn> defines which protocols to advertise with ALPN. The protocol
4776 list consists in a comma-delimited list of protocol names,
4777 for instance: "h2,http/1.1". If it is not set, the server ALPN
4778 is used.
4779
Christopher Fauletedc6ed92020-04-23 16:27:59 +02004780 proto <name> forces the multiplexer's protocol to use for this connection.
4781 It must be an HTTP mux protocol and it must be usable on the
4782 backend side. The list of available protocols is reported in
4783 haproxy -vv.
4784
Christopher Faulete5870d82020-04-15 11:32:03 +02004785 linger cleanly close the connection instead of using a single RST.
4786
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02004787 Just like tcp-check health checks, it is possible to configure the connection
4788 to use to perform HTTP health check. This directive should also be used to
4789 describe a scenario involving several request/response exchanges, possibly on
4790 different ports or with different servers.
4791
4792 When there are no TCP port configured on the server line neither server port
4793 directive, then the first step of the http-check sequence must be to specify
4794 the port with a "http-check connect".
4795
4796 In an http-check ruleset a 'connect' is required, it is also mandatory to start
4797 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
4798 do.
4799
4800 When a connect must start the ruleset, if may still be preceded by set-var,
4801 unset-var or comment rules.
4802
4803 Examples :
Christopher Faulete5870d82020-04-15 11:32:03 +02004804 # check HTTP and HTTPs services on a server.
4805 # first open port 80 thanks to server line port directive, then
4806 # tcp-check opens port 443, ciphered and run a request on it:
4807 option httpchk
4808
4809 http-check connect
Christopher Fauleta5c14ef2020-04-29 14:19:13 +02004810 http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu
Christopher Faulet8021a5f2020-04-24 13:53:12 +02004811 http-check expect status 200-399
Christopher Faulete5870d82020-04-15 11:32:03 +02004812 http-check connect port 443 ssl sni haproxy.1wt.eu
Christopher Fauleta5c14ef2020-04-29 14:19:13 +02004813 http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu
Christopher Faulet8021a5f2020-04-24 13:53:12 +02004814 http-check expect status 200-399
Christopher Faulete5870d82020-04-15 11:32:03 +02004815
4816 server www 10.0.0.1 check port 80
4817
4818 See also : "option httpchk", "http-check send", "http-check expect"
Christopher Faulet6d0c3df2020-01-22 09:26:35 +01004819
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02004820
Willy Tarreau0ba27502007-12-24 16:55:16 +01004821http-check disable-on-404
4822 Enable a maintenance mode upon HTTP/404 response to health-checks
4823 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01004824 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01004825 Arguments : none
4826
4827 When this option is set, a server which returns an HTTP code 404 will be
4828 excluded from further load-balancing, but will still receive persistent
4829 connections. This provides a very convenient method for Web administrators
4830 to perform a graceful shutdown of their servers. It is also important to note
4831 that a server which is detected as failed while it was in this mode will not
4832 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
4833 will immediately be reinserted into the farm. The status on the stats page
4834 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01004835 option only works in conjunction with the "httpchk" option. If this option
4836 is used with "http-check expect", then it has precedence over it so that 404
4837 responses will still be considered as soft-stop.
4838
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02004839 See also : "option httpchk" and "http-check expect".
Willy Tarreaubd741542010-03-16 18:46:54 +01004840
4841
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02004842http-check expect [min-recv <int>] [comment <msg>]
Christopher Faulete5870d82020-04-15 11:32:03 +02004843 [ok-status <st>] [error-status <st>] [tout-status <st>]
4844 [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
4845 [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004846 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01004847 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02004848 yes | no | yes | yes
Christopher Faulete5870d82020-04-15 11:32:03 +02004849
Willy Tarreaubd741542010-03-16 18:46:54 +01004850 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02004851 comment <msg> defines a message to report if the rule evaluation fails.
4852
Christopher Faulete5870d82020-04-15 11:32:03 +02004853 min-recv is optional and can define the minimum amount of data required to
4854 evaluate the current expect rule. If the number of received bytes
4855 is under this limit, the check will wait for more data. This
4856 option can be used to resolve some ambiguous matching rules or to
4857 avoid executing costly regex matches on content known to be still
4858 incomplete. If an exact string is used, the minimum between the
4859 string length and this parameter is used. This parameter is
4860 ignored if it is set to -1. If the expect rule does not match,
4861 the check will wait for more data. If set to 0, the evaluation
4862 result is always conclusive.
4863
4864 ok-status <st> is optional and can be used to set the check status if
4865 the expect rule is successfully evaluated and if it is
4866 the last rule in the tcp-check ruleset. "L7OK", "L7OKC",
Christopher Fauletd888f0f2020-05-07 07:40:17 +02004867 "L6OK" and "L4OK" are supported :
4868 - L7OK : check passed on layer 7
4869 - L7OKC : check conditionally passed on layer 7, for
4870 example 404 with disable-on-404
4871 - L6OK : check passed on layer 6
4872 - L4OK : check passed on layer 4
4873 By default "L7OK" is used.
Christopher Faulete5870d82020-04-15 11:32:03 +02004874
4875 error-status <st> is optional and can be used to set the check status if
4876 an error occurred during the expect rule evaluation.
Christopher Fauletd888f0f2020-05-07 07:40:17 +02004877 "L7RSP", "L7STS", "L6RSP" and "L4CON" are supported :
4878 - L7RSP : layer 7 invalid response - protocol error
4879 - L7STS : layer 7 response error, for example HTTP 5xx
4880 - L6RSP : layer 6 invalid response - protocol error
4881 - L4CON : layer 1-4 connection problem
4882 By default "L7RSP" is used.
Christopher Faulete5870d82020-04-15 11:32:03 +02004883
4884 tout-status <st> is optional and can be used to set the check status if
4885 a timeout occurred during the expect rule evaluation.
Christopher Fauletd888f0f2020-05-07 07:40:17 +02004886 "L7TOUT", "L6TOUT", and "L4TOUT" are supported :
4887 - L7TOUT : layer 7 (HTTP/SMTP) timeout
4888 - L6TOUT : layer 6 (SSL) timeout
4889 - L4TOUT : layer 1-4 timeout
Christopher Faulete5870d82020-04-15 11:32:03 +02004890 By default "L7TOUT" is used.
4891
4892 on-success <fmt> is optional and can be used to customize the
4893 informational message reported in logs if the expect
4894 rule is successfully evaluated and if it is the last rule
4895 in the tcp-check ruleset. <fmt> is a log-format string.
4896
4897 on-error <fmt> is optional and can be used to customize the
4898 informational message reported in logs if an error
4899 occurred during the expect rule evaluation. <fmt> is a
4900 log-format string.
4901
Willy Tarreaubd741542010-03-16 18:46:54 +01004902 <match> is a keyword indicating how to look for a specific pattern in the
Christopher Fauletb5594262020-05-05 20:23:13 +02004903 response. The keyword may be one of "status", "rstatus", "hdr",
4904 "fhdr", "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01004905 exclamation mark ("!") to negate the match. Spaces are allowed
4906 between the exclamation mark and the keyword. See below for more
4907 details on the supported keywords.
4908
Christopher Faulet39708192020-05-05 10:47:36 +02004909 <pattern> is the pattern to look for. It may be a string, a regular
4910 expression or a more complex pattern with several arguments. If
4911 the string pattern contains spaces, they must be escaped with the
4912 usual backslash ('\').
Willy Tarreaubd741542010-03-16 18:46:54 +01004913
4914 By default, "option httpchk" considers that response statuses 2xx and 3xx
4915 are valid, and that others are invalid. When "http-check expect" is used,
4916 it defines what is considered valid or invalid. Only one "http-check"
4917 statement is supported in a backend. If a server fails to respond or times
4918 out, the check obviously fails. The available matches are :
4919
Christopher Faulet8021a5f2020-04-24 13:53:12 +02004920 status <codes> : test the status codes found parsing <codes> string. it
4921 must be a comma-separated list of status codes or range
4922 codes. A health check response will be considered as
4923 valid if the response's status code matches any status
4924 code or is inside any range of the list. If the "status"
4925 keyword is prefixed with "!", then the response will be
4926 considered invalid if the status code matches.
Willy Tarreaubd741542010-03-16 18:46:54 +01004927
4928 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004929 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004930 response's status code matches the expression. If the
4931 "rstatus" keyword is prefixed with "!", then the response
4932 will be considered invalid if the status code matches.
4933 This is mostly used to check for multiple codes.
4934
Christopher Fauletb5594262020-05-05 20:23:13 +02004935 hdr { name | name-lf } [ -m <meth> ] <name>
4936 [ { value | value-lf } [ -m <meth> ] <value> :
Christopher Faulet39708192020-05-05 10:47:36 +02004937 test the specified header pattern on the HTTP response
4938 headers. The name pattern is mandatory but the value
4939 pattern is optional. If not specified, only the header
4940 presence is verified. <meth> is the matching method,
4941 applied on the header name or the header value. Supported
4942 matching methods are "str" (exact match), "beg" (prefix
4943 match), "end" (suffix match), "sub" (substring match) or
4944 "reg" (regex match). If not specified, exact matching
Christopher Fauletb5594262020-05-05 20:23:13 +02004945 method is used. If the "name-lf" parameter is used,
4946 <name> is evaluated as a log-format string. If "value-lf"
4947 parameter is used, <value> is evaluated as a log-format
4948 string. These parameters cannot be used with the regex
4949 matching method. Finally, the header value is considered
4950 as comma-separated list. Note that matchings are case
4951 insensitive on the header names.
4952
4953 fhdr { name | name-lf } [ -m <meth> ] <name>
4954 [ { value | value-lf } [ -m <meth> ] <value> :
4955 test the specified full header pattern on the HTTP
4956 response headers. It does exactly the same than "hdr"
4957 keyword, except the full header value is tested, commas
4958 are not considered as delimiters.
Christopher Faulet39708192020-05-05 10:47:36 +02004959
Willy Tarreaubd741542010-03-16 18:46:54 +01004960 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004961 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004962 response's body contains this exact string. If the
4963 "string" keyword is prefixed with "!", then the response
4964 will be considered invalid if the body contains this
4965 string. This can be used to look for a mandatory word at
4966 the end of a dynamic page, or to detect a failure when a
Davor Ocelice9ed2812017-12-25 17:49:28 +01004967 specific error appears on the check page (e.g. a stack
Willy Tarreaubd741542010-03-16 18:46:54 +01004968 trace).
4969
4970 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004971 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004972 response's body matches this expression. If the "rstring"
4973 keyword is prefixed with "!", then the response will be
4974 considered invalid if the body matches the expression.
4975 This can be used to look for a mandatory word at the end
4976 of a dynamic page, or to detect a failure when a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01004977 error appears on the check page (e.g. a stack trace).
Willy Tarreaubd741542010-03-16 18:46:54 +01004978
Christopher Fauletaaab0832020-05-05 15:54:22 +02004979 string-lf <fmt> : test a log-format string match in the HTTP response body.
4980 A health check response will be considered valid if the
4981 response's body contains the string resulting of the
4982 evaluation of <fmt>, which follows the log-format rules.
4983 If prefixed with "!", then the response will be
4984 considered invalid if the body contains the string.
4985
Willy Tarreaubd741542010-03-16 18:46:54 +01004986 It is important to note that the responses will be limited to a certain size
4987 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
4988 Thus, too large responses may not contain the mandatory pattern when using
4989 "string" or "rstring". If a large response is absolutely required, it is
4990 possible to change the default max size by setting the global variable.
4991 However, it is worth keeping in mind that parsing very large responses can
4992 waste some CPU cycles, especially when regular expressions are used, and that
4993 it is always better to focus the checks on smaller resources.
4994
Christopher Faulete5870d82020-04-15 11:32:03 +02004995 In an http-check ruleset, the last expect rule may be implicit. If no expect
4996 rule is specified after the last "http-check send", an implicit expect rule
4997 is defined to match on 2xx or 3xx status codes. It means this rule is also
4998 defined if there is no "http-check" rule at all, when only "option httpchk"
4999 is set.
Cyril Bonté32602d22015-01-30 00:07:07 +01005000
Willy Tarreaubd741542010-03-16 18:46:54 +01005001 Last, if "http-check expect" is combined with "http-check disable-on-404",
5002 then this last one has precedence when the server responds with 404.
5003
5004 Examples :
5005 # only accept status 200 as valid
Christopher Faulet8021a5f2020-04-24 13:53:12 +02005006 http-check expect status 200,201,300-310
Willy Tarreaubd741542010-03-16 18:46:54 +01005007
Christopher Faulet39708192020-05-05 10:47:36 +02005008 # be sure a sessid coookie is set
5009 http-check expect header name "set-cookie" value -m beg "sessid="
5010
Willy Tarreaubd741542010-03-16 18:46:54 +01005011 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01005012 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01005013
5014 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01005015 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01005016
5017 # check that we have a correct hexadecimal tag before /html
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03005018 http-check expect rstring <!--tag:[0-9a-f]*--></html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01005019
Christopher Faulete5870d82020-04-15 11:32:03 +02005020 See also : "option httpchk", "http-check connect", "http-check disable-on-404"
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005021 and "http-check send".
Willy Tarreau2769aa02007-12-27 18:26:09 +01005022
5023
Christopher Faulet7c95f5f2020-05-06 15:06:34 +02005024http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
Christopher Faulet574e7bd2020-05-06 15:38:58 +02005025 [hdr <name> <fmt>]* [{ body <string> | body-lf <fmt> }]
5026 [comment <msg>]
Christopher Faulet8acb1282020-04-09 08:44:06 +02005027 Add a possible list of headers and/or a body to the request sent during HTTP
5028 health checks.
5029 May be used in sections : defaults | frontend | listen | backend
5030 yes | no | yes | yes
5031 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +02005032 comment <msg> defines a message to report if the rule evaluation fails.
5033
Christopher Faulete5870d82020-04-15 11:32:03 +02005034 meth <method> is the optional HTTP method used with the requests. When not
5035 set, the "OPTIONS" method is used, as it generally requires
5036 low server processing and is easy to filter out from the
5037 logs. Any method may be used, though it is not recommended
5038 to invent non-standard ones.
5039
Christopher Faulet7c95f5f2020-05-06 15:06:34 +02005040 uri <uri> is optional and set the URI referenced in the HTTP requests
5041 to the string <uri>. It defaults to "/" which is accessible
5042 by default on almost any server, but may be changed to any
5043 other URI. Query strings are permitted.
5044
5045 uri-lf <fmt> is optional and set the URI referenced in the HTTP requests
5046 using the log-format string <fmt>. It defaults to "/" which
5047 is accessible by default on almost any server, but may be
5048 changed to any other URI. Query strings are permitted.
Christopher Faulet8acb1282020-04-09 08:44:06 +02005049
Christopher Faulet907701b2020-04-28 09:37:00 +02005050 ver <version> is the optional HTTP version string. It defaults to
Christopher Faulete5870d82020-04-15 11:32:03 +02005051 "HTTP/1.0" but some servers might behave incorrectly in HTTP
Daniel Corbett67a82712020-07-06 23:01:19 -04005052 1.0, so turning it to HTTP/1.1 may sometimes help. Note that
Christopher Faulete5870d82020-04-15 11:32:03 +02005053 the Host field is mandatory in HTTP/1.1, use "hdr" argument
5054 to add it.
5055
5056 hdr <name> <fmt> adds the HTTP header field whose name is specified in
5057 <name> and whose value is defined by <fmt>, which follows
5058 to the log-format rules.
5059
5060 body <string> add the body defined by <string> to the request sent during
5061 HTTP health checks. If defined, the "Content-Length" header
5062 is thus automatically added to the request.
Christopher Faulet8acb1282020-04-09 08:44:06 +02005063
Christopher Faulet574e7bd2020-05-06 15:38:58 +02005064 body-lf <fmt> add the body defined by the log-format string <fmt> to the
5065 request sent during HTTP health checks. If defined, the
5066 "Content-Length" header is thus automatically added to the
5067 request.
5068
Christopher Faulet8acb1282020-04-09 08:44:06 +02005069 In addition to the request line defined by the "option httpchk" directive,
5070 this one is the valid way to add some headers and optionally a body to the
5071 request sent during HTTP health checks. If a body is defined, the associate
Christopher Faulet9df910c2020-04-29 14:20:47 +02005072 "Content-Length" header is automatically added. Thus, this header or
5073 "Transfer-encoding" header should not be present in the request provided by
5074 "http-check send". If so, it will be ignored. The old trick consisting to add
5075 headers after the version string on the "option httpchk" line is now
Christopher Faulet8acb1282020-04-09 08:44:06 +02005076 deprecated. Note also the "Connection: close" header is still added if a
Daniel Corbett67a82712020-07-06 23:01:19 -04005077 "http-check expect" directive is defined independently of this directive, just
Christopher Faulet8acb1282020-04-09 08:44:06 +02005078 like the state header if the directive "http-check send-state" is defined.
5079
Christopher Faulete5870d82020-04-15 11:32:03 +02005080 Also "http-check send" doesn't support HTTP keep-alive. Keep in mind that it
5081 will automatically append a "Connection: close" header, meaning that this
Christopher Faulet9df910c2020-04-29 14:20:47 +02005082 header should not be present in the request provided by "http-check send". If
5083 so, it will be ignored.
5084
5085 Note that the Host header and the request authority, when both defined, are
5086 automatically synchronized. It means when the HTTP request is sent, when a
5087 Host is inserted in the request, the request authority is accordingly
5088 updated. Thus, don't be surprised if the Host header value overwrites the
5089 configured request authority.
5090
5091 Note also for now, no Host header is automatically added in HTTP/1.1 or above
5092 requests. You should add it explicitly.
Christopher Faulete5870d82020-04-15 11:32:03 +02005093
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005094 See also : "option httpchk", "http-check send-state" and "http-check expect".
Christopher Faulet8acb1282020-04-09 08:44:06 +02005095
5096
Willy Tarreauef781042010-01-27 11:53:01 +01005097http-check send-state
5098 Enable emission of a state header with HTTP health checks
5099 May be used in sections : defaults | frontend | listen | backend
5100 yes | no | yes | yes
5101 Arguments : none
5102
5103 When this option is set, haproxy will systematically send a special header
5104 "X-Haproxy-Server-State" with a list of parameters indicating to each server
5105 how they are seen by haproxy. This can be used for instance when a server is
5106 manipulated without access to haproxy and the operator needs to know whether
5107 haproxy still sees it up or not, or if the server is the last one in a farm.
5108
5109 The header is composed of fields delimited by semi-colons, the first of which
5110 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
5111 checks on the total number before transition, just as appears in the stats
5112 interface. Next headers are in the form "<variable>=<value>", indicating in
5113 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08005114 - a variable "address", containing the address of the backend server.
5115 This corresponds to the <address> field in the server declaration. For
5116 unix domain sockets, it will read "unix".
5117
5118 - a variable "port", containing the port of the backend server. This
5119 corresponds to the <port> field in the server declaration. For unix
5120 domain sockets, it will read "unix".
5121
Willy Tarreauef781042010-01-27 11:53:01 +01005122 - a variable "name", containing the name of the backend followed by a slash
5123 ("/") then the name of the server. This can be used when a server is
5124 checked in multiple backends.
5125
5126 - a variable "node" containing the name of the haproxy node, as set in the
5127 global "node" variable, otherwise the system's hostname if unspecified.
5128
5129 - a variable "weight" indicating the weight of the server, a slash ("/")
5130 and the total weight of the farm (just counting usable servers). This
5131 helps to know if other servers are available to handle the load when this
5132 one fails.
5133
5134 - a variable "scur" indicating the current number of concurrent connections
5135 on the server, followed by a slash ("/") then the total number of
5136 connections on all servers of the same backend.
5137
5138 - a variable "qcur" indicating the current number of requests in the
5139 server's queue.
5140
5141 Example of a header received by the application server :
5142 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
5143 scur=13/22; qcur=0
5144
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005145 See also : "option httpchk", "http-check disable-on-404" and
5146 "http-check send".
Willy Tarreauef781042010-01-27 11:53:01 +01005147
Christopher Faulete5870d82020-04-15 11:32:03 +02005148
5149http-check set-var(<var-name>) <expr>
Christopher Faulete5870d82020-04-15 11:32:03 +02005150 This operation sets the content of a variable. The variable is declared inline.
Christopher Faulete5870d82020-04-15 11:32:03 +02005151 May be used in sections: defaults | frontend | listen | backend
5152 yes | no | yes | yes
5153
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005154 Arguments :
Christopher Faulete5870d82020-04-15 11:32:03 +02005155 <var-name> The name of the variable starts with an indication about its
5156 scope. The scopes allowed for http-check are:
5157 "proc" : the variable is shared with the whole process.
5158 "sess" : the variable is shared with the tcp-check session.
5159 "check": the variable is declared for the lifetime of the tcp-check.
5160 This prefix is followed by a name. The separator is a '.'.
5161 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
5162 and '-'.
5163
5164 <expr> Is a sample-fetch expression potentially followed by converters.
5165
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005166 Examples :
5167 http-check set-var(check.port) int(1234)
Christopher Faulete5870d82020-04-15 11:32:03 +02005168
5169
5170http-check unset-var(<var-name>)
Christopher Faulete5870d82020-04-15 11:32:03 +02005171 Free a reference to a variable within its scope.
Christopher Faulete5870d82020-04-15 11:32:03 +02005172 May be used in sections: defaults | frontend | listen | backend
5173 yes | no | yes | yes
5174
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005175 Arguments :
Christopher Faulete5870d82020-04-15 11:32:03 +02005176 <var-name> The name of the variable starts with an indication about its
5177 scope. The scopes allowed for http-check are:
5178 "proc" : the variable is shared with the whole process.
5179 "sess" : the variable is shared with the tcp-check session.
5180 "check": the variable is declared for the lifetime of the tcp-check.
5181 This prefix is followed by a name. The separator is a '.'.
5182 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
5183 and '-'.
5184
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02005185 Examples :
5186 http-check unset-var(check.port)
Christopher Faulete5870d82020-04-15 11:32:03 +02005187
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005188
Christopher Faulet3b967c12020-05-15 15:47:44 +02005189http-error status <code> [content-type <type>]
5190 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
5191 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
5192 [ hdr <name> <fmt> ]*
5193 Defines a custom error message to use instead of errors generated by HAProxy.
5194 May be used in sections : defaults | frontend | listen | backend
5195 yes | yes | yes | yes
5196 Arguments :
Ilya Shipitsin11057a32020-06-21 21:18:27 +05005197 status <code> is the HTTP status code. It must be specified.
Christopher Faulet3b967c12020-05-15 15:47:44 +02005198 Currently, HAProxy is capable of generating codes
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02005199 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 425,
5200 429, 500, 502, 503, and 504.
Christopher Faulet3b967c12020-05-15 15:47:44 +02005201
5202 content-type <type> is the response content type, for instance
5203 "text/plain". This parameter is ignored and should be
5204 omitted when an errorfile is configured or when the
5205 payload is empty. Otherwise, it must be defined.
5206
5207 default-errorfiles Reset the previously defined error message for current
5208 proxy for the status <code>. If used on a backend, the
5209 frontend error message is used, if defined. If used on
5210 a frontend, the default error message is used.
5211
5212 errorfile <file> designates a file containing the full HTTP response.
5213 It is recommended to follow the common practice of
5214 appending ".http" to the filename so that people do
5215 not confuse the response with HTML error pages, and to
5216 use absolute paths, since files are read before any
5217 chroot is performed.
5218
5219 errorfiles <name> designates the http-errors section to use to import
5220 the error message with the status code <code>. If no
5221 such message is found, the proxy's error messages are
5222 considered.
5223
5224 file <file> specifies the file to use as response payload. If the
5225 file is not empty, its content-type must be set as
5226 argument to "content-type", otherwise, any
5227 "content-type" argument is ignored. <file> is
5228 considered as a raw string.
5229
5230 string <str> specifies the raw string to use as response payload.
5231 The content-type must always be set as argument to
5232 "content-type".
5233
5234 lf-file <file> specifies the file to use as response payload. If the
5235 file is not empty, its content-type must be set as
5236 argument to "content-type", otherwise, any
5237 "content-type" argument is ignored. <file> is
5238 evaluated as a log-format string.
5239
5240 lf-string <str> specifies the log-format string to use as response
5241 payload. The content-type must always be set as
5242 argument to "content-type".
5243
5244 hdr <name> <fmt> adds to the response the HTTP header field whose name
5245 is specified in <name> and whose value is defined by
5246 <fmt>, which follows to the log-format rules.
5247 This parameter is ignored if an errorfile is used.
5248
5249 This directive may be used instead of "errorfile", to define a custom error
5250 message. As "errorfile" directive, it is used for errors detected and
5251 returned by HAProxy. If an errorfile is defined, it is parsed when HAProxy
5252 starts and must be valid according to the HTTP standards. The generated
5253 response must not exceed the configured buffer size (BUFFSIZE), otherwise an
5254 internal error will be returned. Finally, if you consider to use some
5255 http-after-response rules to rewrite these errors, the reserved buffer space
5256 should be available (see "tune.maxrewrite").
5257
5258 The files are read at the same time as the configuration and kept in memory.
5259 For this reason, the errors continue to be returned even when the process is
5260 chrooted, and no file change is considered while the process is running.
5261
5262 See also : "errorfile", "errorfiles", "errorloc", "errorloc302",
5263 "errorloc303" and section 3.8 about http-errors.
5264
5265
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005266http-request <action> [options...] [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005267 Access control for Layer 7 requests
5268
5269 May be used in sections: defaults | frontend | listen | backend
5270 no | yes | yes | yes
5271
Willy Tarreau20b0de52012-12-24 15:45:22 +01005272 The http-request statement defines a set of rules which apply to layer 7
5273 processing. The rules are evaluated in their declaration order when they are
5274 met in a frontend, listen or backend section. Any rule may optionally be
5275 followed by an ACL-based condition, in which case it will only be evaluated
5276 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005277
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005278 The first keyword is the rule's action. The supported actions are described
5279 below.
Willy Tarreau20b0de52012-12-24 15:45:22 +01005280
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005281 There is no limit to the number of http-request statements per instance.
Willy Tarreau20b0de52012-12-24 15:45:22 +01005282
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005283 Example:
5284 acl nagios src 192.168.129.3
5285 acl local_net src 192.168.0.0/16
5286 acl auth_ok http_auth(L1)
Willy Tarreau20b0de52012-12-24 15:45:22 +01005287
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005288 http-request allow if nagios
5289 http-request allow if local_net auth_ok
5290 http-request auth realm Gimme if local_net auth_ok
5291 http-request deny
Willy Tarreau81499eb2012-12-27 12:19:02 +01005292
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005293 Example:
5294 acl key req.hdr(X-Add-Acl-Key) -m found
5295 acl add path /addacl
5296 acl del path /delacl
Willy Tarreau20b0de52012-12-24 15:45:22 +01005297
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005298 acl myhost hdr(Host) -f myhost.lst
Willy Tarreau20b0de52012-12-24 15:45:22 +01005299
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005300 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
5301 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02005302
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005303 Example:
5304 acl value req.hdr(X-Value) -m found
5305 acl setmap path /setmap
5306 acl delmap path /delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06005307
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005308 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06005309
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005310 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
5311 http-request del-map(map.lst) %[src] if delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06005312
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005313 See also : "stats http-request", section 3.4 about userlists and section 7
5314 about ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06005315
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005316http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005317
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005318 This is used to add a new entry into an ACL. The ACL must be loaded from a
5319 file (even a dummy empty file). The file name of the ACL to be updated is
5320 passed between parentheses. It takes one argument: <key fmt>, which follows
5321 log-format rules, to collect content of the new entry. It performs a lookup
5322 in the ACL before insertion, to avoid duplicated (or more) values. This
5323 lookup is done by a linear search and can be expensive with large lists!
5324 It is the equivalent of the "add acl" command from the stats socket, but can
5325 be triggered by an HTTP request.
Sasha Pachev218f0642014-06-16 12:05:59 -06005326
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005327http-request add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005328
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005329 This appends an HTTP header field whose name is specified in <name> and
5330 whose value is defined by <fmt> which follows the log-format rules (see
5331 Custom Log Format in section 8.2.4). This is particularly useful to pass
5332 connection-specific information to the server (e.g. the client's SSL
5333 certificate), or to combine several headers into one. This rule is not
5334 final, so it is possible to add other similar rules. Note that header
5335 addition is performed immediately, so one rule might reuse the resulting
5336 header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06005337
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005338http-request allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005339
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005340 This stops the evaluation of the rules and lets the request pass the check.
5341 No further "http-request" rules are evaluated.
Sasha Pachev218f0642014-06-16 12:05:59 -06005342
Sasha Pachev218f0642014-06-16 12:05:59 -06005343
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005344http-request auth [realm <realm>] [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005345
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005346 This stops the evaluation of the rules and immediately responds with an
5347 HTTP 401 or 407 error code to invite the user to present a valid user name
5348 and password. No further "http-request" rules are evaluated. An optional
5349 "realm" parameter is supported, it sets the authentication realm that is
5350 returned with the response (typically the application's name).
Sasha Pachev218f0642014-06-16 12:05:59 -06005351
Christopher Faulet612f2ea2020-05-27 09:57:28 +02005352 The corresponding proxy's error message is used. It may be customized using
5353 an "errorfile" or an "http-error" directive. For 401 responses, all
5354 occurrences of the WWW-Authenticate header are removed and replaced by a new
5355 one with a basic authentication challenge for realm "<realm>". For 407
5356 responses, the same is done on the Proxy-Authenticate header. If the error
5357 message must not be altered, consider to use "http-request return" rule
5358 instead.
5359
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005360 Example:
5361 acl auth_ok http_auth_group(L1) G1
5362 http-request auth unless auth_ok
Sasha Pachev218f0642014-06-16 12:05:59 -06005363
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02005364http-request cache-use <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005365
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02005366 See section 6.2 about cache setup.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01005367
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005368http-request capture <sample> [ len <length> | id <id> ]
5369 [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01005370
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005371 This captures sample expression <sample> from the request buffer, and
5372 converts it to a string of at most <len> characters. The resulting string is
5373 stored into the next request "capture" slot, so it will possibly appear next
5374 to some captured HTTP headers. It will then automatically appear in the logs,
5375 and it will be possible to extract it using sample fetch rules to feed it
5376 into headers or anything. The length should be limited given that this size
5377 will be allocated for each capture during the whole session life.
5378 Please check section 7.3 (Fetching samples) and "capture request header" for
5379 more information.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01005380
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005381 If the keyword "id" is used instead of "len", the action tries to store the
5382 captured string in a previously declared capture slot. This is useful to run
5383 captures in backends. The slot id can be declared by a previous directive
Baptiste Assmann19a69b32020-01-16 14:34:22 +01005384 "http-request capture" or with the "declare capture" keyword.
5385
5386 When using this action in a backend, double check that the relevant
5387 frontend(s) have the required capture slots otherwise, this rule will be
5388 ignored at run time. This can't be detected at configuration parsing time
5389 due to HAProxy's ability to dynamically resolve backend name at runtime.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01005390
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005391http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01005392
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005393 This is used to delete an entry from an ACL. The ACL must be loaded from a
5394 file (even a dummy empty file). The file name of the ACL to be updated is
5395 passed between parentheses. It takes one argument: <key fmt>, which follows
5396 log-format rules, to collect content of the entry to delete.
5397 It is the equivalent of the "del acl" command from the stats socket, but can
5398 be triggered by an HTTP request.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01005399
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005400http-request del-header <name> [ { if | unless } <condition> ]
Willy Tarreauf4c43c12013-06-11 17:01:13 +02005401
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005402 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau9a355ec2013-06-11 17:45:46 +02005403
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005404http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau42cf39e2013-06-11 18:51:32 +02005405
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005406 This is used to delete an entry from a MAP. The MAP must be loaded from a
5407 file (even a dummy empty file). The file name of the MAP to be updated is
5408 passed between parentheses. It takes one argument: <key fmt>, which follows
5409 log-format rules, to collect content of the entry to delete.
5410 It takes one argument: "file name" It is the equivalent of the "del map"
5411 command from the stats socket, but can be triggered by an HTTP request.
Willy Tarreau51347ed2013-06-11 19:34:13 +02005412
Christopher Faulet5cb513a2020-05-13 17:56:56 +02005413http-request deny [deny_status <status>] [ { if | unless } <condition> ]
5414http-request deny [ { status | deny_status } <code>] [content-type <type>]
5415 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
5416 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
5417 [ hdr <name> <fmt> ]*
5418 [ { if | unless } <condition> ]
Patrick Hemmer268a7072018-05-11 12:52:31 -04005419
Christopher Faulet5cb513a2020-05-13 17:56:56 +02005420 This stops the evaluation of the rules and immediately rejects the request.
5421 By default an HTTP 403 error is returned. But the response may be customized
5422 using same syntax than "http-request return" rules. Thus, see "http-request
Ilya Shipitsin11057a32020-06-21 21:18:27 +05005423 return" for details. For compatibility purpose, when no argument is defined,
Christopher Faulet5cb513a2020-05-13 17:56:56 +02005424 or only "deny_status", the argument "default-errorfiles" is implied. It means
5425 "http-request deny [deny_status <status>]" is an alias of
5426 "http-request deny [status <status>] default-errorfiles".
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005427 No further "http-request" rules are evaluated.
Christopher Faulet5cb513a2020-05-13 17:56:56 +02005428 See also "http-request return".
Patrick Hemmer268a7072018-05-11 12:52:31 -04005429
Olivier Houchard602bf7d2019-05-10 13:59:15 +02005430http-request disable-l7-retry [ { if | unless } <condition> ]
5431 This disables any attempt to retry the request if it fails for any other
5432 reason than a connection failure. This can be useful for example to make
5433 sure POST requests aren't retried on failure.
5434
Baptiste Assmann333939c2019-01-21 08:34:50 +01005435http-request do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr> :
5436
5437 This action performs a DNS resolution of the output of <expr> and stores
5438 the result in the variable <var>. It uses the DNS resolvers section
5439 pointed by <resolvers>.
5440 It is possible to choose a resolution preference using the optional
5441 arguments 'ipv4' or 'ipv6'.
5442 When performing the DNS resolution, the client side connection is on
5443 pause waiting till the end of the resolution.
5444 If an IP address can be found, it is stored into <var>. If any kind of
5445 error occurs, then <var> is not set.
5446 One can use this action to discover a server IP address at run time and
5447 based on information found in the request (IE a Host header).
5448 If this action is used to find the server's IP address (using the
5449 "set-dst" action), then the server IP address in the backend must be set
5450 to 0.0.0.0.
5451
5452 Example:
5453 resolvers mydns
5454 nameserver local 127.0.0.53:53
5455 nameserver google 8.8.8.8:53
5456 timeout retry 1s
5457 hold valid 10s
5458 hold nx 3s
5459 hold other 3s
5460 hold obsolete 0s
5461 accepted_payload_size 8192
5462
5463 frontend fe
5464 bind 10.42.0.1:80
5465 http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),lower
5466 http-request capture var(txn.myip) len 40
5467
5468 # return 503 when the variable is not set,
5469 # which mean DNS resolution error
5470 use_backend b_503 unless { var(txn.myip) -m found }
5471
5472 default_backend be
5473
5474 backend b_503
5475 # dummy backend used to return 503.
5476 # one can use the errorfile directive to send a nice
5477 # 503 error page to end users
5478
5479 backend be
5480 # rule to prevent HAProxy from reconnecting to services
5481 # on the local network (forged DNS name used to scan the network)
5482 http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 }
5483 http-request set-dst var(txn.myip)
5484 server clear 0.0.0.0:0
5485
5486 NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't
5487 be used to scan the network or worst won't loop over itself...
5488
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01005489http-request early-hint <name> <fmt> [ { if | unless } <condition> ]
5490
5491 This is used to build an HTTP 103 Early Hints response prior to any other one.
5492 This appends an HTTP header field to this response whose name is specified in
5493 <name> and whose value is defined by <fmt> which follows the log-format rules
5494 (see Custom Log Format in section 8.2.4). This is particularly useful to pass
Frédéric Lécaille3aac1062018-11-13 09:42:13 +01005495 to the client some Link headers to preload resources required to render the
5496 HTML documents.
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01005497
5498 See RFC 8297 for more information.
5499
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005500http-request redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005501
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005502 This performs an HTTP redirection based on a redirect rule. This is exactly
5503 the same as the "redirect" statement except that it inserts a redirect rule
5504 which can be processed in the middle of other "http-request" rules and that
5505 these rules use the "log-format" strings. See the "redirect" keyword for the
5506 rule's syntax.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005507
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005508http-request reject [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005509
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005510 This stops the evaluation of the rules and immediately closes the connection
5511 without sending any response. It acts similarly to the
5512 "tcp-request content reject" rules. It can be useful to force an immediate
5513 connection closure on HTTP/2 connections.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005514
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005515http-request replace-header <name> <match-regex> <replace-fmt>
5516 [ { if | unless } <condition> ]
Willy Tarreaua9083d02015-05-08 15:27:59 +02005517
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05005518 This matches the value of all occurrences of header field <name> against
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005519 <match-regex>. Matching is performed case-sensitively. Matching values are
5520 completely replaced by <replace-fmt>. Format characters are allowed in
5521 <replace-fmt> and work like <fmt> arguments in "http-request add-header".
5522 Standard back-references using the backslash ('\') followed by a number are
5523 supported.
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02005524
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005525 This action acts on whole header lines, regardless of the number of values
5526 they may contain. Thus it is well-suited to process headers naturally
5527 containing commas in their value, such as If-Modified-Since. Headers that
5528 contain a comma-separated list of values, such as Accept, should be processed
5529 using "http-request replace-value".
William Lallemand86d0df02017-11-24 21:36:45 +01005530
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005531 Example:
5532 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
5533
5534 # applied to:
5535 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
5536
5537 # outputs:
5538 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
5539
5540 # assuming the backend IP is 192.168.1.20
Willy Tarreau09448f72014-06-25 18:12:15 +02005541
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005542 http-request replace-header User-Agent curl foo
5543
5544 # applied to:
5545 User-Agent: curl/7.47.0
Willy Tarreau09448f72014-06-25 18:12:15 +02005546
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005547 # outputs:
5548 User-Agent: foo
Willy Tarreau09448f72014-06-25 18:12:15 +02005549
Willy Tarreau262c3f12019-12-17 06:52:51 +01005550http-request replace-path <match-regex> <replace-fmt>
5551 [ { if | unless } <condition> ]
5552
5553 This works like "replace-header" except that it works on the request's path
5554 component instead of a header. The path component starts at the first '/'
Christopher Faulet82c83322020-09-02 14:16:59 +02005555 after an optional scheme+authority and ends before the question mark. Thus,
5556 the replacement does not modify the scheme, the authority and the
5557 query-string.
Willy Tarreau262c3f12019-12-17 06:52:51 +01005558
5559 It is worth noting that regular expressions may be more expensive to evaluate
5560 than certain ACLs, so rare replacements may benefit from a condition to avoid
5561 performing the evaluation at all if it does not match.
5562
5563 Example:
5564 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
5565 http-request replace-path (.*) /foo\1
5566
Willy Tarreau262c3f12019-12-17 06:52:51 +01005567 # strip /foo : turn /foo/bar?q=1 into /bar?q=1
5568 http-request replace-path /foo/(.*) /\1
5569 # or more efficient if only some requests match :
5570 http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ }
5571
Christopher Faulet312294f2020-09-02 17:17:44 +02005572http-request replace-pathq <match-regex> <replace-fmt>
5573 [ { if | unless } <condition> ]
5574
5575 This does the same as "http-request replace-path" except that the path
5576 contains the query-string if any is present. Thus, the path and the
5577 query-string are replaced.
5578
5579 Example:
5580 # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 :
5581 http-request replace-pathq ([^?]*)(\?(.*))? \1/foo\2
5582
Willy Tarreau33810222019-06-12 17:44:02 +02005583http-request replace-uri <match-regex> <replace-fmt>
5584 [ { if | unless } <condition> ]
5585
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005586 This works like "replace-header" except that it works on the request's URI part
5587 instead of a header. The URI part may contain an optional scheme, authority or
5588 query string. These are considered to be part of the value that is matched
5589 against.
5590
5591 It is worth noting that regular expressions may be more expensive to evaluate
5592 than certain ACLs, so rare replacements may benefit from a condition to avoid
5593 performing the evaluation at all if it does not match.
Willy Tarreau33810222019-06-12 17:44:02 +02005594
Willy Tarreau62b59132019-12-17 06:51:20 +01005595 IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent
5596 by browsers use the "origin form", which differs from the "absolute form" in
5597 that they do not contain a scheme nor authority in the URI portion. Mostly
5598 only requests sent to proxies, those forged by hand and some emitted by
5599 certain applications use the absolute form. As such, "replace-uri" usually
5600 works fine most of the time in HTTP/1.x with rules starting with a "/". But
5601 with HTTP/2, clients are encouraged to send absolute URIs only, which look
5602 like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri
5603 rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need
Willy Tarreau262c3f12019-12-17 06:52:51 +01005604 to be adapted to optionally match a scheme and authority, or replace-path
5605 should be used.
Willy Tarreau33810222019-06-12 17:44:02 +02005606
Willy Tarreau62b59132019-12-17 06:51:20 +01005607 Example:
5608 # rewrite all "http" absolute requests to "https":
5609 http-request replace-uri ^http://(.*) https://\1
Willy Tarreau33810222019-06-12 17:44:02 +02005610
Willy Tarreau62b59132019-12-17 06:51:20 +01005611 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
5612 http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2
Willy Tarreau33810222019-06-12 17:44:02 +02005613
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005614http-request replace-value <name> <match-regex> <replace-fmt>
5615 [ { if | unless } <condition> ]
Willy Tarreau09448f72014-06-25 18:12:15 +02005616
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005617 This works like "replace-header" except that it matches the regex against
5618 every comma-delimited value of the header field <name> instead of the
5619 entire header. This is suited for all headers which are allowed to carry
5620 more than one value. An example could be the Accept header.
Willy Tarreau09448f72014-06-25 18:12:15 +02005621
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005622 Example:
5623 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
Thierry FOURNIER236657b2015-08-19 08:25:14 +02005624
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005625 # applied to:
5626 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02005627
Tim Duesterhus2252beb2019-10-29 00:05:13 +01005628 # outputs:
5629 X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
Frédéric Lécaille6778b272018-01-29 15:22:53 +01005630
Christopher Faulet24231ab2020-01-24 17:44:23 +01005631http-request return [status <code>] [content-type <type>]
5632 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
5633 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
Christopher Faulet4a2c1422020-01-31 17:36:01 +01005634 [ hdr <name> <fmt> ]*
Christopher Faulet24231ab2020-01-24 17:44:23 +01005635 [ { if | unless } <condition> ]
5636
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05005637 This stops the evaluation of the rules and immediately returns a response. The
Christopher Faulet24231ab2020-01-24 17:44:23 +01005638 default status code used for the response is 200. It can be optionally
5639 specified as an arguments to "status". The response content-type may also be
Daniel Corbett67a82712020-07-06 23:01:19 -04005640 specified as an argument to "content-type". Finally the response itself may
Christopher Faulet24231ab2020-01-24 17:44:23 +01005641 be defined. If can be a full HTTP response specifying the errorfile to use,
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05005642 or the response payload specifying the file or the string to use. These rules
Christopher Faulet24231ab2020-01-24 17:44:23 +01005643 are followed to create the response :
5644
5645 * If neither the errorfile nor the payload to use is defined, a dummy
5646 response is returned. Only the "status" argument is considered. It can be
5647 any code in the range [200, 599]. The "content-type" argument, if any, is
5648 ignored.
5649
5650 * If "default-errorfiles" argument is set, the proxy's errorfiles are
5651 considered. If the "status" argument is defined, it must be one of the
Daniel Corbett67a82712020-07-06 23:01:19 -04005652 status code handled by haproxy (200, 400, 403, 404, 405, 408, 410, 413,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02005653 425, 429, 500, 502, 503, and 504). The "content-type" argument, if any,
5654 is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01005655
5656 * If a specific errorfile is defined, with an "errorfile" argument, the
5657 corresponding file, containing a full HTTP response, is returned. Only the
5658 "status" argument is considered. It must be one of the status code handled
Daniel Corbett67a82712020-07-06 23:01:19 -04005659 by haproxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 502, 503,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02005660 and 504). The "content-type" argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01005661
5662 * If an http-errors section is defined, with an "errorfiles" argument, the
5663 corresponding file in the specified http-errors section, containing a full
5664 HTTP response, is returned. Only the "status" argument is considered. It
Daniel Corbett67a82712020-07-06 23:01:19 -04005665 must be one of the status code handled by haproxy (200, 400, 403, 404, 405,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02005666 408, 410, 413, 425, 429, 500, 502, 503, and 504). The "content-type"
5667 argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01005668
5669 * If a "file" or a "lf-file" argument is specified, the file's content is
5670 used as the response payload. If the file is not empty, its content-type
5671 must be set as argument to "content-type". Otherwise, any "content-type"
5672 argument is ignored. With a "lf-file" argument, the file's content is
5673 evaluated as a log-format string. With a "file" argument, it is considered
5674 as a raw content.
5675
5676 * If a "string" or "lf-string" argument is specified, the defined string is
5677 used as the response payload. The content-type must always be set as
5678 argument to "content-type". With a "lf-string" argument, the string is
5679 evaluated as a log-format string. With a "string" argument, it is
5680 considered as a raw string.
5681
Christopher Faulet4a2c1422020-01-31 17:36:01 +01005682 When the response is not based an errorfile, it is possible to appends HTTP
5683 header fields to the response using "hdr" arguments. Otherwise, all "hdr"
5684 arguments are ignored. For each one, the header name is specified in <name>
5685 and its value is defined by <fmt> which follows the log-format rules.
5686
Christopher Faulet24231ab2020-01-24 17:44:23 +01005687 Note that the generated response must be smaller than a buffer. And to avoid
5688 any warning, when an errorfile or a raw file is loaded, the buffer space
Ilya Shipitsin11057a32020-06-21 21:18:27 +05005689 reserved to the headers rewriting should also be free.
Christopher Faulet24231ab2020-01-24 17:44:23 +01005690
5691 No further "http-request" rules are evaluated.
5692
5693 Example:
Daniel Corbett67a82712020-07-06 23:01:19 -04005694 http-request return errorfile /etc/haproxy/errorfiles/200.http \
Christopher Faulet24231ab2020-01-24 17:44:23 +01005695 if { path /ping }
5696
5697 http-request return content-type image/x-icon file /var/www/favicon.ico \
5698 if { path /favicon.ico }
5699
5700 http-request return status 403 content-type text/plain \
5701 lf-string "Access denied. IP %[src] is blacklisted." \
5702 if { src -f /etc/haproxy/blacklist.lst }
5703
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005704http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
5705http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005706
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005707 This actions increments the GPC0 or GPC1 counter according with the sticky
5708 counter designated by <sc-id>. If an error occurs, this action silently fails
5709 and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005710
Cédric Dufour0d7712d2019-11-06 18:38:53 +01005711http-request sc-set-gpt0(<sc-id>) { <int> | <expr> }
5712 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005713
Cédric Dufour0d7712d2019-11-06 18:38:53 +01005714 This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
5715 designated by <sc-id> and the value of <int>/<expr>. The expected result is a
5716 boolean. If an error occurs, this action silently fails and the actions
5717 evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005718
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005719http-request set-dst <expr> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005720
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005721 This is used to set the destination IP address to the value of specified
5722 expression. Useful when a proxy in front of HAProxy rewrites destination IP,
5723 but provides the correct IP in a HTTP header; or you want to mask the IP for
5724 privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
5725 server address in the backend.
Christopher Faulet85d79c92016-11-09 16:54:56 +01005726
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005727 Arguments:
5728 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
5729 by some converters.
Christopher Faulet85d79c92016-11-09 16:54:56 +01005730
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005731 Example:
5732 http-request set-dst hdr(x-dst)
5733 http-request set-dst dst,ipmask(24)
Christopher Faulet85d79c92016-11-09 16:54:56 +01005734
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005735 When possible, set-dst preserves the original destination port as long as the
5736 address family allows it, otherwise the destination port is set to 0.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02005737
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005738http-request set-dst-port <expr> [ { if | unless } <condition> ]
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02005739
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005740 This is used to set the destination port address to the value of specified
5741 expression. If you want to connect to the new address/port, use '0.0.0.0:0'
5742 as a server address in the backend.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02005743
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005744 Arguments:
5745 <expr> Is a standard HAProxy expression formed by a sample-fetch
5746 followed by some converters.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02005747
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005748 Example:
5749 http-request set-dst-port hdr(x-port)
5750 http-request set-dst-port int(4000)
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02005751
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005752 When possible, set-dst-port preserves the original destination address as
5753 long as the address family supports a port, otherwise it forces the
5754 destination address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02005755
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005756http-request set-header <name> <fmt> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02005757
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005758 This does the same as "http-request add-header" except that the header name
5759 is first removed if it existed. This is useful when passing security
5760 information to the server, where the header must not be manipulated by
5761 external users. Note that the new value is computed before the removal so it
5762 is possible to concatenate a value to an existing header.
William Lallemand44be6402016-05-25 01:51:35 +02005763
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005764 Example:
5765 http-request set-header X-Haproxy-Current-Date %T
5766 http-request set-header X-SSL %[ssl_fc]
5767 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
5768 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
5769 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
5770 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
5771 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
5772 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
5773 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
William Lallemand44be6402016-05-25 01:51:35 +02005774
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005775http-request set-log-level <level> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02005776
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005777 This is used to change the log level of the current request when a certain
5778 condition is met. Valid levels are the 8 syslog levels (see the "log"
5779 keyword) plus the special level "silent" which disables logging for this
5780 request. This rule is not final so the last matching rule wins. This rule
5781 can be useful to disable health checks coming from another equipment.
William Lallemand13e9b0c2016-05-25 02:34:07 +02005782
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005783http-request set-map(<file-name>) <key fmt> <value fmt>
5784 [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02005785
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005786 This is used to add a new entry into a MAP. The MAP must be loaded from a
5787 file (even a dummy empty file). The file name of the MAP to be updated is
5788 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
5789 log-format rules, used to collect MAP key, and <value fmt>, which follows
5790 log-format rules, used to collect content for the new entry.
5791 It performs a lookup in the MAP before insertion, to avoid duplicated (or
5792 more) values. This lookup is done by a linear search and can be expensive
5793 with large lists! It is the equivalent of the "set map" command from the
5794 stats socket, but can be triggered by an HTTP request.
William Lallemand13e9b0c2016-05-25 02:34:07 +02005795
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005796http-request set-mark <mark> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02005797
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005798 This is used to set the Netfilter MARK on all packets sent to the client to
5799 the value passed in <mark> on platforms which support it. This value is an
5800 unsigned 32 bit value which can be matched by netfilter and by the routing
5801 table. It can be expressed both in decimal or hexadecimal format (prefixed by
5802 "0x"). This can be useful to force certain packets to take a different route
5803 (for example a cheaper network path for bulk downloads). This works on Linux
5804 kernels 2.6.32 and above and requires admin privileges.
Willy Tarreau00005ce2016-10-21 15:07:45 +02005805
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005806http-request set-method <fmt> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02005807
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005808 This rewrites the request method with the result of the evaluation of format
5809 string <fmt>. There should be very few valid reasons for having to do so as
5810 this is more likely to break something than to fix it.
William Lallemand13e9b0c2016-05-25 02:34:07 +02005811
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005812http-request set-nice <nice> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02005813
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005814 This sets the "nice" factor of the current request being processed. It only
5815 has effect against the other requests being processed at the same time.
5816 The default value is 0, unless altered by the "nice" setting on the "bind"
5817 line. The accepted range is -1024..1024. The higher the value, the nicest
5818 the request will be. Lower values will make the request more important than
5819 other ones. This can be useful to improve the speed of some requests, or
5820 lower the priority of non-important requests. Using this setting without
5821 prior experimentation can cause some major slowdown.
William Lallemand13e9b0c2016-05-25 02:34:07 +02005822
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005823http-request set-path <fmt> [ { if | unless } <condition> ]
Willy Tarreau00005ce2016-10-21 15:07:45 +02005824
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005825 This rewrites the request path with the result of the evaluation of format
5826 string <fmt>. The query string, if any, is left intact. If a scheme and
5827 authority is found before the path, they are left intact as well. If the
5828 request doesn't have a path ("*"), this one is replaced with the format.
5829 This can be used to prepend a directory component in front of a path for
5830 example. See also "http-request set-query" and "http-request set-uri".
Willy Tarreau2d392c22015-08-24 01:43:45 +02005831
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005832 Example :
5833 # prepend the host name before the path
5834 http-request set-path /%[hdr(host)]%[path]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005835
Christopher Faulet312294f2020-09-02 17:17:44 +02005836http-request set-pathq <fmt> [ { if | unless } <condition> ]
5837
5838 This does the same as "http-request set-path" except that the query-string is
5839 also rewritten. It may be used to remove the query-string, including the
5840 question mark (it is not possible using "http-request set-query").
5841
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005842http-request set-priority-class <expr> [ { if | unless } <condition> ]
Olivier Houchardccaa7de2017-10-02 11:51:03 +02005843
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005844 This is used to set the queue priority class of the current request.
5845 The value must be a sample expression which converts to an integer in the
5846 range -2047..2047. Results outside this range will be truncated.
5847 The priority class determines the order in which queued requests are
5848 processed. Lower values have higher priority.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005849
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005850http-request set-priority-offset <expr> [ { if | unless } <condition> ]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005851
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005852 This is used to set the queue priority timestamp offset of the current
5853 request. The value must be a sample expression which converts to an integer
5854 in the range -524287..524287. Results outside this range will be truncated.
5855 When a request is queued, it is ordered first by the priority class, then by
5856 the current timestamp adjusted by the given offset in milliseconds. Lower
5857 values have higher priority.
5858 Note that the resulting timestamp is is only tracked with enough precision
5859 for 524,287ms (8m44s287ms). If the request is queued long enough to where the
5860 adjusted timestamp exceeds this value, it will be misidentified as highest
5861 priority. Thus it is important to set "timeout queue" to a value, where when
5862 combined with the offset, does not exceed this limit.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005863
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005864http-request set-query <fmt> [ { if | unless } <condition> ]
Willy Tarreau20b0de52012-12-24 15:45:22 +01005865
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005866 This rewrites the request's query string which appears after the first
5867 question mark ("?") with the result of the evaluation of format string <fmt>.
5868 The part prior to the question mark is left intact. If the request doesn't
5869 contain a question mark and the new value is not empty, then one is added at
5870 the end of the URI, followed by the new value. If a question mark was
5871 present, it will never be removed even if the value is empty. This can be
5872 used to add or remove parameters from the query string.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08005873
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005874 See also "http-request set-query" and "http-request set-uri".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005875
5876 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005877 # replace "%3D" with "=" in the query string
5878 http-request set-query %[query,regsub(%3D,=,g)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005879
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005880http-request set-src <expr> [ { if | unless } <condition> ]
5881 This is used to set the source IP address to the value of specified
5882 expression. Useful when a proxy in front of HAProxy rewrites source IP, but
5883 provides the correct IP in a HTTP header; or you want to mask source IP for
Olivier Doucet56e31202020-04-21 09:32:56 +02005884 privacy. All subsequent calls to "src" fetch will return this value
5885 (see example).
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005886
5887 Arguments :
5888 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
5889 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005890
Olivier Doucet56e31202020-04-21 09:32:56 +02005891 See also "option forwardfor".
5892
Cyril Bonté78caf842010-03-10 22:41:43 +01005893 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005894 http-request set-src hdr(x-forwarded-for)
5895 http-request set-src src,ipmask(24)
5896
Olivier Doucet56e31202020-04-21 09:32:56 +02005897 # After the masking this will track connections
5898 # based on the IP address with the last byte zeroed out.
5899 http-request track-sc0 src
5900
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005901 When possible, set-src preserves the original source port as long as the
5902 address family allows it, otherwise the source port is set to 0.
5903
5904http-request set-src-port <expr> [ { if | unless } <condition> ]
5905
5906 This is used to set the source port address to the value of specified
5907 expression.
5908
5909 Arguments:
5910 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
5911 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01005912
Willy Tarreau20b0de52012-12-24 15:45:22 +01005913 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005914 http-request set-src-port hdr(x-port)
5915 http-request set-src-port int(4000)
5916
5917 When possible, set-src-port preserves the original source address as long as
5918 the address family supports a port, otherwise it forces the source address to
5919 IPv4 "0.0.0.0" before rewriting the port.
5920
5921http-request set-tos <tos> [ { if | unless } <condition> ]
5922
5923 This is used to set the TOS or DSCP field value of packets sent to the client
5924 to the value passed in <tos> on platforms which support this. This value
5925 represents the whole 8 bits of the IP TOS field, and can be expressed both in
5926 decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
5927 bits are used in DSCP or TOS, and the two lower bits are always 0. This can
5928 be used to adjust some routing behavior on border routers based on some
5929 information from the request.
5930
5931 See RFC 2474, 2597, 3260 and 4594 for more information.
5932
5933http-request set-uri <fmt> [ { if | unless } <condition> ]
5934
5935 This rewrites the request URI with the result of the evaluation of format
5936 string <fmt>. The scheme, authority, path and query string are all replaced
5937 at once. This can be used to rewrite hosts in front of proxies, or to
5938 perform complex modifications to the URI such as moving parts between the
5939 path and the query string.
5940 See also "http-request set-path" and "http-request set-query".
5941
5942http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ]
5943
5944 This is used to set the contents of a variable. The variable is declared
5945 inline.
5946
5947 Arguments:
5948 <var-name> The name of the variable starts with an indication about its
5949 scope. The scopes allowed are:
5950 "proc" : the variable is shared with the whole process
5951 "sess" : the variable is shared with the whole session
5952 "txn" : the variable is shared with the transaction
5953 (request and response)
5954 "req" : the variable is shared only during request
5955 processing
5956 "res" : the variable is shared only during response
5957 processing
5958 This prefix is followed by a name. The separator is a '.'.
5959 The name may only contain characters 'a-z', 'A-Z', '0-9'
5960 and '_'.
5961
5962 <expr> Is a standard HAProxy expression formed by a sample-fetch
5963 followed by some converters.
Willy Tarreau20b0de52012-12-24 15:45:22 +01005964
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005965 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005966 http-request set-var(req.my_var) req.fhdr(user-agent),lower
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005967
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005968http-request send-spoe-group <engine-name> <group-name>
5969 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005970
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005971 This action is used to trigger sending of a group of SPOE messages. To do so,
5972 the SPOE engine used to send messages must be defined, as well as the SPOE
5973 group to send. Of course, the SPOE engine must refer to an existing SPOE
5974 filter. If not engine name is provided on the SPOE filter line, the SPOE
5975 agent name must be used.
5976
5977 Arguments:
5978 <engine-name> The SPOE engine name.
5979
5980 <group-name> The SPOE group name as specified in the engine
5981 configuration.
5982
5983http-request silent-drop [ { if | unless } <condition> ]
5984
5985 This stops the evaluation of the rules and makes the client-facing connection
5986 suddenly disappear using a system-dependent way that tries to prevent the
5987 client from being notified. The effect it then that the client still sees an
5988 established connection while there's none on HAProxy. The purpose is to
5989 achieve a comparable effect to "tarpit" except that it doesn't use any local
5990 resource at all on the machine running HAProxy. It can resist much higher
5991 loads than "tarpit", and slow down stronger attackers. It is important to
5992 understand the impact of using this mechanism. All stateful equipment placed
5993 between the client and HAProxy (firewalls, proxies, load balancers) will also
5994 keep the established connection for a long time and may suffer from this
5995 action.
5996 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
5997 option is used to block the emission of a TCP reset. On other systems, the
5998 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
5999 router, though it's still delivered to local networks. Do not use it unless
6000 you fully understand how it works.
6001
Christopher Faulet46f95542019-12-20 10:07:22 +01006002http-request strict-mode { on | off }
6003
6004 This enables or disables the strict rewriting mode for following rules. It
6005 does not affect rules declared before it and it is only applicable on rules
6006 performing a rewrite on the requests. When the strict mode is enabled, any
6007 rewrite failure triggers an internal error. Otherwise, such errors are
6008 silently ignored. The purpose of the strict rewriting mode is to make some
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006009 rewrites optional while others must be performed to continue the request
Christopher Faulet46f95542019-12-20 10:07:22 +01006010 processing.
6011
Christopher Faulet1aea50e2020-01-17 16:03:53 +01006012 By default, the strict rewriting mode is enabled. Its value is also reset
Christopher Faulet46f95542019-12-20 10:07:22 +01006013 when a ruleset evaluation ends. So, for instance, if you change the mode on
6014 the frontend, the default mode is restored when HAProxy starts the backend
6015 rules evaluation.
6016
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006017http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
6018http-request tarpit [ { status | deny_status } <code>] [content-type <type>]
6019 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
6020 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
6021 [ hdr <name> <fmt> ]*
6022 [ { if | unless } <condition> ]
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006023
6024 This stops the evaluation of the rules and immediately blocks the request
6025 without responding for a delay specified by "timeout tarpit" or
6026 "timeout connect" if the former is not set. After that delay, if the client
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006027 is still connected, a response is returned so that the client does not
6028 suspect it has been tarpitted. Logs will report the flags "PT". The goal of
6029 the tarpit rule is to slow down robots during an attack when they're limited
6030 on the number of concurrent requests. It can be very efficient against very
6031 dumb robots, and will significantly reduce the load on firewalls compared to
6032 a "deny" rule. But when facing "correctly" developed robots, it can make
6033 things worse by forcing haproxy and the front firewall to support insane
6034 number of concurrent connections. By default an HTTP error 500 is returned.
6035 But the response may be customized using same syntax than
6036 "http-request return" rules. Thus, see "http-request return" for details.
Ilya Shipitsin11057a32020-06-21 21:18:27 +05006037 For compatibility purpose, when no argument is defined, or only "deny_status",
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006038 the argument "default-errorfiles" is implied. It means
6039 "http-request tarpit [deny_status <status>]" is an alias of
6040 "http-request tarpit [status <status>] default-errorfiles".
6041 No further "http-request" rules are evaluated.
6042 See also "http-request return" and "http-request silent-drop".
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006043
6044http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
6045http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
6046http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
6047
6048 This enables tracking of sticky counters from current request. These rules do
6049 not stop evaluation and do not change default action. The number of counters
6050 that may be simultaneously tracked by the same connection is set in
6051 MAX_SESS_STKCTR at build time (reported in haproxy -vv) which defaults to 3,
6052 so the track-sc number is between 0 and (MAX_SESS_STCKTR-1). The first
6053 "track-sc0" rule executed enables tracking of the counters of the specified
6054 table as the first set. The first "track-sc1" rule executed enables tracking
6055 of the counters of the specified table as the second set. The first
6056 "track-sc2" rule executed enables tracking of the counters of the specified
6057 table as the third set. It is a recommended practice to use the first set of
6058 counters for the per-frontend counters and the second set for the per-backend
6059 ones. But this is just a guideline, all may be used everywhere.
6060
6061 Arguments :
6062 <key> is mandatory, and is a sample expression rule as described in
6063 section 7.3. It describes what elements of the incoming request or
6064 connection will be analyzed, extracted, combined, and used to
6065 select which table entry to update the counters.
6066
6067 <table> is an optional table to be used instead of the default one, which
6068 is the stick-table declared in the current proxy. All the counters
6069 for the matches and updates for the key will then be performed in
6070 that table until the session ends.
6071
6072 Once a "track-sc*" rule is executed, the key is looked up in the table and if
6073 it is not found, an entry is allocated for it. Then a pointer to that entry
6074 is kept during all the session's life, and this entry's counters are updated
6075 as often as possible, every time the session's counters are updated, and also
6076 systematically when the session ends. Counters are only updated for events
6077 that happen after the tracking has been started. As an exception, connection
6078 counters and request counters are systematically updated so that they reflect
6079 useful information.
6080
6081 If the entry tracks concurrent connection counters, one connection is counted
6082 for as long as the entry is tracked, and the entry will not expire during
6083 that time. Tracking counters also provides a performance advantage over just
6084 checking the keys, because only one table lookup is performed for all ACL
6085 checks that make use of it.
6086
6087http-request unset-var(<var-name>) [ { if | unless } <condition> ]
6088
6089 This is used to unset a variable. See above for details about <var-name>.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006090
6091 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006092 http-request unset-var(req.my_var)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006093
Christopher Faulet579d83b2019-11-22 15:34:17 +01006094http-request use-service <service-name> [ { if | unless } <condition> ]
6095
6096 This directive executes the configured HTTP service to reply to the request
6097 and stops the evaluation of the rules. An HTTP service may choose to reply by
6098 sending any valid HTTP response or it may immediately close the connection
6099 without sending any response. Outside natives services, for instance the
6100 Prometheus exporter, it is possible to write your own services in Lua. No
6101 further "http-request" rules are evaluated.
6102
6103 Arguments :
6104 <service-name> is mandatory. It is the service to call
6105
6106 Example:
6107 http-request use-service prometheus-exporter if { path /metrics }
6108
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006109http-request wait-for-handshake [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006110
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02006111 This will delay the processing of the request until the SSL handshake
6112 happened. This is mostly useful to delay processing early data until we're
6113 sure they are valid.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006114
Willy Tarreauef781042010-01-27 11:53:01 +01006115
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006116http-response <action> <options...> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006117 Access control for Layer 7 responses
6118
6119 May be used in sections: defaults | frontend | listen | backend
6120 no | yes | yes | yes
6121
6122 The http-response statement defines a set of rules which apply to layer 7
6123 processing. The rules are evaluated in their declaration order when they are
6124 met in a frontend, listen or backend section. Any rule may optionally be
6125 followed by an ACL-based condition, in which case it will only be evaluated
6126 if the condition is true. Since these rules apply on responses, the backend
6127 rules are applied first, followed by the frontend's rules.
6128
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006129 The first keyword is the rule's action. The supported actions are described
6130 below.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006131
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006132 There is no limit to the number of http-response statements per instance.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006133
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006134 Example:
6135 acl key_acl res.hdr(X-Acl-Key) -m found
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02006136
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006137 acl myhost hdr(Host) -f myhost.lst
Sasha Pachev218f0642014-06-16 12:05:59 -06006138
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006139 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
6140 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
Sasha Pachev218f0642014-06-16 12:05:59 -06006141
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006142 Example:
6143 acl value res.hdr(X-Value) -m found
Sasha Pachev218f0642014-06-16 12:05:59 -06006144
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006145 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06006146
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006147 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
6148 http-response del-map(map.lst) %[src] if ! value
Sasha Pachev218f0642014-06-16 12:05:59 -06006149
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006150 See also : "http-request", section 3.4 about userlists and section 7 about
6151 ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06006152
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006153http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006154
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006155 This is used to add a new entry into an ACL. The ACL must be loaded from a
6156 file (even a dummy empty file). The file name of the ACL to be updated is
6157 passed between parentheses. It takes one argument: <key fmt>, which follows
6158 log-format rules, to collect content of the new entry. It performs a lookup
6159 in the ACL before insertion, to avoid duplicated (or more) values.
6160 This lookup is done by a linear search and can be expensive with large lists!
6161 It is the equivalent of the "add acl" command from the stats socket, but can
6162 be triggered by an HTTP response.
Sasha Pachev218f0642014-06-16 12:05:59 -06006163
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006164http-response add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006165
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006166 This appends an HTTP header field whose name is specified in <name> and whose
6167 value is defined by <fmt> which follows the log-format rules (see Custom Log
6168 Format in section 8.2.4). This may be used to send a cookie to a client for
6169 example, or to pass some internal information.
6170 This rule is not final, so it is possible to add other similar rules.
6171 Note that header addition is performed immediately, so one rule might reuse
6172 the resulting header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06006173
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006174http-response allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006175
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006176 This stops the evaluation of the rules and lets the response pass the check.
6177 No further "http-response" rules are evaluated for the current section.
Sasha Pachev218f0642014-06-16 12:05:59 -06006178
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02006179http-response cache-store <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006180
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02006181 See section 6.2 about cache setup.
Sasha Pachev218f0642014-06-16 12:05:59 -06006182
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006183http-response capture <sample> id <id> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06006184
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006185 This captures sample expression <sample> from the response buffer, and
6186 converts it to a string. The resulting string is stored into the next request
6187 "capture" slot, so it will possibly appear next to some captured HTTP
6188 headers. It will then automatically appear in the logs, and it will be
6189 possible to extract it using sample fetch rules to feed it into headers or
6190 anything. Please check section 7.3 (Fetching samples) and
6191 "capture response header" for more information.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02006192
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006193 The keyword "id" is the id of the capture slot which is used for storing the
6194 string. The capture slot must be defined in an associated frontend.
6195 This is useful to run captures in backends. The slot id can be declared by a
6196 previous directive "http-response capture" or with the "declare capture"
6197 keyword.
Baptiste Assmann19a69b32020-01-16 14:34:22 +01006198
6199 When using this action in a backend, double check that the relevant
6200 frontend(s) have the required capture slots otherwise, this rule will be
6201 ignored at run time. This can't be detected at configuration parsing time
6202 due to HAProxy's ability to dynamically resolve backend name at runtime.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02006203
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006204http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02006205
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006206 This is used to delete an entry from an ACL. The ACL must be loaded from a
6207 file (even a dummy empty file). The file name of the ACL to be updated is
6208 passed between parentheses. It takes one argument: <key fmt>, which follows
6209 log-format rules, to collect content of the entry to delete.
6210 It is the equivalent of the "del acl" command from the stats socket, but can
6211 be triggered by an HTTP response.
Willy Tarreauf4c43c12013-06-11 17:01:13 +02006212
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006213http-response del-header <name> [ { if | unless } <condition> ]
Willy Tarreau9a355ec2013-06-11 17:45:46 +02006214
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006215 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau42cf39e2013-06-11 18:51:32 +02006216
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006217http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau51347ed2013-06-11 19:34:13 +02006218
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006219 This is used to delete an entry from a MAP. The MAP must be loaded from a
6220 file (even a dummy empty file). The file name of the MAP to be updated is
6221 passed between parentheses. It takes one argument: <key fmt>, which follows
6222 log-format rules, to collect content of the entry to delete.
6223 It takes one argument: "file name" It is the equivalent of the "del map"
6224 command from the stats socket, but can be triggered by an HTTP response.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006225
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006226http-response deny [deny_status <status>] [ { if | unless } <condition> ]
6227http-response deny [ { status | deny_status } <code>] [content-type <type>]
6228 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
6229 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
6230 [ hdr <name> <fmt> ]*
6231 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006232
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006233 This stops the evaluation of the rules and immediately rejects the response.
6234 By default an HTTP 502 error is returned. But the response may be customized
6235 using same syntax than "http-response return" rules. Thus, see
Ilya Shipitsin11057a32020-06-21 21:18:27 +05006236 "http-response return" for details. For compatibility purpose, when no
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006237 argument is defined, or only "deny_status", the argument "default-errorfiles"
6238 is implied. It means "http-response deny [deny_status <status>]" is an alias
6239 of "http-response deny [status <status>] default-errorfiles".
Christopher Faulet040c8cd2020-01-13 16:43:45 +01006240 No further "http-response" rules are evaluated.
Christopher Faulet5cb513a2020-05-13 17:56:56 +02006241 See also "http-response return".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006242
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006243http-response redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006244
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006245 This performs an HTTP redirection based on a redirect rule.
6246 This supports a format string similarly to "http-request redirect" rules,
6247 with the exception that only the "location" type of redirect is possible on
6248 the response. See the "redirect" keyword for the rule's syntax. When a
6249 redirect rule is applied during a response, connections to the server are
6250 closed so that no data can be forwarded from the server to the client.
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02006251
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006252http-response replace-header <name> <regex-match> <replace-fmt>
6253 [ { if | unless } <condition> ]
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02006254
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006255 This works like "http-request replace-header" except that it works on the
6256 server's response instead of the client's request.
William Lallemand86d0df02017-11-24 21:36:45 +01006257
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006258 Example:
6259 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
Willy Tarreau51d861a2015-05-22 17:30:48 +02006260
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006261 # applied to:
6262 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006263
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006264 # outputs:
6265 Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006266
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006267 # assuming the backend IP is 192.168.1.20.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006268
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006269http-response replace-value <name> <regex-match> <replace-fmt>
6270 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006271
Tim Duesterhus6bd909b2020-01-17 15:53:18 +01006272 This works like "http-request replace-value" except that it works on the
Tim Duesterhus2252beb2019-10-29 00:05:13 +01006273 server's response instead of the client's request.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02006274
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006275 Example:
6276 http-response replace-value Cache-control ^public$ private
Christopher Faulet85d79c92016-11-09 16:54:56 +01006277
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006278 # applied to:
6279 Cache-Control: max-age=3600, public
Christopher Faulet85d79c92016-11-09 16:54:56 +01006280
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006281 # outputs:
6282 Cache-Control: max-age=3600, private
Christopher Faulet85d79c92016-11-09 16:54:56 +01006283
Christopher Faulet24231ab2020-01-24 17:44:23 +01006284http-response return [status <code>] [content-type <type>]
6285 [ { default-errorfiles | errorfile <file> | errorfiles <name> |
6286 file <file> | lf-file <file> | string <str> | lf-string <fmt> } ]
Christopher Faulet4a2c1422020-01-31 17:36:01 +01006287 [ hdr <name> <value> ]*
Christopher Faulet24231ab2020-01-24 17:44:23 +01006288 [ { if | unless } <condition> ]
6289
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006290 This stops the evaluation of the rules and immediately returns a response. The
Christopher Faulet24231ab2020-01-24 17:44:23 +01006291 default status code used for the response is 200. It can be optionally
6292 specified as an arguments to "status". The response content-type may also be
Daniel Corbett67a82712020-07-06 23:01:19 -04006293 specified as an argument to "content-type". Finally the response itself may
Christopher Faulet24231ab2020-01-24 17:44:23 +01006294 be defined. If can be a full HTTP response specifying the errorfile to use,
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006295 or the response payload specifying the file or the string to use. These rules
Christopher Faulet24231ab2020-01-24 17:44:23 +01006296 are followed to create the response :
6297
6298 * If neither the errorfile nor the payload to use is defined, a dummy
6299 response is returned. Only the "status" argument is considered. It can be
6300 any code in the range [200, 599]. The "content-type" argument, if any, is
6301 ignored.
6302
6303 * If "default-errorfiles" argument is set, the proxy's errorfiles are
6304 considered. If the "status" argument is defined, it must be one of the
Daniel Corbett67a82712020-07-06 23:01:19 -04006305 status code handled by haproxy (200, 400, 403, 404, 405, 408, 410, 413,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02006306 425, 429, 500, 502, 503, and 504). The "content-type" argument, if any,
6307 is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006308
6309 * If a specific errorfile is defined, with an "errorfile" argument, the
6310 corresponding file, containing a full HTTP response, is returned. Only the
6311 "status" argument is considered. It must be one of the status code handled
Daniel Corbett67a82712020-07-06 23:01:19 -04006312 by haproxy (200, 400, 403, 404, 405, 408, 410, 413, 425, 429, 500, 502, 503,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02006313 and 504). The "content-type" argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006314
6315 * If an http-errors section is defined, with an "errorfiles" argument, the
6316 corresponding file in the specified http-errors section, containing a full
6317 HTTP response, is returned. Only the "status" argument is considered. It
Daniel Corbett67a82712020-07-06 23:01:19 -04006318 must be one of the status code handled by haproxy (200, 400, 403, 404, 405,
Anthonin Bonnefoy85048f82020-06-22 09:17:01 +02006319 408, 410, 413, 425, 429, 500, 502, 503, and 504). The "content-type"
6320 argument, if any, is ignored.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006321
6322 * If a "file" or a "lf-file" argument is specified, the file's content is
6323 used as the response payload. If the file is not empty, its content-type
6324 must be set as argument to "content-type". Otherwise, any "content-type"
6325 argument is ignored. With a "lf-file" argument, the file's content is
6326 evaluated as a log-format string. With a "file" argument, it is considered
6327 as a raw content.
6328
6329 * If a "string" or "lf-string" argument is specified, the defined string is
6330 used as the response payload. The content-type must always be set as
6331 argument to "content-type". With a "lf-string" argument, the string is
6332 evaluated as a log-format string. With a "string" argument, it is
6333 considered as a raw string.
6334
Christopher Faulet4a2c1422020-01-31 17:36:01 +01006335 When the response is not based an errorfile, it is possible to appends HTTP
6336 header fields to the response using "hdr" arguments. Otherwise, all "hdr"
6337 arguments are ignored. For each one, the header name is specified in <name>
6338 and its value is defined by <fmt> which follows the log-format rules.
6339
Christopher Faulet24231ab2020-01-24 17:44:23 +01006340 Note that the generated response must be smaller than a buffer. And to avoid
6341 any warning, when an errorfile or a raw file is loaded, the buffer space
Ilya Shipitsin11057a32020-06-21 21:18:27 +05006342 reserved to the headers rewriting should also be free.
Christopher Faulet24231ab2020-01-24 17:44:23 +01006343
6344 No further "http-response" rules are evaluated.
6345
6346 Example:
Daniel Corbett67a82712020-07-06 23:01:19 -04006347 http-response return errorfile /etc/haproxy/errorfiles/200.http \
Christopher Faulet24231ab2020-01-24 17:44:23 +01006348 if { status eq 404 }
6349
6350 http-response return content-type text/plain \
6351 string "This is the end !" \
6352 if { status eq 500 }
6353
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006354http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
6355http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08006356
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006357 This action increments the GPC0 or GPC1 counter according with the sticky
6358 counter designated by <sc-id>. If an error occurs, this action silently fails
6359 and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02006360
Cédric Dufour0d7712d2019-11-06 18:38:53 +01006361http-response sc-set-gpt0(<sc-id>) { <int> | <expr> }
6362 [ { if | unless } <condition> ]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02006363
Cédric Dufour0d7712d2019-11-06 18:38:53 +01006364 This action sets the 32-bit unsigned GPT0 tag according to the sticky counter
6365 designated by <sc-id> and the value of <int>/<expr>. The expected result is a
6366 boolean. If an error occurs, this action silently fails and the actions
6367 evaluation continues.
Frédéric Lécaille6778b272018-01-29 15:22:53 +01006368
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006369http-response send-spoe-group [ { if | unless } <condition> ]
Willy Tarreau2d392c22015-08-24 01:43:45 +02006370
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006371 This action is used to trigger sending of a group of SPOE messages. To do so,
6372 the SPOE engine used to send messages must be defined, as well as the SPOE
6373 group to send. Of course, the SPOE engine must refer to an existing SPOE
6374 filter. If not engine name is provided on the SPOE filter line, the SPOE
6375 agent name must be used.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006376
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006377 Arguments:
6378 <engine-name> The SPOE engine name.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006379
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006380 <group-name> The SPOE group name as specified in the engine
6381 configuration.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02006382
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006383http-response set-header <name> <fmt> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006384
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006385 This does the same as "add-header" except that the header name is first
6386 removed if it existed. This is useful when passing security information to
6387 the server, where the header must not be manipulated by external users.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006388
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006389http-response set-log-level <level> [ { if | unless } <condition> ]
6390
6391 This is used to change the log level of the current request when a certain
6392 condition is met. Valid levels are the 8 syslog levels (see the "log"
6393 keyword) plus the special level "silent" which disables logging for this
6394 request. This rule is not final so the last matching rule wins. This rule can
6395 be useful to disable health checks coming from another equipment.
6396
6397http-response set-map(<file-name>) <key fmt> <value fmt>
6398
6399 This is used to add a new entry into a MAP. The MAP must be loaded from a
6400 file (even a dummy empty file). The file name of the MAP to be updated is
6401 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
6402 log-format rules, used to collect MAP key, and <value fmt>, which follows
6403 log-format rules, used to collect content for the new entry. It performs a
6404 lookup in the MAP before insertion, to avoid duplicated (or more) values.
6405 This lookup is done by a linear search and can be expensive with large lists!
6406 It is the equivalent of the "set map" command from the stats socket, but can
6407 be triggered by an HTTP response.
6408
6409http-response set-mark <mark> [ { if | unless } <condition> ]
6410
6411 This is used to set the Netfilter MARK on all packets sent to the client to
6412 the value passed in <mark> on platforms which support it. This value is an
6413 unsigned 32 bit value which can be matched by netfilter and by the routing
6414 table. It can be expressed both in decimal or hexadecimal format (prefixed
6415 by "0x"). This can be useful to force certain packets to take a different
6416 route (for example a cheaper network path for bulk downloads). This works on
6417 Linux kernels 2.6.32 and above and requires admin privileges.
6418
6419http-response set-nice <nice> [ { if | unless } <condition> ]
6420
6421 This sets the "nice" factor of the current request being processed.
6422 It only has effect against the other requests being processed at the same
6423 time. The default value is 0, unless altered by the "nice" setting on the
6424 "bind" line. The accepted range is -1024..1024. The higher the value, the
6425 nicest the request will be. Lower values will make the request more important
6426 than other ones. This can be useful to improve the speed of some requests, or
6427 lower the priority of non-important requests. Using this setting without
6428 prior experimentation can cause some major slowdown.
6429
6430http-response set-status <status> [reason <str>]
6431 [ { if | unless } <condition> ]
6432
6433 This replaces the response status code with <status> which must be an integer
6434 between 100 and 999. Optionally, a custom reason text can be provided defined
6435 by <str>, or the default reason for the specified code will be used as a
6436 fallback.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08006437
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006438 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006439 # return "431 Request Header Fields Too Large"
6440 http-response set-status 431
6441 # return "503 Slow Down", custom reason
6442 http-response set-status 503 reason "Slow Down".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006443
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006444http-response set-tos <tos> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006445
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006446 This is used to set the TOS or DSCP field value of packets sent to the client
6447 to the value passed in <tos> on platforms which support this.
6448 This value represents the whole 8 bits of the IP TOS field, and can be
6449 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note that
6450 only the 6 higher bits are used in DSCP or TOS, and the two lower bits are
6451 always 0. This can be used to adjust some routing behavior on border routers
6452 based on some information from the request.
6453
6454 See RFC 2474, 2597, 3260 and 4594 for more information.
6455
6456http-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
6457
6458 This is used to set the contents of a variable. The variable is declared
6459 inline.
6460
6461 Arguments:
6462 <var-name> The name of the variable starts with an indication about its
6463 scope. The scopes allowed are:
6464 "proc" : the variable is shared with the whole process
6465 "sess" : the variable is shared with the whole session
6466 "txn" : the variable is shared with the transaction
6467 (request and response)
6468 "req" : the variable is shared only during request
6469 processing
6470 "res" : the variable is shared only during response
6471 processing
6472 This prefix is followed by a name. The separator is a '.'.
6473 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
6474 and '_'.
6475
6476 <expr> Is a standard HAProxy expression formed by a sample-fetch
6477 followed by some converters.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006478
6479 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006480 http-response set-var(sess.last_redir) res.hdr(location)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006481
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006482http-response silent-drop [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006483
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006484 This stops the evaluation of the rules and makes the client-facing connection
6485 suddenly disappear using a system-dependent way that tries to prevent the
6486 client from being notified. The effect it then that the client still sees an
6487 established connection while there's none on HAProxy. The purpose is to
6488 achieve a comparable effect to "tarpit" except that it doesn't use any local
6489 resource at all on the machine running HAProxy. It can resist much higher
6490 loads than "tarpit", and slow down stronger attackers. It is important to
6491 understand the impact of using this mechanism. All stateful equipment placed
6492 between the client and HAProxy (firewalls, proxies, load balancers) will also
6493 keep the established connection for a long time and may suffer from this
6494 action.
6495 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
6496 option is used to block the emission of a TCP reset. On other systems, the
6497 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
6498 router, though it's still delivered to local networks. Do not use it unless
6499 you fully understand how it works.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02006500
Christopher Faulet46f95542019-12-20 10:07:22 +01006501http-response strict-mode { on | off }
6502
6503 This enables or disables the strict rewriting mode for following rules. It
6504 does not affect rules declared before it and it is only applicable on rules
6505 performing a rewrite on the responses. When the strict mode is enabled, any
6506 rewrite failure triggers an internal error. Otherwise, such errors are
6507 silently ignored. The purpose of the strict rewriting mode is to make some
Ilya Shipitsin8525fd92020-02-29 12:34:59 +05006508 rewrites optional while others must be performed to continue the response
Christopher Faulet46f95542019-12-20 10:07:22 +01006509 processing.
6510
Christopher Faulet1aea50e2020-01-17 16:03:53 +01006511 By default, the strict rewriting mode is enabled. Its value is also reset
Christopher Faulet46f95542019-12-20 10:07:22 +01006512 when a ruleset evaluation ends. So, for instance, if you change the mode on
Daniel Corbett67a82712020-07-06 23:01:19 -04006513 the backend, the default mode is restored when HAProxy starts the frontend
Christopher Faulet46f95542019-12-20 10:07:22 +01006514 rules evaluation.
6515
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006516http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
6517http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
6518http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02006519
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02006520 This enables tracking of sticky counters from current response. Please refer
6521 to "http-request track-sc" for a complete description. The only difference
6522 from "http-request track-sc" is the <key> sample expression can only make use
6523 of samples in response (e.g. res.*, status etc.) and samples below Layer 6
6524 (e.g. SSL-related samples, see section 7.3.4). If the sample is not
6525 supported, haproxy will fail and warn while parsing the config.
6526
6527http-response unset-var(<var-name>) [ { if | unless } <condition> ]
6528
6529 This is used to unset a variable. See "http-response set-var" for details
6530 about <var-name>.
6531
6532 Example:
6533 http-response unset-var(sess.last_redir)
6534
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02006535
Willy Tarreau30631952015-08-06 15:05:24 +02006536http-reuse { never | safe | aggressive | always }
6537 Declare how idle HTTP connections may be shared between requests
6538
6539 May be used in sections: defaults | frontend | listen | backend
6540 yes | no | yes | yes
6541
6542 By default, a connection established between haproxy and the backend server
Olivier Houchard86006a52018-12-14 19:37:49 +01006543 which is considered safe for reuse is moved back to the server's idle
6544 connections pool so that any other request can make use of it. This is the
6545 "safe" strategy below.
Willy Tarreau30631952015-08-06 15:05:24 +02006546
6547 The argument indicates the desired connection reuse strategy :
6548
Olivier Houchard86006a52018-12-14 19:37:49 +01006549 - "never" : idle connections are never shared between sessions. This mode
6550 may be enforced to cancel a different strategy inherited from
6551 a defaults section or for troubleshooting. For example, if an
6552 old bogus application considers that multiple requests over
6553 the same connection come from the same client and it is not
6554 possible to fix the application, it may be desirable to
6555 disable connection sharing in a single backend. An example of
6556 such an application could be an old haproxy using cookie
6557 insertion in tunnel mode and not checking any request past the
6558 first one.
Willy Tarreau30631952015-08-06 15:05:24 +02006559
Olivier Houchard86006a52018-12-14 19:37:49 +01006560 - "safe" : this is the default and the recommended strategy. The first
6561 request of a session is always sent over its own connection,
6562 and only subsequent requests may be dispatched over other
6563 existing connections. This ensures that in case the server
6564 closes the connection when the request is being sent, the
6565 browser can decide to silently retry it. Since it is exactly
6566 equivalent to regular keep-alive, there should be no side
6567 effects.
Willy Tarreau30631952015-08-06 15:05:24 +02006568
6569 - "aggressive" : this mode may be useful in webservices environments where
6570 all servers are not necessarily known and where it would be
6571 appreciable to deliver most first requests over existing
6572 connections. In this case, first requests are only delivered
6573 over existing connections that have been reused at least once,
6574 proving that the server correctly supports connection reuse.
6575 It should only be used when it's sure that the client can
6576 retry a failed request once in a while and where the benefit
Michael Prokop4438c602019-05-24 10:25:45 +02006577 of aggressive connection reuse significantly outweighs the
Willy Tarreau30631952015-08-06 15:05:24 +02006578 downsides of rare connection failures.
6579
6580 - "always" : this mode is only recommended when the path to the server is
6581 known for never breaking existing connections quickly after
6582 releasing them. It allows the first request of a session to be
6583 sent to an existing connection. This can provide a significant
6584 performance increase over the "safe" strategy when the backend
6585 is a cache farm, since such components tend to show a
Davor Ocelice9ed2812017-12-25 17:49:28 +01006586 consistent behavior and will benefit from the connection
Willy Tarreau30631952015-08-06 15:05:24 +02006587 sharing. It is recommended that the "http-keep-alive" timeout
6588 remains low in this mode so that no dead connections remain
6589 usable. In most cases, this will lead to the same performance
6590 gains as "aggressive" but with more risks. It should only be
6591 used when it improves the situation over "aggressive".
6592
6593 When http connection sharing is enabled, a great care is taken to respect the
Davor Ocelice9ed2812017-12-25 17:49:28 +01006594 connection properties and compatibility. Specifically :
6595 - connections made with "usesrc" followed by a client-dependent value
6596 ("client", "clientip", "hdr_ip") are marked private and never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02006597
6598 - connections sent to a server with a TLS SNI extension are marked private
Davor Ocelice9ed2812017-12-25 17:49:28 +01006599 and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02006600
Lukas Tribusfd9b68c2018-10-27 20:06:59 +02006601 - connections with certain bogus authentication schemes (relying on the
6602 connection) like NTLM are detected, marked private and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02006603
Lukas Tribuse8adfeb2019-11-06 11:50:25 +01006604 A connection pool is involved and configurable with "pool-max-conn".
Willy Tarreau30631952015-08-06 15:05:24 +02006605
6606 Note: connection reuse improves the accuracy of the "server maxconn" setting,
6607 because almost no new connection will be established while idle connections
6608 remain available. This is particularly true with the "always" strategy.
6609
6610 See also : "option http-keep-alive", "server maxconn"
6611
6612
Mark Lamourinec2247f02012-01-04 13:02:01 -05006613http-send-name-header [<header>]
6614 Add the server name to a request. Use the header string given by <header>
Mark Lamourinec2247f02012-01-04 13:02:01 -05006615 May be used in sections: defaults | frontend | listen | backend
6616 yes | no | yes | yes
Mark Lamourinec2247f02012-01-04 13:02:01 -05006617 Arguments :
Mark Lamourinec2247f02012-01-04 13:02:01 -05006618 <header> The header string to use to send the server name
6619
Willy Tarreau81bef7e2019-10-07 14:58:02 +02006620 The "http-send-name-header" statement causes the header field named <header>
6621 to be set to the name of the target server at the moment the request is about
6622 to be sent on the wire. Any existing occurrences of this header are removed.
6623 Upon retries and redispatches, the header field is updated to always reflect
6624 the server being attempted to connect to. Given that this header is modified
6625 very late in the connection setup, it may have unexpected effects on already
6626 modified headers. For example using it with transport-level header such as
6627 connection, content-length, transfer-encoding and so on will likely result in
6628 invalid requests being sent to the server. Additionally it has been reported
6629 that this directive is currently being used as a way to overwrite the Host
6630 header field in outgoing requests; while this trick has been known to work
6631 as a side effect of the feature for some time, it is not officially supported
6632 and might possibly not work anymore in a future version depending on the
6633 technical difficulties this feature induces. A long-term solution instead
6634 consists in fixing the application which required this trick so that it binds
6635 to the correct host name.
Mark Lamourinec2247f02012-01-04 13:02:01 -05006636
6637 See also : "server"
6638
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01006639id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02006640 Set a persistent ID to a proxy.
6641 May be used in sections : defaults | frontend | listen | backend
6642 no | yes | yes | yes
6643 Arguments : none
6644
6645 Set a persistent ID for the proxy. This ID must be unique and positive.
6646 An unused ID will automatically be assigned if unset. The first assigned
6647 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01006648
6649
Cyril Bonté0d4bf012010-04-25 23:21:46 +02006650ignore-persist { if | unless } <condition>
6651 Declare a condition to ignore persistence
6652 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01006653 no | no | yes | yes
Cyril Bonté0d4bf012010-04-25 23:21:46 +02006654
6655 By default, when cookie persistence is enabled, every requests containing
6656 the cookie are unconditionally persistent (assuming the target server is up
6657 and running).
6658
6659 The "ignore-persist" statement allows one to declare various ACL-based
6660 conditions which, when met, will cause a request to ignore persistence.
6661 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006662 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02006663 persistence for a specific User-Agent (for example, some web crawler bots).
6664
Cyril Bonté0d4bf012010-04-25 23:21:46 +02006665 The persistence is ignored when an "if" condition is met, or unless an
6666 "unless" condition is met.
6667
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03006668 Example:
6669 acl url_static path_beg /static /images /img /css
6670 acl url_static path_end .gif .png .jpg .css .js
6671 ignore-persist if url_static
6672
Cyril Bonté0d4bf012010-04-25 23:21:46 +02006673 See also : "force-persist", "cookie", and section 7 about ACL usage.
6674
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006675load-server-state-from-file { global | local | none }
6676 Allow seamless reload of HAProxy
6677 May be used in sections: defaults | frontend | listen | backend
6678 yes | no | yes | yes
6679
6680 This directive points HAProxy to a file where server state from previous
6681 running process has been saved. That way, when starting up, before handling
6682 traffic, the new process can apply old states to servers exactly has if no
Davor Ocelice9ed2812017-12-25 17:49:28 +01006683 reload occurred. The purpose of the "load-server-state-from-file" directive is
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006684 to tell haproxy which file to use. For now, only 2 arguments to either prevent
6685 loading state or load states from a file containing all backends and servers.
6686 The state file can be generated by running the command "show servers state"
6687 over the stats socket and redirect output.
6688
Davor Ocelice9ed2812017-12-25 17:49:28 +01006689 The format of the file is versioned and is very specific. To understand it,
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006690 please read the documentation of the "show servers state" command (chapter
Willy Tarreau1af20c72017-06-23 16:01:14 +02006691 9.3 of Management Guide).
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006692
6693 Arguments:
6694 global load the content of the file pointed by the global directive
6695 named "server-state-file".
6696
6697 local load the content of the file pointed by the directive
6698 "server-state-file-name" if set. If not set, then the backend
6699 name is used as a file name.
6700
6701 none don't load any stat for this backend
6702
6703 Notes:
Willy Tarreaue5a60682016-11-09 14:54:53 +01006704 - server's IP address is preserved across reloads by default, but the
6705 order can be changed thanks to the server's "init-addr" setting. This
6706 means that an IP address change performed on the CLI at run time will
Davor Ocelice9ed2812017-12-25 17:49:28 +01006707 be preserved, and that any change to the local resolver (e.g. /etc/hosts)
Willy Tarreaue5a60682016-11-09 14:54:53 +01006708 will possibly not have any effect if the state file is in use.
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006709
6710 - server's weight is applied from previous running process unless it has
6711 has changed between previous and new configuration files.
6712
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006713 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006714
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006715 global
6716 stats socket /tmp/socket
6717 server-state-file /tmp/server_state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006718
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006719 defaults
6720 load-server-state-from-file global
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006721
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006722 backend bk
6723 server s1 127.0.0.1:22 check weight 11
6724 server s2 127.0.0.1:22 check weight 12
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006725
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006726
6727 Then one can run :
6728
6729 socat /tmp/socket - <<< "show servers state" > /tmp/server_state
6730
6731 Content of the file /tmp/server_state would be like this:
6732
6733 1
6734 # <field names skipped for the doc example>
6735 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
6736 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
6737
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006738 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006739
6740 global
6741 stats socket /tmp/socket
6742 server-state-base /etc/haproxy/states
6743
6744 defaults
6745 load-server-state-from-file local
6746
6747 backend bk
6748 server s1 127.0.0.1:22 check weight 11
6749 server s2 127.0.0.1:22 check weight 12
6750
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006751
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02006752 Then one can run :
6753
6754 socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
6755
6756 Content of the file /etc/haproxy/states/bk would be like this:
6757
6758 1
6759 # <field names skipped for the doc example>
6760 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
6761 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
6762
6763 See also: "server-state-file", "server-state-file-name", and
6764 "show servers state"
6765
Cyril Bonté0d4bf012010-04-25 23:21:46 +02006766
Willy Tarreau2769aa02007-12-27 18:26:09 +01006767log global
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02006768log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
6769 <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02006770no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01006771 Enable per-instance logging of events and traffic.
6772 May be used in sections : defaults | frontend | listen | backend
6773 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02006774
6775 Prefix :
6776 no should be used when the logger list must be flushed. For example,
6777 if you don't want to inherit from the default logger list. This
6778 prefix does not allow arguments.
6779
Willy Tarreau2769aa02007-12-27 18:26:09 +01006780 Arguments :
6781 global should be used when the instance's logging parameters are the
6782 same as the global ones. This is the most common usage. "global"
6783 replaces <address>, <facility> and <level> with those of the log
6784 entries found in the "global" section. Only one "log global"
6785 statement may be used per instance, and this form takes no other
6786 parameter.
6787
6788 <address> indicates where to send the logs. It takes the same format as
6789 for the "global" section's logs, and can be one of :
6790
6791 - An IPv4 address optionally followed by a colon (':') and a UDP
6792 port. If no port is specified, 514 is used by default (the
6793 standard syslog port).
6794
David du Colombier24bb5f52011-03-17 10:40:23 +01006795 - An IPv6 address followed by a colon (':') and optionally a UDP
6796 port. If no port is specified, 514 is used by default (the
6797 standard syslog port).
6798
Willy Tarreau2769aa02007-12-27 18:26:09 +01006799 - A filesystem path to a UNIX domain socket, keeping in mind
6800 considerations for chroot (be sure the path is accessible
6801 inside the chroot) and uid/gid (be sure the path is
Davor Ocelice9ed2812017-12-25 17:49:28 +01006802 appropriately writable).
Willy Tarreau2769aa02007-12-27 18:26:09 +01006803
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01006804 - A file descriptor number in the form "fd@<number>", which may
6805 point to a pipe, terminal, or socket. In this case unbuffered
6806 logs are used and one writev() call per log is performed. This
6807 is a bit expensive but acceptable for most workloads. Messages
6808 sent this way will not be truncated but may be dropped, in
6809 which case the DroppedLogs counter will be incremented. The
6810 writev() call is atomic even on pipes for messages up to
6811 PIPE_BUF size, which POSIX recommends to be at least 512 and
6812 which is 4096 bytes on most modern operating systems. Any
6813 larger message may be interleaved with messages from other
6814 processes. Exceptionally for debugging purposes the file
6815 descriptor may also be directed to a file, but doing so will
6816 significantly slow haproxy down as non-blocking calls will be
6817 ignored. Also there will be no way to purge nor rotate this
6818 file without restarting the process. Note that the configured
6819 syslog format is preserved, so the output is suitable for use
Willy Tarreauc1b06452018-11-12 11:57:56 +01006820 with a TCP syslog server. See also the "short" and "raw"
6821 formats below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01006822
6823 - "stdout" / "stderr", which are respectively aliases for "fd@1"
6824 and "fd@2", see above.
6825
Willy Tarreauc046d162019-08-30 15:24:59 +02006826 - A ring buffer in the form "ring@<name>", which will correspond
6827 to an in-memory ring buffer accessible over the CLI using the
6828 "show events" command, which will also list existing rings and
6829 their sizes. Such buffers are lost on reload or restart but
6830 when used as a complement this can help troubleshooting by
6831 having the logs instantly available.
6832
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01006833 You may want to reference some environment variables in the
6834 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01006835
Willy Tarreau18324f52014-06-27 18:10:07 +02006836 <length> is an optional maximum line length. Log lines larger than this
6837 value will be truncated before being sent. The reason is that
6838 syslog servers act differently on log line length. All servers
6839 support the default value of 1024, but some servers simply drop
6840 larger lines while others do log them. If a server supports long
6841 lines, it may make sense to set this value here in order to avoid
6842 truncating long lines. Similarly, if a server drops long lines,
6843 it is preferable to truncate them before sending them. Accepted
6844 values are 80 to 65535 inclusive. The default value of 1024 is
6845 generally fine for all standard usages. Some specific cases of
Davor Ocelice9ed2812017-12-25 17:49:28 +01006846 long captures or JSON-formatted logs may require larger values.
Willy Tarreau18324f52014-06-27 18:10:07 +02006847
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02006848 <ranges> A list of comma-separated ranges to identify the logs to sample.
6849 This is used to balance the load of the logs to send to the log
6850 server. The limits of the ranges cannot be null. They are numbered
6851 from 1. The size or period (in number of logs) of the sample must
6852 be set with <sample_size> parameter.
6853
6854 <sample_size>
6855 The size of the sample in number of logs to consider when balancing
6856 their logging loads. It is used to balance the load of the logs to
6857 send to the syslog server. This size must be greater or equal to the
6858 maximum of the high limits of the ranges.
6859 (see also <ranges> parameter).
6860
Willy Tarreauadb345d2018-11-12 07:56:13 +01006861 <format> is the log format used when generating syslog messages. It may be
6862 one of the following :
6863
6864 rfc3164 The RFC3164 syslog message format. This is the default.
6865 (https://tools.ietf.org/html/rfc3164)
6866
6867 rfc5424 The RFC5424 syslog message format.
6868 (https://tools.ietf.org/html/rfc5424)
6869
Emeric Brun54648852020-07-06 15:54:06 +02006870 priority A message containing only a level plus syslog facility between
6871 angle brackets such as '<63>', followed by the text. The PID,
6872 date, time, process name and system name are omitted. This is
6873 designed to be used with a local log server.
6874
Willy Tarreaue8746a02018-11-12 08:45:00 +01006875 short A message containing only a level between angle brackets such as
6876 '<3>', followed by the text. The PID, date, time, process name
6877 and system name are omitted. This is designed to be used with a
6878 local log server. This format is compatible with what the
6879 systemd logger consumes.
6880
Emeric Brun54648852020-07-06 15:54:06 +02006881 timed A message containing only a level between angle brackets such as
6882 '<3>', followed by ISO date and by the text. The PID, process
6883 name and system name are omitted. This is designed to be
6884 used with a local log server.
6885
6886 iso A message containing only the ISO date, followed by the text.
6887 The PID, process name and system name are omitted. This is
6888 designed to be used with a local log server.
6889
Willy Tarreauc1b06452018-11-12 11:57:56 +01006890 raw A message containing only the text. The level, PID, date, time,
6891 process name and system name are omitted. This is designed to
6892 be used in containers or during development, where the severity
6893 only depends on the file descriptor used (stdout/stderr).
6894
Willy Tarreau2769aa02007-12-27 18:26:09 +01006895 <facility> must be one of the 24 standard syslog facilities :
6896
Willy Tarreaue8746a02018-11-12 08:45:00 +01006897 kern user mail daemon auth syslog lpr news
6898 uucp cron auth2 ftp ntp audit alert cron2
6899 local0 local1 local2 local3 local4 local5 local6 local7
6900
Willy Tarreauc1b06452018-11-12 11:57:56 +01006901 Note that the facility is ignored for the "short" and "raw"
6902 formats, but still required as a positional field. It is
6903 recommended to use "daemon" in this case to make it clear that
6904 it's only supposed to be used locally.
Willy Tarreau2769aa02007-12-27 18:26:09 +01006905
6906 <level> is optional and can be specified to filter outgoing messages. By
6907 default, all messages are sent. If a level is specified, only
6908 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02006909 will be sent. An optional minimum level can be specified. If it
6910 is set, logs emitted with a more severe level than this one will
6911 be capped to this level. This is used to avoid sending "emerg"
6912 messages on all terminals on some default syslog configurations.
6913 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01006914
6915 emerg alert crit err warning notice info debug
6916
William Lallemand0f99e342011-10-12 17:50:54 +02006917 It is important to keep in mind that it is the frontend which decides what to
6918 log from a connection, and that in case of content switching, the log entries
6919 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01006920
6921 However, backend log declaration define how and where servers status changes
6922 will be logged. Level "notice" will be used to indicate a server going up,
6923 "warning" will be used for termination signals and definitive service
6924 termination, and "alert" will be used for when a server goes down.
6925
6926 Note : According to RFC3164, messages are truncated to 1024 bytes before
6927 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01006928
6929 Example :
6930 log global
Willy Tarreauc1b06452018-11-12 11:57:56 +01006931 log stdout format short daemon # send log to systemd
6932 log stdout format raw daemon # send everything to stdout
6933 log stderr format raw daemon notice # send important events to stderr
Willy Tarreauf7edefa2009-05-10 17:20:05 +02006934 log 127.0.0.1:514 local0 notice # only send important events
6935 log 127.0.0.1:514 local0 notice notice # same but limit output level
William Lallemandb2f07452015-05-12 14:27:13 +02006936 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01006937
Willy Tarreau2769aa02007-12-27 18:26:09 +01006938
William Lallemand48940402012-01-30 16:47:22 +01006939log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01006940 Specifies the log format string to use for traffic logs
6941 May be used in sections: defaults | frontend | listen | backend
6942 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01006943
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01006944 This directive specifies the log format string that will be used for all logs
6945 resulting from traffic passing through the frontend using this line. If the
6946 directive is used in a defaults section, all subsequent frontends will use
6947 the same log format. Please see section 8.2.4 which covers the log format
6948 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01006949
Guillaume de Lafond29f45602017-03-31 19:52:15 +02006950 "log-format" directive overrides previous "option tcplog", "log-format" and
6951 "option httplog" directives.
6952
Dragan Dosen7ad31542015-09-28 17:16:47 +02006953log-format-sd <string>
6954 Specifies the RFC5424 structured-data log format string
6955 May be used in sections: defaults | frontend | listen | backend
6956 yes | yes | yes | no
6957
6958 This directive specifies the RFC5424 structured-data log format string that
6959 will be used for all logs resulting from traffic passing through the frontend
6960 using this line. If the directive is used in a defaults section, all
6961 subsequent frontends will use the same log format. Please see section 8.2.4
6962 which covers the log format string in depth.
6963
6964 See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
6965 about the RFC5424 structured-data part.
6966
6967 Note : This log format string will be used only for loggers that have set
6968 log format to "rfc5424".
6969
6970 Example :
6971 log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
6972
6973
Willy Tarreau094af4e2015-01-07 15:03:42 +01006974log-tag <string>
6975 Specifies the log tag to use for all outgoing logs
6976 May be used in sections: defaults | frontend | listen | backend
6977 yes | yes | yes | yes
6978
6979 Sets the tag field in the syslog header to this string. It defaults to the
6980 log-tag set in the global section, otherwise the program name as launched
6981 from the command line, which usually is "haproxy". Sometimes it can be useful
6982 to differentiate between multiple processes running on the same host, or to
6983 differentiate customer instances running in the same process. In the backend,
6984 logs about servers up/down will use this tag. As a hint, it can be convenient
6985 to set a log-tag related to a hosted customer in a defaults section then put
6986 all the frontends and backends for that customer, then start another customer
6987 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01006988
Willy Tarreauc35362a2014-04-25 13:58:37 +02006989max-keep-alive-queue <value>
6990 Set the maximum server queue size for maintaining keep-alive connections
6991 May be used in sections: defaults | frontend | listen | backend
6992 yes | no | yes | yes
6993
6994 HTTP keep-alive tries to reuse the same server connection whenever possible,
6995 but sometimes it can be counter-productive, for example if a server has a lot
6996 of connections while other ones are idle. This is especially true for static
6997 servers.
6998
6999 The purpose of this setting is to set a threshold on the number of queued
7000 connections at which haproxy stops trying to reuse the same server and prefers
7001 to find another one. The default value, -1, means there is no limit. A value
7002 of zero means that keep-alive requests will never be queued. For very close
7003 servers which can be reached with a low latency and which are not sensible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01007004 breaking keep-alive, a low value is recommended (e.g. local static server can
Willy Tarreauc35362a2014-04-25 13:58:37 +02007005 use a value of 10 or less). For remote servers suffering from a high latency,
7006 higher values might be needed to cover for the latency and/or the cost of
7007 picking a different server.
7008
7009 Note that this has no impact on responses which are maintained to the same
7010 server consecutively to a 401 response. They will still go to the same server
7011 even if they have to be queued.
7012
7013 See also : "option http-server-close", "option prefer-last-server", server
7014 "maxconn" and cookie persistence.
7015
Olivier Houcharda4d4fdf2018-12-14 19:27:06 +01007016max-session-srv-conns <nb>
7017 Set the maximum number of outgoing connections we can keep idling for a given
7018 client session. The default is 5 (it precisely equals MAX_SRV_LIST which is
7019 defined at build time).
Willy Tarreauc35362a2014-04-25 13:58:37 +02007020
Willy Tarreau2769aa02007-12-27 18:26:09 +01007021maxconn <conns>
7022 Fix the maximum number of concurrent connections on a frontend
7023 May be used in sections : defaults | frontend | listen | backend
7024 yes | yes | yes | no
7025 Arguments :
7026 <conns> is the maximum number of concurrent connections the frontend will
7027 accept to serve. Excess connections will be queued by the system
7028 in the socket's listen queue and will be served once a connection
7029 closes.
7030
7031 If the system supports it, it can be useful on big sites to raise this limit
7032 very high so that haproxy manages connection queues, instead of leaving the
7033 clients with unanswered connection attempts. This value should not exceed the
7034 global maxconn. Also, keep in mind that a connection contains two buffers
Baptiste Assmann79fb45d2016-03-06 23:34:31 +01007035 of tune.bufsize (16kB by default) each, as well as some other data resulting
7036 in about 33 kB of RAM being consumed per established connection. That means
7037 that a medium system equipped with 1GB of RAM can withstand around
7038 20000-25000 concurrent connections if properly tuned.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007039
7040 Also, when <conns> is set to large values, it is possible that the servers
7041 are not sized to accept such loads, and for this reason it is generally wise
7042 to assign them some reasonable connection limits.
7043
Willy Tarreauc8d5b952019-02-27 17:25:52 +01007044 When this value is set to zero, which is the default, the global "maxconn"
7045 value is used.
Vincent Bernat6341be52012-06-27 17:18:30 +02007046
Willy Tarreau2769aa02007-12-27 18:26:09 +01007047 See also : "server", global section's "maxconn", "fullconn"
7048
7049
7050mode { tcp|http|health }
7051 Set the running mode or protocol of the instance
7052 May be used in sections : defaults | frontend | listen | backend
7053 yes | yes | yes | yes
7054 Arguments :
7055 tcp The instance will work in pure TCP mode. A full-duplex connection
7056 will be established between clients and servers, and no layer 7
7057 examination will be performed. This is the default mode. It
7058 should be used for SSL, SSH, SMTP, ...
7059
7060 http The instance will work in HTTP mode. The client request will be
7061 analyzed in depth before connecting to any server. Any request
7062 which is not RFC-compliant will be rejected. Layer 7 filtering,
7063 processing and switching will be possible. This is the mode which
7064 brings HAProxy most of its value.
7065
7066 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02007067 to incoming connections and close the connection. Alternatively,
7068 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
7069 instead. Nothing will be logged in either case. This mode is used
7070 to reply to external components health checks. This mode is
7071 deprecated and should not be used anymore as it is possible to do
7072 the same and even better by combining TCP or HTTP modes with the
7073 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007074
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007075 When doing content switching, it is mandatory that the frontend and the
7076 backend are in the same mode (generally HTTP), otherwise the configuration
7077 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007078
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007079 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01007080 defaults http_instances
7081 mode http
7082
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007083 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01007084
Willy Tarreau0ba27502007-12-24 16:55:16 +01007085
Cyril Bontéf0c60612010-02-06 14:44:47 +01007086monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01007087 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007088 May be used in sections : defaults | frontend | listen | backend
7089 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01007090 Arguments :
7091 if <cond> the monitor request will fail if the condition is satisfied,
7092 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007093 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01007094 are met, for instance a low number of servers both in a
7095 backend and its backup.
7096
7097 unless <cond> the monitor request will succeed only if the condition is
7098 satisfied, and will fail otherwise. Such a condition may be
7099 based on a test on the presence of a minimum number of active
7100 servers in a list of backends.
7101
7102 This statement adds a condition which can force the response to a monitor
7103 request to report a failure. By default, when an external component queries
7104 the URI dedicated to monitoring, a 200 response is returned. When one of the
7105 conditions above is met, haproxy will return 503 instead of 200. This is
7106 very useful to report a site failure to an external component which may base
7107 routing advertisements between multiple sites on the availability reported by
7108 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02007109 criterion. Note that "monitor fail" only works in HTTP mode. Both status
7110 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007111
7112 Example:
7113 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01007114 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01007115 acl site_dead nbsrv(dynamic) lt 2
7116 acl site_dead nbsrv(static) lt 2
7117 monitor-uri /site_alive
7118 monitor fail if site_dead
7119
Willy Tarreauae94d4d2011-05-11 16:28:49 +02007120 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01007121
7122
7123monitor-net <source>
7124 Declare a source network which is limited to monitor requests
7125 May be used in sections : defaults | frontend | listen | backend
7126 yes | yes | yes | no
7127 Arguments :
7128 <source> is the source IPv4 address or network which will only be able to
7129 get monitor responses to any request. It can be either an IPv4
7130 address, a host name, or an address followed by a slash ('/')
7131 followed by a mask.
7132
7133 In TCP mode, any connection coming from a source matching <source> will cause
7134 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007135 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01007136 forwarding the connection to a remote server.
7137
7138 In HTTP mode, a connection coming from a source matching <source> will be
7139 accepted, the following response will be sent without waiting for a request,
7140 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
7141 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02007142 running without forwarding the request to a backend server. Note that this
7143 response is sent in raw format, without any transformation. This is important
7144 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01007145
Willy Tarreau82569f92012-09-27 23:48:56 +02007146 Monitor requests are processed very early, just after tcp-request connection
7147 ACLs which are the only ones able to block them. These connections are short
7148 lived and never wait for any data from the client. They cannot be logged, and
7149 it is the intended purpose. They are only used to report HAProxy's health to
7150 an upper component, nothing more. Please note that "monitor fail" rules do
7151 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01007152
Willy Tarreau95cd2832010-03-04 23:36:33 +01007153 Last, please note that only one "monitor-net" statement can be specified in
7154 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007155
Willy Tarreau2769aa02007-12-27 18:26:09 +01007156 Example :
7157 # addresses .252 and .253 are just probing us.
7158 frontend www
7159 monitor-net 192.168.0.252/31
7160
7161 See also : "monitor fail", "monitor-uri"
7162
7163
7164monitor-uri <uri>
7165 Intercept a URI used by external components' monitor requests
7166 May be used in sections : defaults | frontend | listen | backend
7167 yes | yes | yes | no
7168 Arguments :
7169 <uri> is the exact URI which we want to intercept to return HAProxy's
7170 health status instead of forwarding the request.
7171
7172 When an HTTP request referencing <uri> will be received on a frontend,
7173 HAProxy will not forward it nor log it, but instead will return either
7174 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
7175 conditions defined with "monitor fail". This is normally enough for any
7176 front-end HTTP probe to detect that the service is UP and running without
7177 forwarding the request to a backend server. Note that the HTTP method, the
7178 version and all headers are ignored, but the request must at least be valid
7179 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
7180
Willy Tarreau721d8e02017-12-01 18:25:08 +01007181 Monitor requests are processed very early, just after the request is parsed
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02007182 and even before any "http-request". The only rulesets applied before are the
7183 tcp-request ones. They cannot be logged either, and it is the intended
7184 purpose. They are only used to report HAProxy's health to an upper component,
7185 nothing more. However, it is possible to add any number of conditions using
7186 "monitor fail" and ACLs so that the result can be adjusted to whatever check
7187 can be imagined (most often the number of available servers in a backend).
Willy Tarreau2769aa02007-12-27 18:26:09 +01007188
Christopher Faulet6072beb2020-02-18 15:34:58 +01007189 Note: if <uri> starts by a slash ('/'), the matching is performed against the
7190 request's path instead of the request's uri. It is a workaround to let
7191 the HTTP/2 requests match the monitor-uri. Indeed, in HTTP/2, clients
7192 are encouraged to send absolute URIs only.
7193
Willy Tarreau2769aa02007-12-27 18:26:09 +01007194 Example :
7195 # Use /haproxy_test to report haproxy's status
7196 frontend www
7197 mode http
7198 monitor-uri /haproxy_test
7199
7200 See also : "monitor fail", "monitor-net"
7201
Willy Tarreau0ba27502007-12-24 16:55:16 +01007202
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007203option abortonclose
7204no option abortonclose
7205 Enable or disable early dropping of aborted requests pending in queues.
7206 May be used in sections : defaults | frontend | listen | backend
7207 yes | no | yes | yes
7208 Arguments : none
7209
7210 In presence of very high loads, the servers will take some time to respond.
7211 The per-instance connection queue will inflate, and the response time will
7212 increase respective to the size of the queue times the average per-session
7213 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01007214 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007215 the queue, and slowing down other users, and the servers as well, because the
7216 request will eventually be served, then aborted at the first error
7217 encountered while delivering the response.
7218
7219 As there is no way to distinguish between a full STOP and a simple output
7220 close on the client side, HTTP agents should be conservative and consider
7221 that the client might only have closed its output channel while waiting for
7222 the response. However, this introduces risks of congestion when lots of users
7223 do the same, and is completely useless nowadays because probably no client at
7224 all will close the session while waiting for the response. Some HTTP agents
Davor Ocelice9ed2812017-12-25 17:49:28 +01007225 support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007226 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01007227 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007228 of being the single component to break rare but valid traffic is extremely
7229 low, which adds to the temptation to be able to abort a session early while
7230 still not served and not pollute the servers.
7231
Davor Ocelice9ed2812017-12-25 17:49:28 +01007232 In HAProxy, the user can choose the desired behavior using the option
7233 "abortonclose". By default (without the option) the behavior is HTTP
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007234 compliant and aborted requests will be served. But when the option is
7235 specified, a session with an incoming channel closed will be aborted while
7236 it is still possible, either pending in the queue for a connection slot, or
7237 during the connection establishment if the server has not yet acknowledged
7238 the connection request. This considerably reduces the queue size and the load
7239 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01007240 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007241
7242 If this option has been enabled in a "defaults" section, it can be disabled
7243 in a specific instance by prepending the "no" keyword before it.
7244
7245 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
7246
7247
Willy Tarreau4076a152009-04-02 15:18:36 +02007248option accept-invalid-http-request
7249no option accept-invalid-http-request
7250 Enable or disable relaxing of HTTP request parsing
7251 May be used in sections : defaults | frontend | listen | backend
7252 yes | yes | yes | no
7253 Arguments : none
7254
Willy Tarreau91852eb2015-05-01 13:26:00 +02007255 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02007256 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01007257 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02007258 forbidden characters are essentially used to build attacks exploiting server
7259 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
7260 server will emit invalid header names for whatever reason (configuration,
7261 implementation) and the issue will not be immediately fixed. In such a case,
7262 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01007263 even if that does not make sense, by specifying this option. Similarly, the
7264 list of characters allowed to appear in a URI is well defined by RFC3986, and
7265 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
7266 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
Davor Ocelice9ed2812017-12-25 17:49:28 +01007267 not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02007268 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02007269 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
7270 to pass through (no version specified) and multiple digits for both the major
7271 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02007272
7273 This option should never be enabled by default as it hides application bugs
7274 and open security breaches. It should only be deployed after a problem has
7275 been confirmed.
7276
7277 When this option is enabled, erroneous header names will still be accepted in
7278 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01007279 analysis using the "show errors" request on the UNIX stats socket. Similarly,
7280 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02007281 also helps confirming that the issue has been solved.
7282
7283 If this option has been enabled in a "defaults" section, it can be disabled
7284 in a specific instance by prepending the "no" keyword before it.
7285
7286 See also : "option accept-invalid-http-response" and "show errors" on the
7287 stats socket.
7288
7289
7290option accept-invalid-http-response
7291no option accept-invalid-http-response
7292 Enable or disable relaxing of HTTP response parsing
7293 May be used in sections : defaults | frontend | listen | backend
7294 yes | no | yes | yes
7295 Arguments : none
7296
Willy Tarreau91852eb2015-05-01 13:26:00 +02007297 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02007298 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01007299 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02007300 forbidden characters are essentially used to build attacks exploiting server
7301 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
7302 server will emit invalid header names for whatever reason (configuration,
7303 implementation) and the issue will not be immediately fixed. In such a case,
7304 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02007305 even if that does not make sense, by specifying this option. This option also
7306 relaxes the test on the HTTP version format, it allows multiple digits for
7307 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02007308
7309 This option should never be enabled by default as it hides application bugs
7310 and open security breaches. It should only be deployed after a problem has
7311 been confirmed.
7312
7313 When this option is enabled, erroneous header names will still be accepted in
7314 responses, but the complete response will be captured in order to permit
7315 later analysis using the "show errors" request on the UNIX stats socket.
7316 Doing this also helps confirming that the issue has been solved.
7317
7318 If this option has been enabled in a "defaults" section, it can be disabled
7319 in a specific instance by prepending the "no" keyword before it.
7320
7321 See also : "option accept-invalid-http-request" and "show errors" on the
7322 stats socket.
7323
7324
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007325option allbackups
7326no option allbackups
7327 Use either all backup servers at a time or only the first one
7328 May be used in sections : defaults | frontend | listen | backend
7329 yes | no | yes | yes
7330 Arguments : none
7331
7332 By default, the first operational backup server gets all traffic when normal
7333 servers are all down. Sometimes, it may be preferred to use multiple backups
7334 at once, because one will not be enough. When "option allbackups" is enabled,
7335 the load balancing will be performed among all backup servers when all normal
7336 ones are unavailable. The same load balancing algorithm will be used and the
7337 servers' weights will be respected. Thus, there will not be any priority
7338 order between the backup servers anymore.
7339
7340 This option is mostly used with static server farms dedicated to return a
7341 "sorry" page when an application is completely offline.
7342
7343 If this option has been enabled in a "defaults" section, it can be disabled
7344 in a specific instance by prepending the "no" keyword before it.
7345
7346
7347option checkcache
7348no option checkcache
Godbach7056a352013-12-11 20:01:07 +08007349 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007350 May be used in sections : defaults | frontend | listen | backend
7351 yes | no | yes | yes
7352 Arguments : none
7353
7354 Some high-level frameworks set application cookies everywhere and do not
7355 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007356 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007357 high risk of session crossing or stealing between users traversing the same
7358 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02007359 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007360
7361 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007362 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01007363 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007364 response to check if there's a risk of caching a cookie on a client-side
7365 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01007366 to the client are :
Davor Ocelice9ed2812017-12-25 17:49:28 +01007367 - all those without "Set-Cookie" header;
Willy Tarreauc55ddce2017-12-21 11:41:38 +01007368 - all those with a return code other than 200, 203, 204, 206, 300, 301,
7369 404, 405, 410, 414, 501, provided that the server has not set a
Davor Ocelice9ed2812017-12-25 17:49:28 +01007370 "Cache-control: public" header field;
Willy Tarreau24ea0bc2017-12-21 11:32:55 +01007371 - all those that result from a request using a method other than GET, HEAD,
7372 OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
Davor Ocelice9ed2812017-12-25 17:49:28 +01007373 public' header field;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007374 - those with a 'Pragma: no-cache' header
7375 - those with a 'Cache-control: private' header
7376 - those with a 'Cache-control: no-store' header
7377 - those with a 'Cache-control: max-age=0' header
7378 - those with a 'Cache-control: s-maxage=0' header
7379 - those with a 'Cache-control: no-cache' header
7380 - those with a 'Cache-control: no-cache="set-cookie"' header
7381 - those with a 'Cache-control: no-cache="set-cookie,' header
7382 (allowing other fields after set-cookie)
7383
7384 If a response doesn't respect these requirements, then it will be blocked
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02007385 just as if it was from an "http-response deny" rule, with an "HTTP 502 bad
7386 gateway". The session state shows "PH--" meaning that the proxy blocked the
7387 response during headers processing. Additionally, an alert will be sent in
7388 the logs so that admins are informed that there's something to be fixed.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007389
7390 Due to the high impact on the application, the application should be tested
7391 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01007392 good practice to always activate it during tests, even if it is not used in
Davor Ocelice9ed2812017-12-25 17:49:28 +01007393 production, as it will report potentially dangerous application behaviors.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007394
7395 If this option has been enabled in a "defaults" section, it can be disabled
7396 in a specific instance by prepending the "no" keyword before it.
7397
7398
7399option clitcpka
7400no option clitcpka
7401 Enable or disable the sending of TCP keepalive packets on the client side
7402 May be used in sections : defaults | frontend | listen | backend
7403 yes | yes | yes | no
7404 Arguments : none
7405
7406 When there is a firewall or any session-aware component between a client and
7407 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01007408 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007409 components decides to expire a session which has remained idle for too long.
7410
7411 Enabling socket-level TCP keep-alives makes the system regularly send packets
7412 to the other end of the connection, leaving it active. The delay between
7413 keep-alive probes is controlled by the system only and depends both on the
7414 operating system and its tuning parameters.
7415
7416 It is important to understand that keep-alive packets are neither emitted nor
7417 received at the application level. It is only the network stacks which sees
7418 them. For this reason, even if one side of the proxy already uses keep-alives
7419 to maintain its connection alive, those keep-alive packets will not be
7420 forwarded to the other side of the proxy.
7421
7422 Please note that this has nothing to do with HTTP keep-alive.
7423
7424 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
7425 client side of a connection, which should help when session expirations are
7426 noticed between HAProxy and a client.
7427
7428 If this option has been enabled in a "defaults" section, it can be disabled
7429 in a specific instance by prepending the "no" keyword before it.
7430
7431 See also : "option srvtcpka", "option tcpka"
7432
7433
Willy Tarreau0ba27502007-12-24 16:55:16 +01007434option contstats
7435 Enable continuous traffic statistics updates
7436 May be used in sections : defaults | frontend | listen | backend
7437 yes | yes | yes | no
7438 Arguments : none
7439
7440 By default, counters used for statistics calculation are incremented
7441 only when a session finishes. It works quite well when serving small
7442 objects, but with big ones (for example large images or archives) or
7443 with A/V streaming, a graph generated from haproxy counters looks like
Willy Tarreaudef0d222016-11-08 22:03:00 +01007444 a hedgehog. With this option enabled counters get incremented frequently
7445 along the session, typically every 5 seconds, which is often enough to
7446 produce clean graphs. Recounting touches a hotpath directly so it is not
7447 not enabled by default, as it can cause a lot of wakeups for very large
7448 session counts and cause a small performance drop.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007449
Christopher Faulet89aed322020-06-02 17:33:56 +02007450option disable-h2-upgrade
7451no option disable-h2-upgrade
7452 Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client
7453 connection.
7454 May be used in sections : defaults | frontend | listen | backend
7455 yes | yes | yes | no
7456 Arguments : none
7457
7458 By default, HAProxy is able to implicitly upgrade an HTTP/1.x client
7459 connection to an HTTP/2 connection if the first request it receives from a
7460 given HTTP connection matches the HTTP/2 connection preface (i.e. the string
7461 "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"). This way, it is possible to support
7462 HTTP/1.x and HTTP/2 clients on a non-SSL connections. This option must be used to
7463 disable the implicit upgrade. Note this implicit upgrade is only supported
7464 for HTTP proxies, thus this option too. Note also it is possible to force the
7465 HTTP/2 on clear connections by specifying "proto h2" on the bind line.
7466
7467 If this option has been enabled in a "defaults" section, it can be disabled
7468 in a specific instance by prepending the "no" keyword before it.
Willy Tarreau0ba27502007-12-24 16:55:16 +01007469
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02007470option dontlog-normal
7471no option dontlog-normal
7472 Enable or disable logging of normal, successful connections
7473 May be used in sections : defaults | frontend | listen | backend
7474 yes | yes | yes | no
7475 Arguments : none
7476
7477 There are large sites dealing with several thousand connections per second
7478 and for which logging is a major pain. Some of them are even forced to turn
7479 logs off and cannot debug production issues. Setting this option ensures that
7480 normal connections, those which experience no error, no timeout, no retry nor
7481 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
7482 mode, the response status code is checked and return codes 5xx will still be
7483 logged.
7484
7485 It is strongly discouraged to use this option as most of the time, the key to
7486 complex issues is in the normal logs which will not be logged here. If you
7487 need to separate logs, see the "log-separate-errors" option instead.
7488
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007489 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02007490 logging.
7491
7492
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007493option dontlognull
7494no option dontlognull
7495 Enable or disable logging of null connections
7496 May be used in sections : defaults | frontend | listen | backend
7497 yes | yes | yes | no
7498 Arguments : none
7499
7500 In certain environments, there are components which will regularly connect to
7501 various systems to ensure that they are still alive. It can be the case from
7502 another load balancer as well as from monitoring systems. By default, even a
7503 simple port probe or scan will produce a log. If those connections pollute
7504 the logs too much, it is possible to enable option "dontlognull" to indicate
7505 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02007506 which typically corresponds to those probes. Note that errors will still be
7507 returned to the client and accounted for in the stats. If this is not what is
7508 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007509
7510 It is generally recommended not to use this option in uncontrolled
Davor Ocelice9ed2812017-12-25 17:49:28 +01007511 environments (e.g. internet), otherwise scans and other malicious activities
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007512 would not be logged.
7513
7514 If this option has been enabled in a "defaults" section, it can be disabled
7515 in a specific instance by prepending the "no" keyword before it.
7516
Willy Tarreau0f228a02015-05-01 15:37:53 +02007517 See also : "log", "http-ignore-probes", "monitor-net", "monitor-uri", and
7518 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007519
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007520
Willy Tarreau87cf5142011-08-19 22:57:24 +02007521option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01007522 Enable insertion of the X-Forwarded-For header to requests sent to servers
7523 May be used in sections : defaults | frontend | listen | backend
7524 yes | yes | yes | yes
7525 Arguments :
7526 <network> is an optional argument used to disable this option for sources
7527 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02007528 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01007529 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01007530
7531 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
7532 their client address. This is sometimes annoying when the client's IP address
7533 is expected in server logs. To solve this problem, the well-known HTTP header
7534 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
7535 This header contains a value representing the client's IP address. Since this
7536 header is always appended at the end of the existing header list, the server
7537 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02007538 the server's manual to find how to enable use of this standard header. Note
7539 that only the last occurrence of the header must be used, since it is really
7540 possible that the client has already brought one.
7541
Willy Tarreaud72758d2010-01-12 10:42:19 +01007542 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02007543 the default "X-Forwarded-For". This can be useful where you might already
Davor Ocelice9ed2812017-12-25 17:49:28 +01007544 have a "X-Forwarded-For" header from a different application (e.g. stunnel),
Willy Tarreaud72758d2010-01-12 10:42:19 +01007545 and you need preserve it. Also if your backend server doesn't use the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007546 "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
Ross Westaf72a1d2008-08-03 10:51:45 +02007547 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01007548
7549 Sometimes, a same HAProxy instance may be shared between a direct client
7550 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
7551 used to decrypt HTTPS traffic). It is possible to disable the addition of the
7552 header for a known source address or network by adding the "except" keyword
7553 followed by the network address. In this case, any source IP matching the
7554 network will not cause an addition of this header. Most common uses are with
7555 private networks or 127.0.0.1.
7556
Willy Tarreau87cf5142011-08-19 22:57:24 +02007557 Alternatively, the keyword "if-none" states that the header will only be
7558 added if it is not present. This should only be used in perfectly trusted
7559 environment, as this might cause a security issue if headers reaching haproxy
7560 are under the control of the end-user.
7561
Willy Tarreauc27debf2008-01-06 08:57:02 +01007562 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02007563 least one of them uses it, the header will be added. Note that the backend's
7564 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02007565 both are defined. In the case of the "if-none" argument, if at least one of
7566 the frontend or the backend does not specify it, it wants the addition to be
7567 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01007568
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02007569 Example :
Willy Tarreauc27debf2008-01-06 08:57:02 +01007570 # Public HTTP address also used by stunnel on the same machine
7571 frontend www
7572 mode http
7573 option forwardfor except 127.0.0.1 # stunnel already adds the header
7574
Ross Westaf72a1d2008-08-03 10:51:45 +02007575 # Those servers want the IP Address in X-Client
7576 backend www
7577 mode http
7578 option forwardfor header X-Client
7579
Willy Tarreau87cf5142011-08-19 22:57:24 +02007580 See also : "option httpclose", "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02007581 "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01007582
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007583
Christopher Faulet98fbe952019-07-22 16:18:24 +02007584option h1-case-adjust-bogus-client
7585no option h1-case-adjust-bogus-client
7586 Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
7587 May be used in sections : defaults | frontend | listen | backend
7588 yes | yes | yes | no
7589 Arguments : none
7590
7591 There is no standard case for header names because, as stated in RFC7230,
7592 they are case-insensitive. So applications must handle them in a case-
7593 insensitive manner. But some bogus applications violate the standards and
7594 erroneously rely on the cases most commonly used by browsers. This problem
7595 becomes critical with HTTP/2 because all header names must be exchanged in
7596 lower case, and HAProxy follows the same convention. All header names are
7597 sent in lower case to clients and servers, regardless of the HTTP version.
7598
7599 When HAProxy receives an HTTP/1 response, its header names are converted to
7600 lower case and manipulated and sent this way to the clients. If a client is
7601 known to violate the HTTP standards and to fail to process a response coming
7602 from HAProxy, it is possible to transform the lower case header names to a
7603 different format when the response is formatted and sent to the client, by
7604 enabling this option and specifying the list of headers to be reformatted
7605 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
7606 must only be a temporary workaround for the time it takes the client to be
7607 fixed, because clients which require such workarounds might be vulnerable to
7608 content smuggling attacks and must absolutely be fixed.
7609
7610 Please note that this option will not affect standards-compliant clients.
7611
7612 If this option has been enabled in a "defaults" section, it can be disabled
7613 in a specific instance by prepending the "no" keyword before it.
7614
7615 See also: "option h1-case-adjust-bogus-server", "h1-case-adjust",
7616 "h1-case-adjust-file".
7617
7618
7619option h1-case-adjust-bogus-server
7620no option h1-case-adjust-bogus-server
7621 Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
7622 May be used in sections : defaults | frontend | listen | backend
7623 yes | no | yes | yes
7624 Arguments : none
7625
7626 There is no standard case for header names because, as stated in RFC7230,
7627 they are case-insensitive. So applications must handle them in a case-
7628 insensitive manner. But some bogus applications violate the standards and
7629 erroneously rely on the cases most commonly used by browsers. This problem
7630 becomes critical with HTTP/2 because all header names must be exchanged in
7631 lower case, and HAProxy follows the same convention. All header names are
7632 sent in lower case to clients and servers, regardless of the HTTP version.
7633
7634 When HAProxy receives an HTTP/1 request, its header names are converted to
7635 lower case and manipulated and sent this way to the servers. If a server is
7636 known to violate the HTTP standards and to fail to process a request coming
7637 from HAProxy, it is possible to transform the lower case header names to a
7638 different format when the request is formatted and sent to the server, by
7639 enabling this option and specifying the list of headers to be reformatted
7640 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
7641 must only be a temporary workaround for the time it takes the server to be
7642 fixed, because servers which require such workarounds might be vulnerable to
7643 content smuggling attacks and must absolutely be fixed.
7644
7645 Please note that this option will not affect standards-compliant servers.
7646
7647 If this option has been enabled in a "defaults" section, it can be disabled
7648 in a specific instance by prepending the "no" keyword before it.
7649
7650 See also: "option h1-case-adjust-bogus-client", "h1-case-adjust",
7651 "h1-case-adjust-file".
7652
7653
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02007654option http-buffer-request
7655no option http-buffer-request
7656 Enable or disable waiting for whole HTTP request body before proceeding
7657 May be used in sections : defaults | frontend | listen | backend
7658 yes | yes | yes | yes
7659 Arguments : none
7660
7661 It is sometimes desirable to wait for the body of an HTTP request before
7662 taking a decision. This is what is being done by "balance url_param" for
7663 example. The first use case is to buffer requests from slow clients before
7664 connecting to the server. Another use case consists in taking the routing
7665 decision based on the request body's contents. This option placed in a
7666 frontend or backend forces the HTTP processing to wait until either the whole
Christopher Faulet6db8a2e2019-11-19 16:27:25 +01007667 body is received or the request buffer is full. It can have undesired side
7668 effects with some applications abusing HTTP by expecting unbuffered
7669 transmissions between the frontend and the backend, so this should definitely
7670 not be used by default.
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02007671
Baptiste Assmanneccdf432015-10-28 13:49:01 +01007672 See also : "option http-no-delay", "timeout http-request"
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02007673
7674
Willy Tarreau0f228a02015-05-01 15:37:53 +02007675option http-ignore-probes
7676no option http-ignore-probes
7677 Enable or disable logging of null connections and request timeouts
7678 May be used in sections : defaults | frontend | listen | backend
7679 yes | yes | yes | no
7680 Arguments : none
7681
7682 Recently some browsers started to implement a "pre-connect" feature
7683 consisting in speculatively connecting to some recently visited web sites
7684 just in case the user would like to visit them. This results in many
7685 connections being established to web sites, which end up in 408 Request
7686 Timeout if the timeout strikes first, or 400 Bad Request when the browser
7687 decides to close them first. These ones pollute the log and feed the error
7688 counters. There was already "option dontlognull" but it's insufficient in
7689 this case. Instead, this option does the following things :
7690 - prevent any 400/408 message from being sent to the client if nothing
Davor Ocelice9ed2812017-12-25 17:49:28 +01007691 was received over a connection before it was closed;
7692 - prevent any log from being emitted in this situation;
Willy Tarreau0f228a02015-05-01 15:37:53 +02007693 - prevent any error counter from being incremented
7694
7695 That way the empty connection is silently ignored. Note that it is better
7696 not to use this unless it is clear that it is needed, because it will hide
7697 real problems. The most common reason for not receiving a request and seeing
7698 a 408 is due to an MTU inconsistency between the client and an intermediary
7699 element such as a VPN, which blocks too large packets. These issues are
7700 generally seen with POST requests as well as GET with large cookies. The logs
7701 are often the only way to detect them.
7702
7703 If this option has been enabled in a "defaults" section, it can be disabled
7704 in a specific instance by prepending the "no" keyword before it.
7705
7706 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
7707
7708
Willy Tarreau16bfb022010-01-16 19:48:41 +01007709option http-keep-alive
7710no option http-keep-alive
7711 Enable or disable HTTP keep-alive from client to server
7712 May be used in sections : defaults | frontend | listen | backend
7713 yes | yes | yes | yes
7714 Arguments : none
7715
Willy Tarreau70dffda2014-01-30 03:07:23 +01007716 By default HAProxy operates in keep-alive mode with regards to persistent
7717 connections: for each connection it processes each request and response, and
Christopher Faulet315b39c2018-09-21 16:26:19 +02007718 leaves the connection idle on both sides between the end of a response and
7719 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02007720 as "option http-server-close" or "option httpclose". This option allows to
7721 set back the keep-alive mode, which can be useful when another mode was used
7722 in a defaults section.
Willy Tarreau70dffda2014-01-30 03:07:23 +01007723
7724 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
7725 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01007726 network) and the fastest session reuse on the server side at the expense
7727 of maintaining idle connections to the servers. In general, it is possible
7728 with this option to achieve approximately twice the request rate that the
7729 "http-server-close" option achieves on small objects. There are mainly two
7730 situations where this option may be useful :
7731
7732 - when the server is non-HTTP compliant and authenticates the connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01007733 instead of requests (e.g. NTLM authentication)
Willy Tarreau16bfb022010-01-16 19:48:41 +01007734
7735 - when the cost of establishing the connection to the server is significant
7736 compared to the cost of retrieving the associated object from the server.
7737
7738 This last case can happen when the server is a fast static server of cache.
7739 In this case, the server will need to be properly tuned to support high enough
7740 connection counts because connections will last until the client sends another
7741 request.
7742
7743 If the client request has to go to another backend or another server due to
7744 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01007745 immediately be closed and a new one re-opened. Option "prefer-last-server" is
7746 available to try optimize server selection so that if the server currently
7747 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01007748
Willy Tarreau16bfb022010-01-16 19:48:41 +01007749 At the moment, logs will not indicate whether requests came from the same
7750 session or not. The accept date reported in the logs corresponds to the end
7751 of the previous request, and the request time corresponds to the time spent
7752 waiting for a new request. The keep-alive request time is still bound to the
7753 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
7754 not set.
7755
Christopher Faulet159e6672019-07-16 15:09:52 +02007756 This option disables and replaces any previous "option httpclose" or "option
7757 http-server-close". When backend and frontend options differ, all of these 4
7758 options have precedence over "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01007759
Christopher Faulet315b39c2018-09-21 16:26:19 +02007760 See also : "option httpclose",, "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01007761 "option prefer-last-server", "option http-pretend-keepalive",
Frédéric Lécaille93d33162019-03-06 09:35:59 +01007762 and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01007763
7764
Willy Tarreau96e31212011-05-30 18:10:30 +02007765option http-no-delay
7766no option http-no-delay
7767 Instruct the system to favor low interactive delays over performance in HTTP
7768 May be used in sections : defaults | frontend | listen | backend
7769 yes | yes | yes | yes
7770 Arguments : none
7771
7772 In HTTP, each payload is unidirectional and has no notion of interactivity.
7773 Any agent is expected to queue data somewhat for a reasonably low delay.
7774 There are some very rare server-to-server applications that abuse the HTTP
7775 protocol and expect the payload phase to be highly interactive, with many
7776 interleaved data chunks in both directions within a single request. This is
7777 absolutely not supported by the HTTP specification and will not work across
7778 most proxies or servers. When such applications attempt to do this through
7779 haproxy, it works but they will experience high delays due to the network
7780 optimizations which favor performance by instructing the system to wait for
7781 enough data to be available in order to only send full packets. Typical
7782 delays are around 200 ms per round trip. Note that this only happens with
7783 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
7784 affected.
7785
7786 When "option http-no-delay" is present in either the frontend or the backend
7787 used by a connection, all such optimizations will be disabled in order to
7788 make the exchanges as fast as possible. Of course this offers no guarantee on
7789 the functionality, as it may break at any other place. But if it works via
7790 HAProxy, it will work as fast as possible. This option should never be used
7791 by default, and should never be used at all unless such a buggy application
7792 is discovered. The impact of using this option is an increase of bandwidth
7793 usage and CPU usage, which may significantly lower performance in high
7794 latency environments.
7795
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02007796 See also : "option http-buffer-request"
7797
Willy Tarreau96e31212011-05-30 18:10:30 +02007798
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007799option http-pretend-keepalive
7800no option http-pretend-keepalive
7801 Define whether haproxy will announce keepalive to the server or not
7802 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet98db9762018-09-21 10:25:19 +02007803 yes | no | yes | yes
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007804 Arguments : none
7805
Christopher Faulet315b39c2018-09-21 16:26:19 +02007806 When running with "option http-server-close" or "option httpclose", haproxy
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007807 adds a "Connection: close" header to the request forwarded to the server.
7808 Unfortunately, when some servers see this header, they automatically refrain
7809 from using the chunked encoding for responses of unknown length, while this
7810 is totally unrelated. The immediate effect is that this prevents haproxy from
7811 maintaining the client connection alive. A second effect is that a client or
7812 a cache could receive an incomplete response without being aware of it, and
7813 consider the response complete.
7814
7815 By setting "option http-pretend-keepalive", haproxy will make the server
7816 believe it will keep the connection alive. The server will then not fall back
7817 to the abnormal undesired above. When haproxy gets the whole response, it
7818 will close the connection with the server just as it would do with the
Christopher Faulet315b39c2018-09-21 16:26:19 +02007819 "option httpclose". That way the client gets a normal response and the
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007820 connection is correctly closed on the server side.
7821
7822 It is recommended not to enable this option by default, because most servers
7823 will more efficiently close the connection themselves after the last packet,
7824 and release its buffers slightly earlier. Also, the added packet on the
7825 network could slightly reduce the overall peak performance. However it is
7826 worth noting that when this option is enabled, haproxy will have slightly
7827 less work to do. So if haproxy is the bottleneck on the whole architecture,
7828 enabling this option might save a few CPU cycles.
7829
Christopher Faulet98db9762018-09-21 10:25:19 +02007830 This option may be set in backend and listen sections. Using it in a frontend
7831 section will be ignored and a warning will be reported during startup. It is
7832 a backend related option, so there is no real reason to set it on a
7833 frontend. This option may be combined with "option httpclose", which will
7834 cause keepalive to be announced to the server and close to be announced to
7835 the client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007836
7837 If this option has been enabled in a "defaults" section, it can be disabled
7838 in a specific instance by prepending the "no" keyword before it.
7839
Christopher Faulet315b39c2018-09-21 16:26:19 +02007840 See also : "option httpclose", "option http-server-close", and
Willy Tarreau16bfb022010-01-16 19:48:41 +01007841 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02007842
Willy Tarreauc27debf2008-01-06 08:57:02 +01007843
Willy Tarreaub608feb2010-01-02 22:47:18 +01007844option http-server-close
7845no option http-server-close
7846 Enable or disable HTTP connection closing on the server side
7847 May be used in sections : defaults | frontend | listen | backend
7848 yes | yes | yes | yes
7849 Arguments : none
7850
Willy Tarreau70dffda2014-01-30 03:07:23 +01007851 By default HAProxy operates in keep-alive mode with regards to persistent
7852 connections: for each connection it processes each request and response, and
7853 leaves the connection idle on both sides between the end of a response and
7854 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02007855 as "option http-server-close" or "option httpclose". Setting "option
7856 http-server-close" enables HTTP connection-close mode on the server side
7857 while keeping the ability to support HTTP keep-alive and pipelining on the
7858 client side. This provides the lowest latency on the client side (slow
7859 network) and the fastest session reuse on the server side to save server
7860 resources, similarly to "option httpclose". It also permits non-keepalive
7861 capable servers to be served in keep-alive mode to the clients if they
7862 conform to the requirements of RFC7230. Please note that some servers do not
7863 always conform to those requirements when they see "Connection: close" in the
7864 request. The effect will be that keep-alive will never be used. A workaround
7865 consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01007866
7867 At the moment, logs will not indicate whether requests came from the same
7868 session or not. The accept date reported in the logs corresponds to the end
7869 of the previous request, and the request time corresponds to the time spent
7870 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01007871 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
7872 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01007873
7874 This option may be set both in a frontend and in a backend. It is enabled if
7875 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet159e6672019-07-16 15:09:52 +02007876 It disables and replaces any previous "option httpclose" or "option
7877 http-keep-alive". Please check section 4 ("Proxies") to see how this option
7878 combines with others when frontend and backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01007879
7880 If this option has been enabled in a "defaults" section, it can be disabled
7881 in a specific instance by prepending the "no" keyword before it.
7882
Christopher Faulet315b39c2018-09-21 16:26:19 +02007883 See also : "option httpclose", "option http-pretend-keepalive",
7884 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01007885
Willy Tarreau88d349d2010-01-25 12:15:43 +01007886option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01007887no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01007888 Make use of non-standard Proxy-Connection header instead of Connection
7889 May be used in sections : defaults | frontend | listen | backend
7890 yes | yes | yes | no
7891 Arguments : none
7892
Lukas Tribus23953682017-04-28 13:24:30 +00007893 While RFC7230 explicitly states that HTTP/1.1 agents must use the
Willy Tarreau88d349d2010-01-25 12:15:43 +01007894 Connection header to indicate their wish of persistent or non-persistent
7895 connections, both browsers and proxies ignore this header for proxied
7896 connections and make use of the undocumented, non-standard Proxy-Connection
7897 header instead. The issue begins when trying to put a load balancer between
7898 browsers and such proxies, because there will be a difference between what
7899 haproxy understands and what the client and the proxy agree on.
7900
7901 By setting this option in a frontend, haproxy can automatically switch to use
7902 that non-standard header if it sees proxied requests. A proxied request is
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01007903 defined here as one where the URI begins with neither a '/' nor a '*'. This
7904 is incompatible with the HTTP tunnel mode. Note that this option can only be
7905 specified in a frontend and will affect the request along its whole life.
Willy Tarreau88d349d2010-01-25 12:15:43 +01007906
Willy Tarreau844a7e72010-01-31 21:46:18 +01007907 Also, when this option is set, a request which requires authentication will
7908 automatically switch to use proxy authentication headers if it is itself a
7909 proxied request. That makes it possible to check or enforce authentication in
7910 front of an existing proxy.
7911
Willy Tarreau88d349d2010-01-25 12:15:43 +01007912 This option should normally never be used, except in front of a proxy.
7913
Christopher Faulet315b39c2018-09-21 16:26:19 +02007914 See also : "option httpclose", and "option http-server-close".
Willy Tarreau88d349d2010-01-25 12:15:43 +01007915
Willy Tarreaud63335a2010-02-26 12:56:52 +01007916option httpchk
7917option httpchk <uri>
7918option httpchk <method> <uri>
7919option httpchk <method> <uri> <version>
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02007920 Enables HTTP protocol to check on the servers health
Willy Tarreaud63335a2010-02-26 12:56:52 +01007921 May be used in sections : defaults | frontend | listen | backend
7922 yes | no | yes | yes
7923 Arguments :
7924 <method> is the optional HTTP method used with the requests. When not set,
7925 the "OPTIONS" method is used, as it generally requires low server
7926 processing and is easy to filter out from the logs. Any method
7927 may be used, though it is not recommended to invent non-standard
7928 ones.
7929
7930 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
7931 which is accessible by default on almost any server, but may be
7932 changed to any other URI. Query strings are permitted.
7933
7934 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
7935 but some servers might behave incorrectly in HTTP 1.0, so turning
7936 it to HTTP/1.1 may sometimes help. Note that the Host field is
Christopher Faulet8acb1282020-04-09 08:44:06 +02007937 mandatory in HTTP/1.1, use "http-check send" directive to add it.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007938
7939 By default, server health checks only consist in trying to establish a TCP
7940 connection. When "option httpchk" is specified, a complete HTTP request is
7941 sent once the TCP connection is established, and responses 2xx and 3xx are
7942 considered valid, while all other ones indicate a server failure, including
7943 the lack of any response.
7944
Christopher Faulete5870d82020-04-15 11:32:03 +02007945 Combined with "http-check" directives, it is possible to customize the
7946 request sent during the HTTP health checks or the matching rules on the
7947 response. It is also possible to configure a send/expect sequence, just like
7948 with the directive "tcp-check" for TCP health checks.
7949
7950 The server configuration is used by default to open connections to perform
7951 HTTP health checks. By it is also possible to overwrite server parameters
7952 using "http-check connect" rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007953
Christopher Faulete5870d82020-04-15 11:32:03 +02007954 "httpchk" option does not necessarily require an HTTP backend, it also works
7955 with plain TCP backends. This is particularly useful to check simple scripts
Christopher Faulet14cd3162020-04-16 14:50:06 +02007956 bound to some dedicated ports using the inetd daemon. However, it will always
Daniel Corbett67a82712020-07-06 23:01:19 -04007957 internally relies on an HTX multiplexer. Thus, it means the request
Christopher Faulet14cd3162020-04-16 14:50:06 +02007958 formatting and the response parsing will be strict.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007959
Christopher Faulet8acb1282020-04-09 08:44:06 +02007960 Note : For a while, there was no way to add headers or body in the request
7961 used for HTTP health checks. So a workaround was to hide it at the end
7962 of the version string with a "\r\n" after the version. It is now
7963 deprecated. The directive "http-check send" must be used instead.
7964
Willy Tarreaud63335a2010-02-26 12:56:52 +01007965 Examples :
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02007966 # Relay HTTPS traffic to Apache instance and check service availability
7967 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
7968 backend https_relay
7969 mode tcp
7970 option httpchk OPTIONS * HTTP/1.1
7971 http-check send hdr Host www
7972 server apache1 192.168.1.1:443 check port 80
Willy Tarreaud63335a2010-02-26 12:56:52 +01007973
Simon Hormanafc47ee2013-11-25 10:46:35 +09007974 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
7975 "option pgsql-check", "http-check" and the "check", "port" and
7976 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01007977
7978
Willy Tarreauc27debf2008-01-06 08:57:02 +01007979option httpclose
7980no option httpclose
Christopher Faulet315b39c2018-09-21 16:26:19 +02007981 Enable or disable HTTP connection closing
Willy Tarreauc27debf2008-01-06 08:57:02 +01007982 May be used in sections : defaults | frontend | listen | backend
7983 yes | yes | yes | yes
7984 Arguments : none
7985
Willy Tarreau70dffda2014-01-30 03:07:23 +01007986 By default HAProxy operates in keep-alive mode with regards to persistent
7987 connections: for each connection it processes each request and response, and
7988 leaves the connection idle on both sides between the end of a response and
7989 the start of a new request. This mode may be changed by several options such
Christopher Faulet159e6672019-07-16 15:09:52 +02007990 as "option http-server-close" or "option httpclose".
Willy Tarreau70dffda2014-01-30 03:07:23 +01007991
Christopher Faulet315b39c2018-09-21 16:26:19 +02007992 If "option httpclose" is set, HAProxy will close connections with the server
7993 and the client as soon as the request and the response are received. It will
John Roeslerfb2fce12019-07-10 15:45:51 -05007994 also check if a "Connection: close" header is already set in each direction,
Christopher Faulet315b39c2018-09-21 16:26:19 +02007995 and will add one if missing. Any "Connection" header different from "close"
7996 will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01007997
Christopher Faulet315b39c2018-09-21 16:26:19 +02007998 This option may also be combined with "option http-pretend-keepalive", which
7999 will disable sending of the "Connection: close" header, but will still cause
8000 the connection to be closed once the whole response is received.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008001
8002 This option may be set both in a frontend and in a backend. It is enabled if
8003 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet159e6672019-07-16 15:09:52 +02008004 It disables and replaces any previous "option http-server-close" or "option
8005 http-keep-alive". Please check section 4 ("Proxies") to see how this option
8006 combines with others when frontend and backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008007
8008 If this option has been enabled in a "defaults" section, it can be disabled
8009 in a specific instance by prepending the "no" keyword before it.
8010
Christopher Faulet315b39c2018-09-21 16:26:19 +02008011 See also : "option http-server-close" and "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01008012
8013
Emeric Brun3a058f32009-06-30 18:26:00 +02008014option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01008015 Enable logging of HTTP request, session state and timers
8016 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01008017 yes | yes | yes | no
Emeric Brun3a058f32009-06-30 18:26:00 +02008018 Arguments :
8019 clf if the "clf" argument is added, then the output format will be
8020 the CLF format instead of HAProxy's default HTTP format. You can
8021 use this when you need to feed HAProxy's logs through a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01008022 log analyzer which only support the CLF format and which is not
Emeric Brun3a058f32009-06-30 18:26:00 +02008023 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008024
8025 By default, the log output format is very poor, as it only contains the
8026 source and destination addresses, and the instance name. By specifying
8027 "option httplog", each log line turns into a much richer format including,
8028 but not limited to, the HTTP request, the connection timers, the session
8029 status, the connections numbers, the captured headers and cookies, the
8030 frontend, backend and server name, and of course the source address and
8031 ports.
8032
PiBa-NLbd556bf2014-12-11 21:31:54 +01008033 Specifying only "option httplog" will automatically clear the 'clf' mode
8034 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02008035
Guillaume de Lafond29f45602017-03-31 19:52:15 +02008036 "option httplog" overrides any previous "log-format" directive.
8037
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008038 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008039
Willy Tarreau55165fe2009-05-10 12:02:55 +02008040
8041option http_proxy
8042no option http_proxy
8043 Enable or disable plain HTTP proxy mode
8044 May be used in sections : defaults | frontend | listen | backend
8045 yes | yes | yes | yes
8046 Arguments : none
8047
8048 It sometimes happens that people need a pure HTTP proxy which understands
8049 basic proxy requests without caching nor any fancy feature. In this case,
8050 it may be worth setting up an HAProxy instance with the "option http_proxy"
8051 set. In this mode, no server is declared, and the connection is forwarded to
8052 the IP address and port found in the URL after the "http://" scheme.
8053
8054 No host address resolution is performed, so this only works when pure IP
8055 addresses are passed. Since this option's usage perimeter is rather limited,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01008056 it will probably be used only by experts who know they need exactly it. This
8057 is incompatible with the HTTP tunnel mode.
Willy Tarreau55165fe2009-05-10 12:02:55 +02008058
8059 If this option has been enabled in a "defaults" section, it can be disabled
8060 in a specific instance by prepending the "no" keyword before it.
8061
8062 Example :
8063 # this backend understands HTTP proxy requests and forwards them directly.
8064 backend direct_forward
8065 option httpclose
8066 option http_proxy
8067
8068 See also : "option httpclose"
8069
Willy Tarreau211ad242009-10-03 21:45:07 +02008070
Jamie Gloudon801a0a32012-08-25 00:18:33 -04008071option independent-streams
8072no option independent-streams
8073 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02008074 May be used in sections : defaults | frontend | listen | backend
8075 yes | yes | yes | yes
8076 Arguments : none
8077
8078 By default, when data is sent over a socket, both the write timeout and the
8079 read timeout for that socket are refreshed, because we consider that there is
8080 activity on that socket, and we have no other means of guessing if we should
8081 receive data or not.
8082
Davor Ocelice9ed2812017-12-25 17:49:28 +01008083 While this default behavior is desirable for almost all applications, there
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02008084 exists a situation where it is desirable to disable it, and only refresh the
8085 read timeout if there are incoming data. This happens on sessions with large
8086 timeouts and low amounts of exchanged data such as telnet session. If the
8087 server suddenly disappears, the output data accumulates in the system's
8088 socket buffers, both timeouts are correctly refreshed, and there is no way
8089 to know the server does not receive them, so we don't timeout. However, when
8090 the underlying protocol always echoes sent data, it would be enough by itself
8091 to detect the issue using the read timeout. Note that this problem does not
8092 happen with more verbose protocols because data won't accumulate long in the
8093 socket buffers.
8094
8095 When this option is set on the frontend, it will disable read timeout updates
8096 on data sent to the client. There probably is little use of this case. When
8097 the option is set on the backend, it will disable read timeout updates on
8098 data sent to the server. Doing so will typically break large HTTP posts from
8099 slow lines, so use it with caution.
8100
Willy Tarreauce887fd2012-05-12 12:50:00 +02008101 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02008102
8103
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02008104option ldap-check
8105 Use LDAPv3 health checks for server testing
8106 May be used in sections : defaults | frontend | listen | backend
8107 yes | no | yes | yes
8108 Arguments : none
8109
8110 It is possible to test that the server correctly talks LDAPv3 instead of just
8111 testing that it accepts the TCP connection. When this option is set, an
8112 LDAPv3 anonymous simple bind message is sent to the server, and the response
8113 is analyzed to find an LDAPv3 bind response message.
8114
8115 The server is considered valid only when the LDAP response contains success
8116 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
8117
8118 Logging of bind requests is server dependent see your documentation how to
8119 configure it.
8120
8121 Example :
8122 option ldap-check
8123
8124 See also : "option httpchk"
8125
8126
Simon Horman98637e52014-06-20 12:30:16 +09008127option external-check
8128 Use external processes for server health checks
8129 May be used in sections : defaults | frontend | listen | backend
8130 yes | no | yes | yes
8131
8132 It is possible to test the health of a server using an external command.
8133 This is achieved by running the executable set using "external-check
8134 command".
8135
8136 Requires the "external-check" global to be set.
8137
8138 See also : "external-check", "external-check command", "external-check path"
8139
8140
Willy Tarreau211ad242009-10-03 21:45:07 +02008141option log-health-checks
8142no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02008143 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02008144 May be used in sections : defaults | frontend | listen | backend
8145 yes | no | yes | yes
8146 Arguments : none
8147
Willy Tarreaubef1b322014-05-13 21:01:39 +02008148 By default, failed health check are logged if server is UP and successful
8149 health checks are logged if server is DOWN, so the amount of additional
8150 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02008151
Willy Tarreaubef1b322014-05-13 21:01:39 +02008152 When this option is enabled, any change of the health check status or to
8153 the server's health will be logged, so that it becomes possible to know
8154 that a server was failing occasional checks before crashing, or exactly when
8155 it failed to respond a valid HTTP status, then when the port started to
8156 reject connections, then when the server stopped responding at all.
8157
Davor Ocelice9ed2812017-12-25 17:49:28 +01008158 Note that status changes not caused by health checks (e.g. enable/disable on
Willy Tarreaubef1b322014-05-13 21:01:39 +02008159 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02008160
Willy Tarreaubef1b322014-05-13 21:01:39 +02008161 See also: "option httpchk", "option ldap-check", "option mysql-check",
8162 "option pgsql-check", "option redis-check", "option smtpchk",
8163 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02008164
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008165
8166option log-separate-errors
8167no option log-separate-errors
8168 Change log level for non-completely successful connections
8169 May be used in sections : defaults | frontend | listen | backend
8170 yes | yes | yes | no
8171 Arguments : none
8172
8173 Sometimes looking for errors in logs is not easy. This option makes haproxy
8174 raise the level of logs containing potentially interesting information such
8175 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
8176 level changes from "info" to "err". This makes it possible to log them
8177 separately to a different file with most syslog daemons. Be careful not to
8178 remove them from the original file, otherwise you would lose ordering which
8179 provides very important information.
8180
8181 Using this option, large sites dealing with several thousand connections per
8182 second may log normal traffic to a rotating buffer and only archive smaller
8183 error logs.
8184
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008185 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02008186 logging.
8187
Willy Tarreauc27debf2008-01-06 08:57:02 +01008188
8189option logasap
8190no option logasap
Jerome Magnin95fb57b2020-04-23 19:01:17 +02008191 Enable or disable early logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008192 May be used in sections : defaults | frontend | listen | backend
8193 yes | yes | yes | no
8194 Arguments : none
8195
Jerome Magnin95fb57b2020-04-23 19:01:17 +02008196 By default, logs are emitted when all the log format variables and sample
8197 fetches used in the definition of the log-format string return a value, or
8198 when the session is terminated. This allows the built in log-format strings
8199 to account for the transfer time, or the number of bytes in log messages.
8200
8201 When handling long lived connections such as large file transfers or RDP,
8202 it may take a while for the request or connection to appear in the logs.
8203 Using "option logasap", the log message is created as soon as the server
8204 connection is established in mode tcp, or as soon as the server sends the
8205 complete headers in mode http. Missing information in the logs will be the
Ilya Shipitsin4329a9a2020-05-05 21:17:10 +05008206 total number of bytes which will only indicate the amount of data transferred
Jerome Magnin95fb57b2020-04-23 19:01:17 +02008207 before the message was created and the total time which will not take the
8208 remainder of the connection life or transfer time into account. For the case
8209 of HTTP, it is good practice to capture the Content-Length response header
8210 so that the logs at least indicate how many bytes are expected to be
Ilya Shipitsin4329a9a2020-05-05 21:17:10 +05008211 transferred.
Willy Tarreauc27debf2008-01-06 08:57:02 +01008212
Willy Tarreaucc6c8912009-02-22 10:53:55 +01008213 Examples :
8214 listen http_proxy 0.0.0.0:80
8215 mode http
8216 option httplog
8217 option logasap
8218 log 192.168.2.200 local3
8219
8220 >>> Feb 6 12:14:14 localhost \
8221 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
8222 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
8223 "GET /image.iso HTTP/1.0"
8224
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008225 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01008226 logging.
8227
8228
Christopher Faulet62f79fe2020-05-18 18:13:03 +02008229option mysql-check [ user <username> [ { post-41 | pre-41 } ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02008230 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01008231 May be used in sections : defaults | frontend | listen | backend
8232 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02008233 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02008234 <username> This is the username which will be used when connecting to MySQL
8235 server.
Christopher Faulet62f79fe2020-05-18 18:13:03 +02008236 post-41 Send post v4.1 client compatible checks (the default)
8237 pre-41 Send pre v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02008238
8239 If you specify a username, the check consists of sending two MySQL packet,
8240 one Client Authentication packet, and one QUIT packet, to correctly close
Davor Ocelice9ed2812017-12-25 17:49:28 +01008241 MySQL session. We then parse the MySQL Handshake Initialization packet and/or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02008242 Error packet. It is a basic but useful test which does not produce error nor
8243 aborted connect on the server. However, it requires adding an authorization
8244 in the MySQL table, like this :
8245
8246 USE mysql;
8247 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
8248 FLUSH PRIVILEGES;
8249
8250 If you don't specify a username (it is deprecated and not recommended), the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008251 check only consists in parsing the Mysql Handshake Initialization packet or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02008252 Error packet, we don't send anything in this mode. It was reported that it
8253 can generate lockout if check is too frequent and/or if there is not enough
8254 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
8255 value as if a connection is established successfully within fewer than MySQL
8256 "max_connect_errors" attempts after a previous connection was interrupted,
8257 the error count for the host is cleared to zero. If HAProxy's server get
8258 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
8259
8260 Remember that this does not check database presence nor database consistency.
8261 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01008262
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02008263 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01008264
8265 Most often, an incoming MySQL server needs to see the client's IP address for
8266 various purposes, including IP privilege matching and connection logging.
8267 When possible, it is often wise to masquerade the client's IP address when
8268 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02008269 which requires the transparent proxy feature to be compiled in, and the MySQL
8270 server to route the client via the machine hosting haproxy.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01008271
8272 See also: "option httpchk"
8273
8274
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008275option nolinger
8276no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008277 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008278 May be used in sections: defaults | frontend | listen | backend
8279 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008280 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008281
Davor Ocelice9ed2812017-12-25 17:49:28 +01008282 When clients or servers abort connections in a dirty way (e.g. they are
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008283 physically disconnected), the session timeouts triggers and the session is
8284 closed. But it will remain in FIN_WAIT1 state for some time in the system,
8285 using some resources and possibly limiting the ability to establish newer
8286 connections.
8287
8288 When this happens, it is possible to activate "option nolinger" which forces
8289 the system to immediately remove any socket's pending data on close. Thus,
8290 the session is instantly purged from the system's tables. This usually has
8291 side effects such as increased number of TCP resets due to old retransmits
8292 getting immediately rejected. Some firewalls may sometimes complain about
8293 this too.
8294
8295 For this reason, it is not recommended to use this option when not absolutely
8296 needed. You know that you need it when you have thousands of FIN_WAIT1
8297 sessions on your system (TIME_WAIT ones do not count).
8298
8299 This option may be used both on frontends and backends, depending on the side
8300 where it is required. Use it on the frontend for clients, and on the backend
8301 for servers.
8302
8303 If this option has been enabled in a "defaults" section, it can be disabled
8304 in a specific instance by prepending the "no" keyword before it.
8305
8306
Willy Tarreau55165fe2009-05-10 12:02:55 +02008307option originalto [ except <network> ] [ header <name> ]
8308 Enable insertion of the X-Original-To header to requests sent to servers
8309 May be used in sections : defaults | frontend | listen | backend
8310 yes | yes | yes | yes
8311 Arguments :
8312 <network> is an optional argument used to disable this option for sources
8313 matching <network>
8314 <name> an optional argument to specify a different "X-Original-To"
8315 header name.
8316
8317 Since HAProxy can work in transparent mode, every request from a client can
8318 be redirected to the proxy and HAProxy itself can proxy every request to a
8319 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
8320 be lost. This is annoying when you want access rules based on destination ip
8321 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
8322 added by HAProxy to all requests sent to the server. This header contains a
8323 value representing the original destination IP address. Since this must be
8324 configured to always use the last occurrence of this header only. Note that
8325 only the last occurrence of the header must be used, since it is really
8326 possible that the client has already brought one.
8327
8328 The keyword "header" may be used to supply a different header name to replace
8329 the default "X-Original-To". This can be useful where you might already
8330 have a "X-Original-To" header from a different application, and you need
8331 preserve it. Also if your backend server doesn't use the "X-Original-To"
8332 header and requires different one.
8333
8334 Sometimes, a same HAProxy instance may be shared between a direct client
8335 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
8336 used to decrypt HTTPS traffic). It is possible to disable the addition of the
8337 header for a known source address or network by adding the "except" keyword
8338 followed by the network address. In this case, any source IP matching the
8339 network will not cause an addition of this header. Most common uses are with
8340 private networks or 127.0.0.1.
8341
8342 This option may be specified either in the frontend or in the backend. If at
8343 least one of them uses it, the header will be added. Note that the backend's
8344 setting of the header subargument takes precedence over the frontend's if
8345 both are defined.
8346
Willy Tarreau55165fe2009-05-10 12:02:55 +02008347 Examples :
8348 # Original Destination address
8349 frontend www
8350 mode http
8351 option originalto except 127.0.0.1
8352
8353 # Those servers want the IP Address in X-Client-Dst
8354 backend www
8355 mode http
8356 option originalto header X-Client-Dst
8357
Christopher Faulet315b39c2018-09-21 16:26:19 +02008358 See also : "option httpclose", "option http-server-close".
Willy Tarreau55165fe2009-05-10 12:02:55 +02008359
8360
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008361option persist
8362no option persist
8363 Enable or disable forced persistence on down servers
8364 May be used in sections: defaults | frontend | listen | backend
8365 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008366 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008367
8368 When an HTTP request reaches a backend with a cookie which references a dead
8369 server, by default it is redispatched to another server. It is possible to
8370 force the request to be sent to the dead server first using "option persist"
8371 if absolutely needed. A common use case is when servers are under extreme
8372 load and spend their time flapping. In this case, the users would still be
8373 directed to the server they opened the session on, in the hope they would be
8374 correctly served. It is recommended to use "option redispatch" in conjunction
8375 with this option so that in the event it would not be possible to connect to
8376 the server at all (server definitely dead), the client would finally be
8377 redirected to another valid server.
8378
8379 If this option has been enabled in a "defaults" section, it can be disabled
8380 in a specific instance by prepending the "no" keyword before it.
8381
Willy Tarreau4de91492010-01-22 19:10:05 +01008382 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008383
8384
Willy Tarreau0c122822013-12-15 18:49:01 +01008385option pgsql-check [ user <username> ]
8386 Use PostgreSQL health checks for server testing
8387 May be used in sections : defaults | frontend | listen | backend
8388 yes | no | yes | yes
8389 Arguments :
8390 <username> This is the username which will be used when connecting to
8391 PostgreSQL server.
8392
8393 The check sends a PostgreSQL StartupMessage and waits for either
8394 Authentication request or ErrorResponse message. It is a basic but useful
8395 test which does not produce error nor aborted connect on the server.
8396 This check is identical with the "mysql-check".
8397
8398 See also: "option httpchk"
8399
8400
Willy Tarreau9420b122013-12-15 18:58:25 +01008401option prefer-last-server
8402no option prefer-last-server
8403 Allow multiple load balanced requests to remain on the same server
8404 May be used in sections: defaults | frontend | listen | backend
8405 yes | no | yes | yes
8406 Arguments : none
8407
8408 When the load balancing algorithm in use is not deterministic, and a previous
8409 request was sent to a server to which haproxy still holds a connection, it is
8410 sometimes desirable that subsequent requests on a same session go to the same
8411 server as much as possible. Note that this is different from persistence, as
8412 we only indicate a preference which haproxy tries to apply without any form
8413 of warranty. The real use is for keep-alive connections sent to servers. When
8414 this option is used, haproxy will try to reuse the same connection that is
8415 attached to the server instead of rebalancing to another server, causing a
8416 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01008417 not make much sense to use this in combination with hashing algorithms. Note,
8418 haproxy already automatically tries to stick to a server which sends a 401 or
Lukas Tribus80512b12018-10-27 20:07:40 +02008419 to a proxy which sends a 407 (authentication required), when the load
8420 balancing algorithm is not deterministic. This is mandatory for use with the
8421 broken NTLM authentication challenge, and significantly helps in
Willy Tarreau068621e2013-12-23 15:11:25 +01008422 troubleshooting some faulty applications. Option prefer-last-server might be
8423 desirable in these environments as well, to avoid redistributing the traffic
8424 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01008425
8426 If this option has been enabled in a "defaults" section, it can be disabled
8427 in a specific instance by prepending the "no" keyword before it.
8428
8429 See also: "option http-keep-alive"
8430
8431
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008432option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07008433option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008434no option redispatch
8435 Enable or disable session redistribution in case of connection failure
8436 May be used in sections: defaults | frontend | listen | backend
8437 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07008438 Arguments :
8439 <interval> The optional integer value that controls how often redispatches
8440 occur when retrying connections. Positive value P indicates a
8441 redispatch is desired on every Pth retry, and negative value
Davor Ocelice9ed2812017-12-25 17:49:28 +01008442 N indicate a redispatch is desired on the Nth retry prior to the
Joseph Lynch726ab712015-05-11 23:25:34 -07008443 last retry. For example, the default of -1 preserves the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008444 historical behavior of redispatching on the last retry, a
Joseph Lynch726ab712015-05-11 23:25:34 -07008445 positive value of 1 would indicate a redispatch on every retry,
8446 and a positive value of 3 would indicate a redispatch on every
8447 third retry. You can disable redispatches with a value of 0.
8448
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008449
8450 In HTTP mode, if a server designated by a cookie is down, clients may
8451 definitely stick to it because they cannot flush the cookie, so they will not
8452 be able to access the service anymore.
8453
Willy Tarreau59884a62019-01-02 14:48:31 +01008454 Specifying "option redispatch" will allow the proxy to break cookie or
8455 consistent hash based persistence and redistribute them to a working server.
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008456
Olivier Carrère6e6f59b2020-04-15 11:30:18 +02008457 Active servers are selected from a subset of the list of available
8458 servers. Active servers that are not down or in maintenance (i.e., whose
8459 health is not checked or that have been checked as "up"), are selected in the
8460 following order:
8461
8462 1. Any active, non-backup server, if any, or,
8463
8464 2. If the "allbackups" option is not set, the first backup server in the
8465 list, or
8466
8467 3. If the "allbackups" option is set, any backup server.
8468
8469 When a retry occurs, HAProxy tries to select another server than the last
8470 one. The new server is selected from the current list of servers.
8471
8472 Sometimes, if the list is updated between retries (e.g., if numerous retries
8473 occur and last longer than the time needed to check that a server is down,
8474 remove it from the list and fall back on the list of backup servers),
8475 connections may be redirected to a backup server, though.
8476
Joseph Lynch726ab712015-05-11 23:25:34 -07008477 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008478 connection failures. Of course, it requires having "retries" set to a nonzero
8479 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01008480
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008481 If this option has been enabled in a "defaults" section, it can be disabled
8482 in a specific instance by prepending the "no" keyword before it.
8483
Christopher Faulet87f1f3d2019-07-18 14:51:20 +02008484 See also : "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008485
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008486
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02008487option redis-check
8488 Use redis health checks for server testing
8489 May be used in sections : defaults | frontend | listen | backend
8490 yes | no | yes | yes
8491 Arguments : none
8492
8493 It is possible to test that the server correctly talks REDIS protocol instead
8494 of just testing that it accepts the TCP connection. When this option is set,
8495 a PING redis command is sent to the server, and the response is analyzed to
8496 find the "+PONG" response message.
8497
8498 Example :
8499 option redis-check
8500
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03008501 See also : "option httpchk", "option tcp-check", "tcp-check expect"
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02008502
8503
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008504option smtpchk
8505option smtpchk <hello> <domain>
8506 Use SMTP health checks for server testing
8507 May be used in sections : defaults | frontend | listen | backend
8508 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01008509 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008510 <hello> is an optional argument. It is the "hello" command to use. It can
Lukas Tribus27935782018-10-01 02:00:16 +02008511 be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008512 values will be turned into the default command ("HELO").
8513
8514 <domain> is the domain name to present to the server. It may only be
8515 specified (and is mandatory) if the hello command has been
8516 specified. By default, "localhost" is used.
8517
8518 When "option smtpchk" is set, the health checks will consist in TCP
8519 connections followed by an SMTP command. By default, this command is
8520 "HELO localhost". The server's return code is analyzed and only return codes
8521 starting with a "2" will be considered as valid. All other responses,
8522 including a lack of response will constitute an error and will indicate a
8523 dead server.
8524
8525 This test is meant to be used with SMTP servers or relays. Depending on the
8526 request, it is possible that some servers do not log each connection attempt,
Davor Ocelice9ed2812017-12-25 17:49:28 +01008527 so you may want to experiment to improve the behavior. Using telnet on port
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008528 25 is often easier than adjusting the configuration.
8529
8530 Most often, an incoming SMTP server needs to see the client's IP address for
8531 various purposes, including spam filtering, anti-spoofing and logging. When
8532 possible, it is often wise to masquerade the client's IP address when
8533 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02008534 which requires the transparent proxy feature to be compiled in.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008535
8536 Example :
8537 option smtpchk HELO mydomain.org
8538
8539 See also : "option httpchk", "source"
8540
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008541
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02008542option socket-stats
8543no option socket-stats
8544
8545 Enable or disable collecting & providing separate statistics for each socket.
8546 May be used in sections : defaults | frontend | listen | backend
8547 yes | yes | yes | no
8548
8549 Arguments : none
8550
8551
Willy Tarreauff4f82d2009-02-06 11:28:13 +01008552option splice-auto
8553no option splice-auto
8554 Enable or disable automatic kernel acceleration on sockets in both directions
8555 May be used in sections : defaults | frontend | listen | backend
8556 yes | yes | yes | yes
8557 Arguments : none
8558
8559 When this option is enabled either on a frontend or on a backend, haproxy
8560 will automatically evaluate the opportunity to use kernel tcp splicing to
Davor Ocelice9ed2812017-12-25 17:49:28 +01008561 forward data between the client and the server, in either direction. HAProxy
Willy Tarreauff4f82d2009-02-06 11:28:13 +01008562 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01008563 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01008564 are not much aggressive in order to limit excessive use of splicing. This
8565 option requires splicing to be enabled at compile time, and may be globally
8566 disabled with the global option "nosplice". Since splice uses pipes, using it
8567 requires that there are enough spare pipes.
8568
8569 Important note: kernel-based TCP splicing is a Linux-specific feature which
8570 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
8571 transfer data between sockets without copying these data to user-space, thus
8572 providing noticeable performance gains and CPU cycles savings. Since many
8573 early implementations are buggy, corrupt data and/or are inefficient, this
8574 feature is not enabled by default, and it should be used with extreme care.
8575 While it is not possible to detect the correctness of an implementation,
8576 2.6.29 is the first version offering a properly working implementation. In
8577 case of doubt, splicing may be globally disabled using the global "nosplice"
8578 keyword.
8579
8580 Example :
8581 option splice-auto
8582
8583 If this option has been enabled in a "defaults" section, it can be disabled
8584 in a specific instance by prepending the "no" keyword before it.
8585
8586 See also : "option splice-request", "option splice-response", and global
8587 options "nosplice" and "maxpipes"
8588
8589
8590option splice-request
8591no option splice-request
8592 Enable or disable automatic kernel acceleration on sockets for requests
8593 May be used in sections : defaults | frontend | listen | backend
8594 yes | yes | yes | yes
8595 Arguments : none
8596
8597 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008598 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01008599 the client to the server. It might still use the recv/send scheme if there
8600 are no spare pipes left. This option requires splicing to be enabled at
8601 compile time, and may be globally disabled with the global option "nosplice".
8602 Since splice uses pipes, using it requires that there are enough spare pipes.
8603
8604 Important note: see "option splice-auto" for usage limitations.
8605
8606 Example :
8607 option splice-request
8608
8609 If this option has been enabled in a "defaults" section, it can be disabled
8610 in a specific instance by prepending the "no" keyword before it.
8611
8612 See also : "option splice-auto", "option splice-response", and global options
8613 "nosplice" and "maxpipes"
8614
8615
8616option splice-response
8617no option splice-response
8618 Enable or disable automatic kernel acceleration on sockets for responses
8619 May be used in sections : defaults | frontend | listen | backend
8620 yes | yes | yes | yes
8621 Arguments : none
8622
8623 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008624 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01008625 the server to the client. It might still use the recv/send scheme if there
8626 are no spare pipes left. This option requires splicing to be enabled at
8627 compile time, and may be globally disabled with the global option "nosplice".
8628 Since splice uses pipes, using it requires that there are enough spare pipes.
8629
8630 Important note: see "option splice-auto" for usage limitations.
8631
8632 Example :
8633 option splice-response
8634
8635 If this option has been enabled in a "defaults" section, it can be disabled
8636 in a specific instance by prepending the "no" keyword before it.
8637
8638 See also : "option splice-auto", "option splice-request", and global options
8639 "nosplice" and "maxpipes"
8640
8641
Christopher Fauletba7bc162016-11-07 21:07:38 +01008642option spop-check
8643 Use SPOP health checks for server testing
8644 May be used in sections : defaults | frontend | listen | backend
8645 no | no | no | yes
8646 Arguments : none
8647
8648 It is possible to test that the server correctly talks SPOP protocol instead
8649 of just testing that it accepts the TCP connection. When this option is set,
8650 a HELLO handshake is performed between HAProxy and the server, and the
8651 response is analyzed to check no error is reported.
8652
8653 Example :
8654 option spop-check
8655
8656 See also : "option httpchk"
8657
8658
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008659option srvtcpka
8660no option srvtcpka
8661 Enable or disable the sending of TCP keepalive packets on the server side
8662 May be used in sections : defaults | frontend | listen | backend
8663 yes | no | yes | yes
8664 Arguments : none
8665
8666 When there is a firewall or any session-aware component between a client and
8667 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01008668 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008669 components decides to expire a session which has remained idle for too long.
8670
8671 Enabling socket-level TCP keep-alives makes the system regularly send packets
8672 to the other end of the connection, leaving it active. The delay between
8673 keep-alive probes is controlled by the system only and depends both on the
8674 operating system and its tuning parameters.
8675
8676 It is important to understand that keep-alive packets are neither emitted nor
8677 received at the application level. It is only the network stacks which sees
8678 them. For this reason, even if one side of the proxy already uses keep-alives
8679 to maintain its connection alive, those keep-alive packets will not be
8680 forwarded to the other side of the proxy.
8681
8682 Please note that this has nothing to do with HTTP keep-alive.
8683
8684 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
8685 server side of a connection, which should help when session expirations are
8686 noticed between HAProxy and a server.
8687
8688 If this option has been enabled in a "defaults" section, it can be disabled
8689 in a specific instance by prepending the "no" keyword before it.
8690
8691 See also : "option clitcpka", "option tcpka"
8692
8693
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008694option ssl-hello-chk
8695 Use SSLv3 client hello health checks for server testing
8696 May be used in sections : defaults | frontend | listen | backend
8697 yes | no | yes | yes
8698 Arguments : none
8699
8700 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
8701 possible to test that the server correctly talks SSL instead of just testing
8702 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
8703 SSLv3 client hello messages are sent once the connection is established to
8704 the server, and the response is analyzed to find an SSL server hello message.
8705 The server is considered valid only when the response contains this server
8706 hello message.
8707
8708 All servers tested till there correctly reply to SSLv3 client hello messages,
8709 and most servers tested do not even log the requests containing only hello
8710 messages, which is appreciable.
8711
Willy Tarreau763a95b2012-10-04 23:15:39 +02008712 Note that this check works even when SSL support was not built into haproxy
8713 because it forges the SSL message. When SSL support is available, it is best
8714 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008715
Willy Tarreau763a95b2012-10-04 23:15:39 +02008716 See also: "option httpchk", "check-ssl"
8717
Willy Tarreaua453bdd2008-01-08 19:50:52 +01008718
Willy Tarreaued179852013-12-16 01:07:00 +01008719option tcp-check
8720 Perform health checks using tcp-check send/expect sequences
8721 May be used in sections: defaults | frontend | listen | backend
8722 yes | no | yes | yes
8723
8724 This health check method is intended to be combined with "tcp-check" command
8725 lists in order to support send/expect types of health check sequences.
8726
8727 TCP checks currently support 4 modes of operations :
8728 - no "tcp-check" directive : the health check only consists in a connection
8729 attempt, which remains the default mode.
8730
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008731 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01008732 used to send a string along with a connection opening. With some
8733 protocols, it helps sending a "QUIT" message for example that prevents
8734 the server from logging a connection error for each health check. The
8735 check result will still be based on the ability to open the connection
8736 only.
8737
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008738 - "tcp-check expect" only is mentioned : this is used to test a banner.
Willy Tarreaued179852013-12-16 01:07:00 +01008739 The connection is opened and haproxy waits for the server to present some
8740 contents which must validate some rules. The check result will be based
8741 on the matching between the contents and the rules. This is suited for
8742 POP, IMAP, SMTP, FTP, SSH, TELNET.
8743
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008744 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Davor Ocelice9ed2812017-12-25 17:49:28 +01008745 used to test a hello-type protocol. HAProxy sends a message, the server
8746 responds and its response is analyzed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03008747 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01008748 suited for protocols which require a binding or a request/response model.
8749 LDAP, MySQL, Redis and SSL are example of such protocols, though they
8750 already all have their dedicated checks with a deeper understanding of
8751 the respective protocols.
8752 In this mode, many questions may be sent and many answers may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01008753 analyzed.
Willy Tarreaued179852013-12-16 01:07:00 +01008754
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02008755 A fifth mode can be used to insert comments in different steps of the script.
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008756
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02008757 For each tcp-check rule you create, you can add a "comment" directive,
8758 followed by a string. This string will be reported in the log and stderr in
8759 debug mode. It is useful to make user-friendly error reporting. The
8760 "comment" is of course optional.
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008761
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02008762 During the execution of a health check, a variable scope is made available to
8763 store data samples, using the "tcp-check set-var" operation. Freeing those
8764 variable is possible using "tcp-check unset-var".
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +01008765
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008766
Willy Tarreaued179852013-12-16 01:07:00 +01008767 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01008768 # perform a POP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01008769 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008770 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01008771
Davor Ocelice9ed2812017-12-25 17:49:28 +01008772 # perform an IMAP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01008773 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008774 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01008775
8776 # look for the redis master server after ensuring it speaks well
8777 # redis protocol, then it exits properly.
Davor Ocelice9ed2812017-12-25 17:49:28 +01008778 # (send a command then analyze the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01008779 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008780 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01008781 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02008782 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008783 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01008784 tcp-check send info\ replication\r\n
8785 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008786 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01008787 tcp-check send QUIT\r\n
8788 tcp-check expect string +OK
8789
Davor Ocelice9ed2812017-12-25 17:49:28 +01008790 forge a HTTP request, then analyze the response
Willy Tarreaued179852013-12-16 01:07:00 +01008791 (send many headers before analyzing)
8792 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008793 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01008794 tcp-check send HEAD\ /\ HTTP/1.1\r\n
8795 tcp-check send Host:\ www.mydomain.com\r\n
8796 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
8797 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02008798 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01008799
8800
Christopher Fauletc52ea4d2020-04-23 15:43:35 +02008801 See also : "tcp-check connect", "tcp-check expect" and "tcp-check send".
Willy Tarreaued179852013-12-16 01:07:00 +01008802
8803
Willy Tarreau9ea05a72009-06-14 12:07:01 +02008804option tcp-smart-accept
8805no option tcp-smart-accept
8806 Enable or disable the saving of one ACK packet during the accept sequence
8807 May be used in sections : defaults | frontend | listen | backend
8808 yes | yes | yes | no
8809 Arguments : none
8810
8811 When an HTTP connection request comes in, the system acknowledges it on
8812 behalf of HAProxy, then the client immediately sends its request, and the
8813 system acknowledges it too while it is notifying HAProxy about the new
8814 connection. HAProxy then reads the request and responds. This means that we
8815 have one TCP ACK sent by the system for nothing, because the request could
8816 very well be acknowledged by HAProxy when it sends its response.
8817
8818 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
8819 sending this useless ACK on platforms which support it (currently at least
8820 Linux). It must not cause any problem, because the system will send it anyway
8821 after 40 ms if the response takes more time than expected to come.
8822
8823 During complex network debugging sessions, it may be desirable to disable
8824 this optimization because delayed ACKs can make troubleshooting more complex
8825 when trying to identify where packets are delayed. It is then possible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01008826 fall back to normal behavior by specifying "no option tcp-smart-accept".
Willy Tarreau9ea05a72009-06-14 12:07:01 +02008827
8828 It is also possible to force it for non-HTTP proxies by simply specifying
8829 "option tcp-smart-accept". For instance, it can make sense with some services
8830 such as SMTP where the server speaks first.
8831
8832 It is recommended to avoid forcing this option in a defaults section. In case
8833 of doubt, consider setting it back to automatic values by prepending the
8834 "default" keyword before it, or disabling it using the "no" keyword.
8835
Willy Tarreaud88edf22009-06-14 15:48:17 +02008836 See also : "option tcp-smart-connect"
8837
8838
8839option tcp-smart-connect
8840no option tcp-smart-connect
8841 Enable or disable the saving of one ACK packet during the connect sequence
8842 May be used in sections : defaults | frontend | listen | backend
8843 yes | no | yes | yes
8844 Arguments : none
8845
8846 On certain systems (at least Linux), HAProxy can ask the kernel not to
8847 immediately send an empty ACK upon a connection request, but to directly
8848 send the buffer request instead. This saves one packet on the network and
8849 thus boosts performance. It can also be useful for some servers, because they
8850 immediately get the request along with the incoming connection.
8851
8852 This feature is enabled when "option tcp-smart-connect" is set in a backend.
8853 It is not enabled by default because it makes network troubleshooting more
8854 complex.
8855
8856 It only makes sense to enable it with protocols where the client speaks first
8857 such as HTTP. In other situations, if there is no data to send in place of
8858 the ACK, a normal ACK is sent.
8859
8860 If this option has been enabled in a "defaults" section, it can be disabled
8861 in a specific instance by prepending the "no" keyword before it.
8862
8863 See also : "option tcp-smart-accept"
8864
Willy Tarreau9ea05a72009-06-14 12:07:01 +02008865
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008866option tcpka
8867 Enable or disable the sending of TCP keepalive packets on both sides
8868 May be used in sections : defaults | frontend | listen | backend
8869 yes | yes | yes | yes
8870 Arguments : none
8871
8872 When there is a firewall or any session-aware component between a client and
8873 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01008874 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008875 components decides to expire a session which has remained idle for too long.
8876
8877 Enabling socket-level TCP keep-alives makes the system regularly send packets
8878 to the other end of the connection, leaving it active. The delay between
8879 keep-alive probes is controlled by the system only and depends both on the
8880 operating system and its tuning parameters.
8881
8882 It is important to understand that keep-alive packets are neither emitted nor
8883 received at the application level. It is only the network stacks which sees
8884 them. For this reason, even if one side of the proxy already uses keep-alives
8885 to maintain its connection alive, those keep-alive packets will not be
8886 forwarded to the other side of the proxy.
8887
8888 Please note that this has nothing to do with HTTP keep-alive.
8889
8890 Using option "tcpka" enables the emission of TCP keep-alive probes on both
8891 the client and server sides of a connection. Note that this is meaningful
8892 only in "defaults" or "listen" sections. If this option is used in a
8893 frontend, only the client side will get keep-alives, and if this option is
8894 used in a backend, only the server side will get keep-alives. For this
8895 reason, it is strongly recommended to explicitly use "option clitcpka" and
8896 "option srvtcpka" when the configuration is split between frontends and
8897 backends.
8898
8899 See also : "option clitcpka", "option srvtcpka"
8900
Willy Tarreau844e3c52008-01-11 16:28:18 +01008901
8902option tcplog
8903 Enable advanced logging of TCP connections with session state and timers
8904 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01008905 yes | yes | yes | no
Willy Tarreau844e3c52008-01-11 16:28:18 +01008906 Arguments : none
8907
8908 By default, the log output format is very poor, as it only contains the
8909 source and destination addresses, and the instance name. By specifying
8910 "option tcplog", each log line turns into a much richer format including, but
8911 not limited to, the connection timers, the session status, the connections
8912 numbers, the frontend, backend and server name, and of course the source
8913 address and ports. This option is useful for pure TCP proxies in order to
8914 find which of the client or server disconnects or times out. For normal HTTP
8915 proxies, it's better to use "option httplog" which is even more complete.
8916
Guillaume de Lafond29f45602017-03-31 19:52:15 +02008917 "option tcplog" overrides any previous "log-format" directive.
8918
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008919 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01008920
8921
Willy Tarreau844e3c52008-01-11 16:28:18 +01008922option transparent
8923no option transparent
8924 Enable client-side transparent proxying
8925 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01008926 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01008927 Arguments : none
8928
8929 This option was introduced in order to provide layer 7 persistence to layer 3
8930 load balancers. The idea is to use the OS's ability to redirect an incoming
8931 connection for a remote address to a local process (here HAProxy), and let
8932 this process know what address was initially requested. When this option is
8933 used, sessions without cookies will be forwarded to the original destination
8934 IP address of the incoming request (which should match that of another
8935 equipment), while requests with cookies will still be forwarded to the
8936 appropriate server.
8937
8938 Note that contrary to a common belief, this option does NOT make HAProxy
8939 present the client's IP to the server when establishing the connection.
8940
Willy Tarreaua1146052011-03-01 09:51:54 +01008941 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008942 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01008943
Willy Tarreaubf1f8162007-12-28 17:42:56 +01008944
Simon Horman98637e52014-06-20 12:30:16 +09008945external-check command <command>
8946 Executable to run when performing an external-check
8947 May be used in sections : defaults | frontend | listen | backend
8948 yes | no | yes | yes
8949
8950 Arguments :
8951 <command> is the external command to run
8952
Simon Horman98637e52014-06-20 12:30:16 +09008953 The arguments passed to the to the command are:
8954
Cyril Bonté777be862014-12-02 21:21:35 +01008955 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09008956
Cyril Bonté777be862014-12-02 21:21:35 +01008957 The <proxy_address> and <proxy_port> are derived from the first listener
8958 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
8959 listener the proxy_address will be the path of the socket and the
8960 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
8961 possible to determine a listener, and both <proxy_address> and <proxy_port>
8962 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09008963
Cyril Bonté72cda2a2014-12-27 22:28:39 +01008964 Some values are also provided through environment variables.
8965
8966 Environment variables :
8967 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
8968 applicable, for example in a "backend" section).
8969
8970 HAPROXY_PROXY_ID The backend id.
8971
8972 HAPROXY_PROXY_NAME The backend name.
8973
8974 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
8975 applicable, for example in a "backend" section or
8976 for a UNIX socket).
8977
8978 HAPROXY_SERVER_ADDR The server address.
8979
8980 HAPROXY_SERVER_CURCONN The current number of connections on the server.
8981
8982 HAPROXY_SERVER_ID The server id.
8983
8984 HAPROXY_SERVER_MAXCONN The server max connections.
8985
8986 HAPROXY_SERVER_NAME The server name.
8987
8988 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
8989 socket).
8990
8991 PATH The PATH environment variable used when executing
8992 the command may be set using "external-check path".
8993
William Lallemand4d03e432019-06-14 15:35:37 +02008994 See also "2.3. Environment variables" for other variables.
8995
Simon Horman98637e52014-06-20 12:30:16 +09008996 If the command executed and exits with a zero status then the check is
8997 considered to have passed, otherwise the check is considered to have
8998 failed.
8999
9000 Example :
9001 external-check command /bin/true
9002
9003 See also : "external-check", "option external-check", "external-check path"
9004
9005
9006external-check path <path>
9007 The value of the PATH environment variable used when running an external-check
9008 May be used in sections : defaults | frontend | listen | backend
9009 yes | no | yes | yes
9010
9011 Arguments :
9012 <path> is the path used when executing external command to run
9013
9014 The default path is "".
9015
9016 Example :
9017 external-check path "/usr/bin:/bin"
9018
9019 See also : "external-check", "option external-check",
9020 "external-check command"
9021
9022
Emeric Brun647caf12009-06-30 17:57:00 +02009023persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02009024persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02009025 Enable RDP cookie-based persistence
9026 May be used in sections : defaults | frontend | listen | backend
9027 yes | no | yes | yes
9028 Arguments :
9029 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02009030 default cookie name "msts" will be used. There currently is no
9031 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02009032
9033 This statement enables persistence based on an RDP cookie. The RDP cookie
9034 contains all information required to find the server in the list of known
Davor Ocelice9ed2812017-12-25 17:49:28 +01009035 servers. So when this option is set in the backend, the request is analyzed
Emeric Brun647caf12009-06-30 17:57:00 +02009036 and if an RDP cookie is found, it is decoded. If it matches a known server
9037 which is still UP (or if "option persist" is set), then the connection is
9038 forwarded to this server.
9039
9040 Note that this only makes sense in a TCP backend, but for this to work, the
9041 frontend must have waited long enough to ensure that an RDP cookie is present
9042 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009043 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02009044 a single "listen" section.
9045
Willy Tarreau61e28f22010-05-16 22:31:05 +02009046 Also, it is important to understand that the terminal server will emit this
9047 RDP cookie only if it is configured for "token redirection mode", which means
9048 that the "IP address redirection" option is disabled.
9049
Emeric Brun647caf12009-06-30 17:57:00 +02009050 Example :
9051 listen tse-farm
9052 bind :3389
9053 # wait up to 5s for an RDP cookie in the request
9054 tcp-request inspect-delay 5s
9055 tcp-request content accept if RDP_COOKIE
9056 # apply RDP cookie persistence
9057 persist rdp-cookie
9058 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02009059 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02009060 balance rdp-cookie
9061 server srv1 1.1.1.1:3389
9062 server srv2 1.1.1.2:3389
9063
Simon Hormanab814e02011-06-24 14:50:20 +09009064 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
9065 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02009066
9067
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009068rate-limit sessions <rate>
9069 Set a limit on the number of new sessions accepted per second on a frontend
9070 May be used in sections : defaults | frontend | listen | backend
9071 yes | yes | yes | no
9072 Arguments :
9073 <rate> The <rate> parameter is an integer designating the maximum number
9074 of new sessions per second to accept on the frontend.
9075
9076 When the frontend reaches the specified number of new sessions per second, it
9077 stops accepting new connections until the rate drops below the limit again.
9078 During this time, the pending sessions will be kept in the socket's backlog
9079 (in system buffers) and haproxy will not even be aware that sessions are
9080 pending. When applying very low limit on a highly loaded service, it may make
9081 sense to increase the socket's backlog using the "backlog" keyword.
9082
9083 This feature is particularly efficient at blocking connection-based attacks
9084 or service abuse on fragile servers. Since the session rate is measured every
9085 millisecond, it is extremely accurate. Also, the limit applies immediately,
9086 no delay is needed at all to detect the threshold.
9087
9088 Example : limit the connection rate on SMTP to 10 per second max
9089 listen smtp
9090 mode tcp
9091 bind :25
9092 rate-limit sessions 10
Panagiotis Panagiotopoulos7282d8e2016-02-11 16:37:15 +02009093 server smtp1 127.0.0.1:1025
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009094
Willy Tarreaua17c2d92011-07-25 08:16:20 +02009095 Note : when the maximum rate is reached, the frontend's status is not changed
9096 but its sockets appear as "WAITING" in the statistics if the
9097 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01009098
9099 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
9100
9101
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009102redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
9103redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
9104redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009105 Return an HTTP redirection if/unless a condition is matched
9106 May be used in sections : defaults | frontend | listen | backend
9107 no | yes | yes | yes
9108
9109 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01009110 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009111
Willy Tarreau0140f252008-11-19 21:07:09 +01009112 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009113 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009114 the HTTP "Location" header. When used in an "http-request" rule,
9115 <loc> value follows the log-format rules and can include some
9116 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009117
9118 <pfx> With "redirect prefix", the "Location" header is built from the
9119 concatenation of <pfx> and the complete URI path, including the
9120 query string, unless the "drop-query" option is specified (see
9121 below). As a special case, if <pfx> equals exactly "/", then
9122 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009123 redirect to the same URL (for instance, to insert a cookie). When
9124 used in an "http-request" rule, <pfx> value follows the log-format
9125 rules and can include some dynamic values (see Custom Log Format
9126 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009127
9128 <sch> With "redirect scheme", then the "Location" header is built by
9129 concatenating <sch> with "://" then the first occurrence of the
9130 "Host" header, and then the URI path, including the query string
9131 unless the "drop-query" option is specified (see below). If no
9132 path is found or if the path is "*", then "/" is used instead. If
9133 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009134 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009135 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009136 HTTPS. When used in an "http-request" rule, <sch> value follows
9137 the log-format rules and can include some dynamic values (see
9138 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01009139
9140 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01009141 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
9142 with 302 used by default if no code is specified. 301 means
9143 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02009144 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01009145 cache the redirection. 303 is equivalent to 302 except that the
9146 browser will fetch the location with a GET method. 307 is just
9147 like 302 but makes it clear that the same method must be reused.
9148 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01009149
9150 <option> There are several options which can be specified to adjust the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009151 expected behavior of a redirection :
Willy Tarreau0140f252008-11-19 21:07:09 +01009152
9153 - "drop-query"
9154 When this keyword is used in a prefix-based redirection, then the
9155 location will be set without any possible query-string, which is useful
9156 for directing users to a non-secure page for instance. It has no effect
9157 with a location-type redirect.
9158
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01009159 - "append-slash"
9160 This keyword may be used in conjunction with "drop-query" to redirect
9161 users who use a URL not ending with a '/' to the same one with the '/'.
9162 It can be useful to ensure that search engines will only see one URL.
9163 For this, a return code 301 is preferred.
9164
Willy Tarreau0140f252008-11-19 21:07:09 +01009165 - "set-cookie NAME[=value]"
9166 A "Set-Cookie" header will be added with NAME (and optionally "=value")
9167 to the response. This is sometimes used to indicate that a user has
9168 been seen, for instance to protect against some types of DoS. No other
9169 cookie option is added, so the cookie will be a session cookie. Note
9170 that for a browser, a sole cookie name without an equal sign is
9171 different from a cookie with an equal sign.
9172
9173 - "clear-cookie NAME[=]"
9174 A "Set-Cookie" header will be added with NAME (and optionally "="), but
9175 with the "Max-Age" attribute set to zero. This will tell the browser to
9176 delete this cookie. It is useful for instance on logout pages. It is
9177 important to note that clearing the cookie "NAME" will not remove a
9178 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
9179 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009180
9181 Example: move the login URL only to HTTPS.
9182 acl clear dst_port 80
9183 acl secure dst_port 8080
9184 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01009185 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01009186 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01009187 acl cookie_set hdr_sub(cookie) SEEN=1
9188
9189 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01009190 redirect prefix https://mysite.com if login_page !secure
9191 redirect prefix http://mysite.com drop-query if login_page !uid_given
9192 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01009193 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009194
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01009195 Example: send redirects for request for articles without a '/'.
9196 acl missing_slash path_reg ^/article/[^/]*$
9197 redirect code 301 prefix / drop-query append-slash if missing_slash
9198
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009199 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01009200 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02009201
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009202 Example: append 'www.' prefix in front of all hosts not having it
Coen Rosdorff596659b2016-04-11 11:33:49 +02009203 http-request redirect code 301 location \
9204 http://www.%[hdr(host)]%[capture.req.uri] \
9205 unless { hdr_beg(host) -i www }
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01009206
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009207 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02009208
Willy Tarreau303c0352008-01-17 19:01:39 +01009209
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02009210retries <value>
9211 Set the number of retries to perform on a server after a connection failure
9212 May be used in sections: defaults | frontend | listen | backend
9213 yes | no | yes | yes
9214 Arguments :
9215 <value> is the number of times a connection attempt should be retried on
9216 a server when a connection either is refused or times out. The
9217 default value is 3.
9218
9219 It is important to understand that this value applies to the number of
9220 connection attempts, not full requests. When a connection has effectively
9221 been established to a server, there will be no more retry.
9222
9223 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -07009224 a turn-around timer of min("timeout connect", one second) is applied before
9225 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02009226
9227 When "option redispatch" is set, the last retry may be performed on another
9228 server even if a cookie references a different server.
9229
9230 See also : "option redispatch"
9231
9232
Olivier Houcharda254a372019-04-05 15:30:12 +02009233retry-on [list of keywords]
Jerome Magnin5ce3c142020-05-13 20:09:57 +02009234 Specify when to attempt to automatically retry a failed request.
9235 This setting is only valid when "mode" is set to http and is silently ignored
9236 otherwise.
Olivier Houcharda254a372019-04-05 15:30:12 +02009237 May be used in sections: defaults | frontend | listen | backend
9238 yes | no | yes | yes
9239 Arguments :
9240 <keywords> is a list of keywords or HTTP status codes, each representing a
9241 type of failure event on which an attempt to retry the request
9242 is desired. Please read the notes at the bottom before changing
9243 this setting. The following keywords are supported :
9244
9245 none never retry
9246
9247 conn-failure retry when the connection or the SSL handshake failed
9248 and the request could not be sent. This is the default.
9249
9250 empty-response retry when the server connection was closed after part
9251 of the request was sent, and nothing was received from
9252 the server. This type of failure may be caused by the
9253 request timeout on the server side, poor network
9254 condition, or a server crash or restart while
9255 processing the request.
9256
Olivier Houcharde3249a92019-05-03 23:01:47 +02009257 junk-response retry when the server returned something not looking
9258 like a complete HTTP response. This includes partial
9259 responses headers as well as non-HTTP contents. It
9260 usually is a bad idea to retry on such events, which
9261 may be caused a configuration issue (wrong server port)
9262 or by the request being harmful to the server (buffer
9263 overflow attack for example).
9264
Olivier Houcharda254a372019-04-05 15:30:12 +02009265 response-timeout the server timeout stroke while waiting for the server
9266 to respond to the request. This may be caused by poor
9267 network condition, the reuse of an idle connection
9268 which has expired on the path, or by the request being
9269 extremely expensive to process. It generally is a bad
9270 idea to retry on such events on servers dealing with
9271 heavy database processing (full scans, etc) as it may
9272 amplify denial of service attacks.
9273
Olivier Houchard865d8392019-05-03 22:46:27 +02009274 0rtt-rejected retry requests which were sent over early data and were
9275 rejected by the server. These requests are generally
9276 considered to be safe to retry.
9277
Olivier Houcharda254a372019-04-05 15:30:12 +02009278 <status> any HTTP status code among "404" (Not Found), "408"
9279 (Request Timeout), "425" (Too Early), "500" (Server
9280 Error), "501" (Not Implemented), "502" (Bad Gateway),
9281 "503" (Service Unavailable), "504" (Gateway Timeout).
9282
Olivier Houchardddf0e032019-05-10 18:05:40 +02009283 all-retryable-errors
9284 retry request for any error that are considered
9285 retryable. This currently activates "conn-failure",
9286 "empty-response", "junk-response", "response-timeout",
9287 "0rtt-rejected", "500", "502", "503", and "504".
9288
Olivier Houcharda254a372019-04-05 15:30:12 +02009289 Using this directive replaces any previous settings with the new ones; it is
9290 not cumulative.
9291
9292 Please note that using anything other than "none" and "conn-failure" requires
9293 to allocate a buffer and copy the whole request into it, so it has memory and
9294 performance impacts. Requests not fitting in a single buffer will never be
9295 retried (see the global tune.bufsize setting).
9296
9297 You have to make sure the application has a replay protection mechanism built
9298 in such as a unique transaction IDs passed in requests, or that replaying the
9299 same request has no consequence, or it is very dangerous to use any retry-on
9300 value beside "conn-failure" and "none". Static file servers and caches are
9301 generally considered safe against any type of retry. Using a status code can
9302 be useful to quickly leave a server showing an abnormal behavior (out of
9303 memory, file system issues, etc), but in this case it may be a good idea to
9304 immediately redispatch the connection to another server (please see "option
9305 redispatch" for this). Last, it is important to understand that most causes
9306 of failures are the requests themselves and that retrying a request causing a
9307 server to misbehave will often make the situation even worse for this server,
9308 or for the whole service in case of redispatch.
9309
9310 Unless you know exactly how the application deals with replayed requests, you
9311 should not use this directive.
9312
9313 The default is "conn-failure".
9314
9315 See also: "retries", "option redispatch", "tune.bufsize"
9316
David du Colombier486df472011-03-17 10:40:26 +01009317server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009318 Declare a server in a backend
9319 May be used in sections : defaults | frontend | listen | backend
9320 no | no | yes | yes
9321 Arguments :
9322 <name> is the internal name assigned to this server. This name will
Davor Ocelice9ed2812017-12-25 17:49:28 +01009323 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05009324 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009325
David du Colombier486df472011-03-17 10:40:26 +01009326 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
9327 resolvable hostname is supported, but this name will be resolved
9328 during start-up. Address "0.0.0.0" or "*" has a special meaning.
9329 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02009330 address as the one from the client connection. This is useful in
9331 transparent proxy architectures where the client's connection is
9332 intercepted and haproxy must forward to the original destination
9333 address. This is more or less what the "transparent" keyword does
9334 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01009335 to report statistics. Optionally, an address family prefix may be
9336 used before the address to force the family regardless of the
9337 address format, which can be useful to specify a path to a unix
9338 socket with no slash ('/'). Currently supported prefixes are :
9339 - 'ipv4@' -> address is always IPv4
9340 - 'ipv6@' -> address is always IPv6
9341 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02009342 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemand2fe7dd02018-09-11 16:51:29 +02009343 - 'sockpair@' -> address is the FD of a connected unix
9344 socket or of a socketpair. During a connection, the
9345 backend creates a pair of connected sockets, and passes
9346 one of them over the FD. The bind part will use the
9347 received socket as the client FD. Should be used
9348 carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02009349 You may want to reference some environment variables in the
9350 address parameter, see section 2.3 about environment
Willy Tarreau6a031d12016-11-07 19:42:35 +01009351 variables. The "init-addr" setting can be used to modify the way
9352 IP addresses should be resolved upon startup.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009353
Willy Tarreaub6205fd2012-09-24 12:27:33 +02009354 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009355 be sent to this port. If unset, the same port the client
9356 connected to will be used. The port may also be prefixed by a "+"
9357 or a "-". In this case, the server's port will be determined by
9358 adding this value to the client's port.
9359
9360 <param*> is a list of parameters for this server. The "server" keywords
9361 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009362 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009363
9364 Examples :
9365 server first 10.1.1.1:1080 cookie first check inter 1000
9366 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01009367 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +02009368 server backup "${SRV_BACKUP}:1080" backup
9369 server www1_dc1 "${LAN_DC1}.101:80"
9370 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009371
Willy Tarreau55dcaf62015-09-27 15:03:15 +02009372 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
9373 sun_path length is used for the address length. Some other programs
9374 such as socat use the string length only by default. Pass the option
9375 ",unix-tightsocklen=0" to any abstract socket definition in socat to
9376 make it compatible with HAProxy's.
9377
Mark Lamourinec2247f02012-01-04 13:02:01 -05009378 See also: "default-server", "http-send-name-header" and section 5 about
9379 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009380
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02009381server-state-file-name [<file>]
9382 Set the server state file to read, load and apply to servers available in
9383 this backend. It only applies when the directive "load-server-state-from-file"
9384 is set to "local". When <file> is not provided or if this directive is not
9385 set, then backend name is used. If <file> starts with a slash '/', then it is
9386 considered as an absolute path. Otherwise, <file> is concatenated to the
9387 global directive "server-state-file-base".
9388
9389 Example: the minimal configuration below would make HAProxy look for the
9390 state server file '/etc/haproxy/states/bk':
9391
9392 global
9393 server-state-file-base /etc/haproxy/states
9394
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +01009395 backend bk
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02009396 load-server-state-from-file
9397
9398 See also: "server-state-file-base", "load-server-state-from-file", and
9399 "show servers state"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009400
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02009401server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
9402 Set a template to initialize servers with shared parameters.
9403 The names of these servers are built from <prefix> and <num | range> parameters.
9404 May be used in sections : defaults | frontend | listen | backend
9405 no | no | yes | yes
9406
9407 Arguments:
9408 <prefix> A prefix for the server names to be built.
9409
9410 <num | range>
9411 If <num> is provided, this template initializes <num> servers
9412 with 1 up to <num> as server name suffixes. A range of numbers
9413 <num_low>-<num_high> may also be used to use <num_low> up to
9414 <num_high> as server name suffixes.
9415
9416 <fqdn> A FQDN for all the servers this template initializes.
9417
9418 <port> Same meaning as "server" <port> argument (see "server" keyword).
9419
9420 <params*>
9421 Remaining server parameters among all those supported by "server"
9422 keyword.
9423
9424 Examples:
9425 # Initializes 3 servers with srv1, srv2 and srv3 as names,
9426 # google.com as FQDN, and health-check enabled.
9427 server-template srv 1-3 google.com:80 check
9428
9429 # or
9430 server-template srv 3 google.com:80 check
9431
9432 # would be equivalent to:
9433 server srv1 google.com:80 check
9434 server srv2 google.com:80 check
9435 server srv3 google.com:80 check
9436
9437
9438
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009439source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02009440source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01009441source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009442 Set the source address for outgoing connections
9443 May be used in sections : defaults | frontend | listen | backend
9444 yes | no | yes | yes
9445 Arguments :
9446 <addr> is the IPv4 address HAProxy will bind to before connecting to a
9447 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01009448
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009449 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01009450 the most appropriate address to reach its destination. Optionally
9451 an address family prefix may be used before the address to force
9452 the family regardless of the address format, which can be useful
9453 to specify a path to a unix socket with no slash ('/'). Currently
9454 supported prefixes are :
9455 - 'ipv4@' -> address is always IPv4
9456 - 'ipv6@' -> address is always IPv6
9457 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02009458 - 'abns@' -> address is in abstract namespace (Linux only)
Cyril Bonté307ee1e2015-09-28 23:16:06 +02009459 You may want to reference some environment variables in the
9460 address parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009461
9462 <port> is an optional port. It is normally not needed but may be useful
9463 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02009464 the system will select a free port. Note that port ranges are not
9465 supported in the backend. If you want to force port ranges, you
9466 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009467
9468 <addr2> is the IP address to present to the server when connections are
9469 forwarded in full transparent proxy mode. This is currently only
9470 supported on some patched Linux kernels. When this address is
9471 specified, clients connecting to the server will be presented
9472 with this address, while health checks will still use the address
9473 <addr>.
9474
9475 <port2> is the optional port to present to the server when connections
9476 are forwarded in full transparent proxy mode (see <addr2> above).
9477 The default value of zero means the system will select a free
9478 port.
9479
Willy Tarreaubce70882009-09-07 11:51:47 +02009480 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
9481 This is the name of a comma-separated header list which can
9482 contain multiple IP addresses. By default, the last occurrence is
9483 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01009484 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02009485 by previous proxy, typically Stunnel. In order to use another
9486 occurrence from the last one, please see the <occ> parameter
9487 below. When the header (or occurrence) is not found, no binding
9488 is performed so that the proxy's default IP address is used. Also
9489 keep in mind that the header name is case insensitive, as for any
9490 HTTP header.
9491
9492 <occ> is the occurrence number of a value to be used in a multi-value
9493 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04009494 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02009495 address. Positive values indicate a position from the first
9496 occurrence, 1 being the first one. Negative values indicate
9497 positions relative to the last one, -1 being the last one. This
9498 is helpful for situations where an X-Forwarded-For header is set
9499 at the entry point of an infrastructure and must be used several
9500 proxy layers away. When this value is not specified, -1 is
9501 assumed. Passing a zero here disables the feature.
9502
Willy Tarreaud53f96b2009-02-04 18:46:54 +01009503 <name> is an optional interface name to which to bind to for outgoing
9504 traffic. On systems supporting this features (currently, only
9505 Linux), this allows one to bind all traffic to the server to
9506 this interface even if it is not the one the system would select
9507 based on routing tables. This should be used with extreme care.
9508 Note that using this option requires root privileges.
9509
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009510 The "source" keyword is useful in complex environments where a specific
9511 address only is allowed to connect to the servers. It may be needed when a
9512 private address must be used through a public gateway for instance, and it is
9513 known that the system cannot determine the adequate source address by itself.
9514
9515 An extension which is available on certain patched Linux kernels may be used
9516 through the "usesrc" optional keyword. It makes it possible to connect to the
9517 servers with an IP address which does not belong to the system itself. This
9518 is called "full transparent proxy mode". For this to work, the destination
9519 servers have to route their traffic back to this address through the machine
9520 running HAProxy, and IP forwarding must generally be enabled on this machine.
9521
9522 In this "full transparent proxy" mode, it is possible to force a specific IP
9523 address to be presented to the servers. This is not much used in fact. A more
9524 common use is to tell HAProxy to present the client's IP address. For this,
9525 there are two methods :
9526
9527 - present the client's IP and port addresses. This is the most transparent
9528 mode, but it can cause problems when IP connection tracking is enabled on
9529 the machine, because a same connection may be seen twice with different
9530 states. However, this solution presents the huge advantage of not
9531 limiting the system to the 64k outgoing address+port couples, because all
9532 of the client ranges may be used.
9533
9534 - present only the client's IP address and select a spare port. This
9535 solution is still quite elegant but slightly less transparent (downstream
9536 firewalls logs will not match upstream's). It also presents the downside
9537 of limiting the number of concurrent connections to the usual 64k ports.
9538 However, since the upstream and downstream ports are different, local IP
9539 connection tracking on the machine will not be upset by the reuse of the
9540 same session.
9541
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009542 This option sets the default source for all servers in the backend. It may
9543 also be specified in a "defaults" section. Finer source address specification
9544 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009545 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009546
Baptiste Assmann91bd3372015-07-17 21:59:42 +02009547 In order to work, "usesrc" requires root privileges.
9548
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009549 Examples :
9550 backend private
9551 # Connect to the servers using our 192.168.1.200 source address
9552 source 192.168.1.200
9553
9554 backend transparent_ssl1
9555 # Connect to the SSL farm from the client's source address
9556 source 192.168.1.200 usesrc clientip
9557
9558 backend transparent_ssl2
9559 # Connect to the SSL farm from the client's source address and port
9560 # not recommended if IP conntrack is present on the local machine.
9561 source 192.168.1.200 usesrc client
9562
9563 backend transparent_ssl3
9564 # Connect to the SSL farm from the client's source address. It
9565 # is more conntrack-friendly.
9566 source 192.168.1.200 usesrc clientip
9567
9568 backend transparent_smtp
9569 # Connect to the SMTP farm from the client's source address/port
9570 # with Tproxy version 4.
9571 source 0.0.0.0 usesrc clientip
9572
Willy Tarreaubce70882009-09-07 11:51:47 +02009573 backend transparent_http
9574 # Connect to the servers using the client's IP as seen by previous
9575 # proxy.
9576 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
9577
Willy Tarreauc57f0e22009-05-10 13:12:33 +02009578 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009579 the Linux kernel on www.balabit.com, the "bind" keyword.
9580
Willy Tarreau844e3c52008-01-11 16:28:18 +01009581
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09009582srvtcpka-cnt <count>
9583 Sets the maximum number of keepalive probes TCP should send before dropping
9584 the connection on the server side.
9585 May be used in sections : defaults | frontend | listen | backend
9586 yes | no | yes | yes
9587 Arguments :
9588 <count> is the maximum number of keepalive probes.
9589
9590 This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword
9591 is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02009592 The availability of this setting depends on the operating system. It is
9593 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09009594
9595 See also : "option srvtcpka", "srvtcpka-idle", "srvtcpka-intvl".
9596
9597
9598srvtcpka-idle <timeout>
9599 Sets the time the connection needs to remain idle before TCP starts sending
9600 keepalive probes, if enabled the sending of TCP keepalive packets on the
9601 server side.
9602 May be used in sections : defaults | frontend | listen | backend
9603 yes | no | yes | yes
9604 Arguments :
9605 <timeout> is the time the connection needs to remain idle before TCP starts
9606 sending keepalive probes. It is specified in seconds by default,
9607 but can be in any other unit if the number is suffixed by the
9608 unit, as explained at the top of this document.
9609
9610 This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword
9611 is not specified, system-wide TCP parameter (tcp_keepalive_time) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02009612 The availability of this setting depends on the operating system. It is
9613 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09009614
9615 See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-intvl".
9616
9617
9618srvtcpka-intvl <timeout>
9619 Sets the time between individual keepalive probes on the server side.
9620 May be used in sections : defaults | frontend | listen | backend
9621 yes | no | yes | yes
9622 Arguments :
9623 <timeout> is the time between individual keepalive probes. It is specified
9624 in seconds by default, but can be in any other unit if the number
9625 is suffixed by the unit, as explained at the top of this
9626 document.
9627
9628 This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword
9629 is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used.
Willy Tarreau52543212020-07-09 05:58:51 +02009630 The availability of this setting depends on the operating system. It is
9631 known to work on Linux.
MIZUTA Takeshib24bc0d2020-07-09 11:13:20 +09009632
9633 See also : "option srvtcpka", "srvtcpka-cnt", "srvtcpka-idle".
9634
9635
Cyril Bonté66c327d2010-10-12 00:14:37 +02009636stats admin { if | unless } <cond>
9637 Enable statistics admin level if/unless a condition is matched
9638 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009639 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +02009640
9641 This statement enables the statistics admin level if/unless a condition is
9642 matched.
9643
9644 The admin level allows to enable/disable servers from the web interface. By
9645 default, statistics page is read-only for security reasons.
9646
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009647 Note : Consider not using this feature in multi-process mode (nbproc > 1)
9648 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009649 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009650
Cyril Bonté23b39d92011-02-10 22:54:44 +01009651 Currently, the POST request is limited to the buffer size minus the reserved
9652 buffer space, which means that if the list of servers is too long, the
9653 request won't be processed. It is recommended to alter few servers at a
9654 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02009655
9656 Example :
9657 # statistics admin level only for localhost
9658 backend stats_localhost
9659 stats enable
9660 stats admin if LOCALHOST
9661
9662 Example :
9663 # statistics admin level always enabled because of the authentication
9664 backend stats_auth
9665 stats enable
9666 stats auth admin:AdMiN123
9667 stats admin if TRUE
9668
9669 Example :
9670 # statistics admin level depends on the authenticated user
9671 userlist stats-auth
9672 group admin users admin
9673 user admin insecure-password AdMiN123
9674 group readonly users haproxy
9675 user haproxy insecure-password haproxy
9676
9677 backend stats_auth
9678 stats enable
9679 acl AUTH http_auth(stats-auth)
9680 acl AUTH_ADMIN http_auth_group(stats-auth) admin
9681 stats http-request auth unless AUTH
9682 stats admin if AUTH_ADMIN
9683
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009684 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
9685 "bind-process", section 3.4 about userlists and section 7 about
9686 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02009687
9688
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009689stats auth <user>:<passwd>
9690 Enable statistics with authentication and grant access to an account
9691 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009692 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009693 Arguments :
9694 <user> is a user name to grant access to
9695
9696 <passwd> is the cleartext password associated to this user
9697
9698 This statement enables statistics with default settings, and restricts access
9699 to declared users only. It may be repeated as many times as necessary to
9700 allow as many users as desired. When a user tries to access the statistics
9701 without a valid account, a "401 Forbidden" response will be returned so that
9702 the browser asks the user to provide a valid user and password. The real
9703 which will be returned to the browser is configurable using "stats realm".
9704
9705 Since the authentication method is HTTP Basic Authentication, the passwords
9706 circulate in cleartext on the network. Thus, it was decided that the
9707 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02009708 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009709
9710 It is also possible to reduce the scope of the proxies which appear in the
9711 report using "stats scope".
9712
9713 Though this statement alone is enough to enable statistics reporting, it is
9714 recommended to set all other settings in order to avoid relying on default
9715 unobvious parameters.
9716
9717 Example :
9718 # public access (limited to this backend only)
9719 backend public_www
9720 server srv1 192.168.0.1:80
9721 stats enable
9722 stats hide-version
9723 stats scope .
9724 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009725 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009726 stats auth admin1:AdMiN123
9727 stats auth admin2:AdMiN321
9728
9729 # internal monitoring access (unlimited)
9730 backend private_monitoring
9731 stats enable
9732 stats uri /admin?stats
9733 stats refresh 5s
9734
9735 See also : "stats enable", "stats realm", "stats scope", "stats uri"
9736
9737
9738stats enable
9739 Enable statistics reporting with default settings
9740 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009741 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009742 Arguments : none
9743
9744 This statement enables statistics reporting with default settings defined
9745 at build time. Unless stated otherwise, these settings are used :
9746 - stats uri : /haproxy?stats
9747 - stats realm : "HAProxy Statistics"
9748 - stats auth : no authentication
9749 - stats scope : no restriction
9750
9751 Though this statement alone is enough to enable statistics reporting, it is
9752 recommended to set all other settings in order to avoid relying on default
9753 unobvious parameters.
9754
9755 Example :
9756 # public access (limited to this backend only)
9757 backend public_www
9758 server srv1 192.168.0.1:80
9759 stats enable
9760 stats hide-version
9761 stats scope .
9762 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009763 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009764 stats auth admin1:AdMiN123
9765 stats auth admin2:AdMiN321
9766
9767 # internal monitoring access (unlimited)
9768 backend private_monitoring
9769 stats enable
9770 stats uri /admin?stats
9771 stats refresh 5s
9772
9773 See also : "stats auth", "stats realm", "stats uri"
9774
9775
Willy Tarreaud63335a2010-02-26 12:56:52 +01009776stats hide-version
9777 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009778 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009779 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01009780 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009781
Willy Tarreaud63335a2010-02-26 12:56:52 +01009782 By default, the stats page reports some useful status information along with
9783 the statistics. Among them is HAProxy's version. However, it is generally
9784 considered dangerous to report precise version to anyone, as it can help them
9785 target known weaknesses with specific attacks. The "stats hide-version"
9786 statement removes the version from the statistics report. This is recommended
9787 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009788
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02009789 Though this statement alone is enough to enable statistics reporting, it is
9790 recommended to set all other settings in order to avoid relying on default
9791 unobvious parameters.
9792
Willy Tarreaud63335a2010-02-26 12:56:52 +01009793 Example :
9794 # public access (limited to this backend only)
9795 backend public_www
9796 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02009797 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01009798 stats hide-version
9799 stats scope .
9800 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009801 stats realm HAProxy\ Statistics
Willy Tarreaud63335a2010-02-26 12:56:52 +01009802 stats auth admin1:AdMiN123
9803 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009804
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009805 # internal monitoring access (unlimited)
9806 backend private_monitoring
9807 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01009808 stats uri /admin?stats
9809 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01009810
Willy Tarreaud63335a2010-02-26 12:56:52 +01009811 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009812
Willy Tarreau983e01e2010-01-11 18:42:06 +01009813
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02009814stats http-request { allow | deny | auth [realm <realm>] }
9815 [ { if | unless } <condition> ]
9816 Access control for statistics
9817
9818 May be used in sections: defaults | frontend | listen | backend
9819 no | no | yes | yes
9820
9821 As "http-request", these set of options allow to fine control access to
9822 statistics. Each option may be followed by if/unless and acl.
9823 First option with matched condition (or option without condition) is final.
9824 For "deny" a 403 error will be returned, for "allow" normal processing is
9825 performed, for "auth" a 401/407 error code is returned so the client
9826 should be asked to enter a username and password.
9827
9828 There is no fixed limit to the number of http-request statements per
9829 instance.
9830
9831 See also : "http-request", section 3.4 about userlists and section 7
9832 about ACL usage.
9833
9834
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009835stats realm <realm>
9836 Enable statistics and set authentication realm
9837 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009838 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009839 Arguments :
9840 <realm> is the name of the HTTP Basic Authentication realm reported to
9841 the browser. The browser uses it to display it in the pop-up
9842 inviting the user to enter a valid username and password.
9843
9844 The realm is read as a single word, so any spaces in it should be escaped
9845 using a backslash ('\').
9846
9847 This statement is useful only in conjunction with "stats auth" since it is
9848 only related to authentication.
9849
9850 Though this statement alone is enough to enable statistics reporting, it is
9851 recommended to set all other settings in order to avoid relying on default
9852 unobvious parameters.
9853
9854 Example :
9855 # public access (limited to this backend only)
9856 backend public_www
9857 server srv1 192.168.0.1:80
9858 stats enable
9859 stats hide-version
9860 stats scope .
9861 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009862 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009863 stats auth admin1:AdMiN123
9864 stats auth admin2:AdMiN321
9865
9866 # internal monitoring access (unlimited)
9867 backend private_monitoring
9868 stats enable
9869 stats uri /admin?stats
9870 stats refresh 5s
9871
9872 See also : "stats auth", "stats enable", "stats uri"
9873
9874
9875stats refresh <delay>
9876 Enable statistics with automatic refresh
9877 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009878 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009879 Arguments :
9880 <delay> is the suggested refresh delay, specified in seconds, which will
9881 be returned to the browser consulting the report page. While the
9882 browser is free to apply any delay, it will generally respect it
9883 and refresh the page this every seconds. The refresh interval may
9884 be specified in any other non-default time unit, by suffixing the
9885 unit after the value, as explained at the top of this document.
9886
9887 This statement is useful on monitoring displays with a permanent page
9888 reporting the load balancer's activity. When set, the HTML report page will
9889 include a link "refresh"/"stop refresh" so that the user can select whether
Jackie Tapia749f74c2020-07-22 18:59:40 -05009890 they want automatic refresh of the page or not.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009891
9892 Though this statement alone is enough to enable statistics reporting, it is
9893 recommended to set all other settings in order to avoid relying on default
9894 unobvious parameters.
9895
9896 Example :
9897 # public access (limited to this backend only)
9898 backend public_www
9899 server srv1 192.168.0.1:80
9900 stats enable
9901 stats hide-version
9902 stats scope .
9903 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009904 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009905 stats auth admin1:AdMiN123
9906 stats auth admin2:AdMiN321
9907
9908 # internal monitoring access (unlimited)
9909 backend private_monitoring
9910 stats enable
9911 stats uri /admin?stats
9912 stats refresh 5s
9913
9914 See also : "stats auth", "stats enable", "stats realm", "stats uri"
9915
9916
9917stats scope { <name> | "." }
9918 Enable statistics and limit access scope
9919 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009920 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009921 Arguments :
9922 <name> is the name of a listen, frontend or backend section to be
9923 reported. The special name "." (a single dot) designates the
9924 section in which the statement appears.
9925
9926 When this statement is specified, only the sections enumerated with this
9927 statement will appear in the report. All other ones will be hidden. This
9928 statement may appear as many times as needed if multiple sections need to be
9929 reported. Please note that the name checking is performed as simple string
9930 comparisons, and that it is never checked that a give section name really
9931 exists.
9932
9933 Though this statement alone is enough to enable statistics reporting, it is
9934 recommended to set all other settings in order to avoid relying on default
9935 unobvious parameters.
9936
9937 Example :
9938 # public access (limited to this backend only)
9939 backend public_www
9940 server srv1 192.168.0.1:80
9941 stats enable
9942 stats hide-version
9943 stats scope .
9944 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009945 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009946 stats auth admin1:AdMiN123
9947 stats auth admin2:AdMiN321
9948
9949 # internal monitoring access (unlimited)
9950 backend private_monitoring
9951 stats enable
9952 stats uri /admin?stats
9953 stats refresh 5s
9954
9955 See also : "stats auth", "stats enable", "stats realm", "stats uri"
9956
Willy Tarreaud63335a2010-02-26 12:56:52 +01009957
Willy Tarreauc9705a12010-07-27 20:05:50 +02009958stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01009959 Enable reporting of a description on the statistics page.
9960 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009961 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01009962
Willy Tarreauc9705a12010-07-27 20:05:50 +02009963 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01009964 description from global section is automatically used instead.
9965
9966 This statement is useful for users that offer shared services to their
9967 customers, where node or description should be different for each customer.
9968
9969 Though this statement alone is enough to enable statistics reporting, it is
9970 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01009971 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009972
9973 Example :
9974 # internal monitoring access (unlimited)
9975 backend private_monitoring
9976 stats enable
9977 stats show-desc Master node for Europe, Asia, Africa
9978 stats uri /admin?stats
9979 stats refresh 5s
9980
9981 See also: "show-node", "stats enable", "stats uri" and "description" in
9982 global section.
9983
9984
9985stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +02009986 Enable reporting additional information on the statistics page
9987 May be used in sections : defaults | frontend | listen | backend
9988 yes | yes | yes | yes
9989 Arguments : none
9990
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009991 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +01009992 - cap: capabilities (proxy)
9993 - mode: one of tcp, http or health (proxy)
9994 - id: SNMP ID (proxy, socket, server)
9995 - IP (socket, server)
9996 - cookie (backend, server)
9997
9998 Though this statement alone is enough to enable statistics reporting, it is
9999 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +010010000 unobvious parameters. Default behavior is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010001
10002 See also: "stats enable", "stats uri".
10003
10004
10005stats show-node [ <name> ]
10006 Enable reporting of a host name on the statistics page.
10007 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010008 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +010010009 Arguments:
10010 <name> is an optional name to be reported. If unspecified, the
10011 node name from global section is automatically used instead.
10012
10013 This statement is useful for users that offer shared services to their
10014 customers, where node or description might be different on a stats page
Davor Ocelice9ed2812017-12-25 17:49:28 +010010015 provided for each customer. Default behavior is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +010010016
10017 Though this statement alone is enough to enable statistics reporting, it is
10018 recommended to set all other settings in order to avoid relying on default
10019 unobvious parameters.
10020
10021 Example:
10022 # internal monitoring access (unlimited)
10023 backend private_monitoring
10024 stats enable
10025 stats show-node Europe-1
10026 stats uri /admin?stats
10027 stats refresh 5s
10028
10029 See also: "show-desc", "stats enable", "stats uri", and "node" in global
10030 section.
10031
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010032
10033stats uri <prefix>
10034 Enable statistics and define the URI prefix to access them
10035 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +020010036 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010037 Arguments :
10038 <prefix> is the prefix of any URI which will be redirected to stats. This
10039 prefix may contain a question mark ('?') to indicate part of a
10040 query string.
10041
10042 The statistics URI is intercepted on the relayed traffic, so it appears as a
10043 page within the normal application. It is strongly advised to ensure that the
10044 selected URI will never appear in the application, otherwise it will never be
10045 possible to reach it in the application.
10046
10047 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010048 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010049 It is generally a good idea to include a question mark in the URI so that
10050 intermediate proxies refrain from caching the results. Also, since any string
10051 beginning with the prefix will be accepted as a stats request, the question
10052 mark helps ensuring that no valid URI will begin with the same words.
10053
10054 It is sometimes very convenient to use "/" as the URI prefix, and put that
10055 statement in a "listen" instance of its own. That makes it easy to dedicate
10056 an address or a port to statistics only.
10057
10058 Though this statement alone is enough to enable statistics reporting, it is
10059 recommended to set all other settings in order to avoid relying on default
10060 unobvious parameters.
10061
10062 Example :
10063 # public access (limited to this backend only)
10064 backend public_www
10065 server srv1 192.168.0.1:80
10066 stats enable
10067 stats hide-version
10068 stats scope .
10069 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +010010070 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010071 stats auth admin1:AdMiN123
10072 stats auth admin2:AdMiN321
10073
10074 # internal monitoring access (unlimited)
10075 backend private_monitoring
10076 stats enable
10077 stats uri /admin?stats
10078 stats refresh 5s
10079
10080 See also : "stats auth", "stats enable", "stats realm"
10081
10082
Willy Tarreaud63335a2010-02-26 12:56:52 +010010083stick match <pattern> [table <table>] [{if | unless} <cond>]
10084 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +010010085 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +010010086 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010087
10088 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020010089 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010090 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +010010091 will be analyzed in the hope to find a matching entry in a
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010092 stickiness table. This rule is mandatory.
10093
10094 <table> is an optional stickiness table name. If unspecified, the same
10095 backend's table is used. A stickiness table is declared using
10096 the "stick-table" statement.
10097
10098 <cond> is an optional matching condition. It makes it possible to match
10099 on a certain criterion only when other conditions are met (or
10100 not met). For instance, it could be used to match on a source IP
10101 address except when a request passes through a known proxy, in
10102 which case we'd match on a header containing that IP address.
10103
10104 Some protocols or applications require complex stickiness rules and cannot
10105 always simply rely on cookies nor hashing. The "stick match" statement
10106 describes a rule to extract the stickiness criterion from an incoming request
10107 or connection. See section 7 for a complete list of possible patterns and
10108 transformation rules.
10109
10110 The table has to be declared using the "stick-table" statement. It must be of
10111 a type compatible with the pattern. By default it is the one which is present
10112 in the same backend. It is possible to share a table with other backends by
10113 referencing it using the "table" keyword. If another table is referenced,
10114 the server's ID inside the backends are used. By default, all server IDs
10115 start at 1 in each backend, so the server ordering is enough. But in case of
10116 doubt, it is highly recommended to force server IDs using their "id" setting.
10117
10118 It is possible to restrict the conditions where a "stick match" statement
10119 will apply, using "if" or "unless" followed by a condition. See section 7 for
10120 ACL based conditions.
10121
10122 There is no limit on the number of "stick match" statements. The first that
10123 applies and matches will cause the request to be directed to the same server
10124 as was used for the request which created the entry. That way, multiple
10125 matches can be used as fallbacks.
10126
10127 The stick rules are checked after the persistence cookies, so they will not
10128 affect stickiness if a cookie has already been used to select a server. That
10129 way, it becomes very easy to insert cookies and match on IP addresses in
10130 order to maintain stickiness between HTTP and HTTPS.
10131
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010132 Note : Consider not using this feature in multi-process mode (nbproc > 1)
10133 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010010134 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010135
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010136 Example :
10137 # forward SMTP users to the same server they just used for POP in the
10138 # last 30 minutes
10139 backend pop
10140 mode tcp
10141 balance roundrobin
10142 stick store-request src
10143 stick-table type ip size 200k expire 30m
10144 server s1 192.168.1.1:110
10145 server s2 192.168.1.1:110
10146
10147 backend smtp
10148 mode tcp
10149 balance roundrobin
10150 stick match src table pop
10151 server s1 192.168.1.1:25
10152 server s2 192.168.1.1:25
10153
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010154 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +020010155 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010156
10157
10158stick on <pattern> [table <table>] [{if | unless} <condition>]
10159 Define a request pattern to associate a user to a server
10160 May be used in sections : defaults | frontend | listen | backend
10161 no | no | yes | yes
10162
10163 Note : This form is exactly equivalent to "stick match" followed by
10164 "stick store-request", all with the same arguments. Please refer
10165 to both keywords for details. It is only provided as a convenience
10166 for writing more maintainable configurations.
10167
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010168 Note : Consider not using this feature in multi-process mode (nbproc > 1)
10169 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010010170 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010171
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010172 Examples :
10173 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +010010174 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010175
10176 # ...is strictly equivalent to this one :
10177 stick match src table pop if !localhost
10178 stick store-request src table pop if !localhost
10179
10180
10181 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
10182 # well as HTTP without cookie. Share the same table between both accesses.
10183 backend http
10184 mode http
10185 balance roundrobin
10186 stick on src table https
10187 cookie SRV insert indirect nocache
10188 server s1 192.168.1.1:80 cookie s1
10189 server s2 192.168.1.1:80 cookie s2
10190
10191 backend https
10192 mode tcp
10193 balance roundrobin
10194 stick-table type ip size 200k expire 30m
10195 stick on src
10196 server s1 192.168.1.1:443
10197 server s2 192.168.1.1:443
10198
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010199 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010200
10201
10202stick store-request <pattern> [table <table>] [{if | unless} <condition>]
10203 Define a request pattern used to create an entry in a stickiness table
10204 May be used in sections : defaults | frontend | listen | backend
10205 no | no | yes | yes
10206
10207 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020010208 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010209 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +010010210 will be analyzed, extracted and stored in the table once a
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010211 server is selected.
10212
10213 <table> is an optional stickiness table name. If unspecified, the same
10214 backend's table is used. A stickiness table is declared using
10215 the "stick-table" statement.
10216
10217 <cond> is an optional storage condition. It makes it possible to store
10218 certain criteria only when some conditions are met (or not met).
10219 For instance, it could be used to store the source IP address
10220 except when the request passes through a known proxy, in which
10221 case we'd store a converted form of a header containing that IP
10222 address.
10223
10224 Some protocols or applications require complex stickiness rules and cannot
10225 always simply rely on cookies nor hashing. The "stick store-request" statement
10226 describes a rule to decide what to extract from the request and when to do
10227 it, in order to store it into a stickiness table for further requests to
10228 match it using the "stick match" statement. Obviously the extracted part must
10229 make sense and have a chance to be matched in a further request. Storing a
10230 client's IP address for instance often makes sense. Storing an ID found in a
10231 URL parameter also makes sense. Storing a source port will almost never make
10232 any sense because it will be randomly matched. See section 7 for a complete
10233 list of possible patterns and transformation rules.
10234
10235 The table has to be declared using the "stick-table" statement. It must be of
10236 a type compatible with the pattern. By default it is the one which is present
10237 in the same backend. It is possible to share a table with other backends by
10238 referencing it using the "table" keyword. If another table is referenced,
10239 the server's ID inside the backends are used. By default, all server IDs
10240 start at 1 in each backend, so the server ordering is enough. But in case of
10241 doubt, it is highly recommended to force server IDs using their "id" setting.
10242
10243 It is possible to restrict the conditions where a "stick store-request"
10244 statement will apply, using "if" or "unless" followed by a condition. This
10245 condition will be evaluated while parsing the request, so any criteria can be
10246 used. See section 7 for ACL based conditions.
10247
10248 There is no limit on the number of "stick store-request" statements, but
10249 there is a limit of 8 simultaneous stores per request or response. This
10250 makes it possible to store up to 8 criteria, all extracted from either the
10251 request or the response, regardless of the number of rules. Only the 8 first
10252 ones which match will be kept. Using this, it is possible to feed multiple
10253 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +010010254 another protocol or access method. Using multiple store-request rules with
10255 the same table is possible and may be used to find the best criterion to rely
10256 on, by arranging the rules by decreasing preference order. Only the first
10257 extracted criterion for a given table will be stored. All subsequent store-
10258 request rules referencing the same table will be skipped and their ACLs will
10259 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010260
10261 The "store-request" rules are evaluated once the server connection has been
10262 established, so that the table will contain the real server that processed
10263 the request.
10264
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010265 Note : Consider not using this feature in multi-process mode (nbproc > 1)
10266 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +010010267 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010268
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010269 Example :
10270 # forward SMTP users to the same server they just used for POP in the
10271 # last 30 minutes
10272 backend pop
10273 mode tcp
10274 balance roundrobin
10275 stick store-request src
10276 stick-table type ip size 200k expire 30m
10277 server s1 192.168.1.1:110
10278 server s2 192.168.1.1:110
10279
10280 backend smtp
10281 mode tcp
10282 balance roundrobin
10283 stick match src table pop
10284 server s1 192.168.1.1:25
10285 server s2 192.168.1.1:25
10286
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010287 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +020010288 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010289
10290
Emeric Brun7c6b82e2010-09-24 16:34:28 +020010291stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +020010292 size <size> [expire <expire>] [nopurge] [peers <peersect>]
10293 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +080010294 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010295 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +020010296 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010297
10298 Arguments :
10299 ip a table declared with "type ip" will only store IPv4 addresses.
10300 This form is very compact (about 50 bytes per entry) and allows
10301 very fast entry lookup and stores with almost no overhead. This
10302 is mainly used to store client source IP addresses.
10303
David du Colombier9a6d3c92011-03-17 10:40:24 +010010304 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
10305 This form is very compact (about 60 bytes per entry) and allows
10306 very fast entry lookup and stores with almost no overhead. This
10307 is mainly used to store client source IP addresses.
10308
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010309 integer a table declared with "type integer" will store 32bit integers
10310 which can represent a client identifier found in a request for
10311 instance.
10312
10313 string a table declared with "type string" will store substrings of up
10314 to <len> characters. If the string provided by the pattern
10315 extractor is larger than <len>, it will be truncated before
10316 being stored. During matching, at most <len> characters will be
10317 compared between the string in the table and the extracted
10318 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +020010319 to 32 characters.
10320
10321 binary a table declared with "type binary" will store binary blocks
10322 of <len> bytes. If the block provided by the pattern
10323 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +020010324 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +020010325 is shorter than <len>, it will be padded by 0. When not
10326 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010327
10328 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +020010329 "string" type table (See type "string" above). Or the number
10330 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010331 changing this parameter as memory usage will proportionally
10332 increase.
10333
10334 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +010010335 value directly impacts memory usage. Count approximately
10336 50 bytes per entry, plus the size of a string if any. The size
10337 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010338
10339 [nopurge] indicates that we refuse to purge older entries when the table
10340 is full. When not specified and the table is full when haproxy
10341 wants to store an entry in it, it will flush a few of the oldest
10342 entries in order to release some space for the new ones. This is
Davor Ocelice9ed2812017-12-25 17:49:28 +010010343 most often the desired behavior. In some specific cases, it
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010344 be desirable to refuse new entries instead of purging the older
10345 ones. That may be the case when the amount of data to store is
10346 far above the hardware limits and we prefer not to offer access
10347 to new clients than to reject the ones already connected. When
10348 using this parameter, be sure to properly set the "expire"
10349 parameter (see below).
10350
Emeric Brunf099e792010-09-27 12:05:28 +020010351 <peersect> is the name of the peers section to use for replication. Entries
10352 which associate keys to server IDs are kept synchronized with
10353 the remote peers declared in this section. All entries are also
10354 automatically learned from the local peer (old process) during a
10355 soft restart.
10356
Willy Tarreau1abc6732015-05-01 19:21:02 +020010357 NOTE : each peers section may be referenced only by tables
10358 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +010010359
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010360 <expire> defines the maximum duration of an entry in the table since it
10361 was last created, refreshed or matched. The expiration delay is
10362 defined using the standard time format, similarly as the various
10363 timeouts. The maximum duration is slightly above 24 days. See
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +030010364 section 2.4 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +020010365 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010366 be removed once full. Be sure not to use the "nopurge" parameter
10367 if not expiration delay is specified.
10368
Willy Tarreau08d5f982010-06-06 13:34:54 +020010369 <data_type> is used to store additional information in the stick-table. This
10370 may be used by ACLs in order to control various criteria related
10371 to the activity of the client matching the stick-table. For each
10372 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +020010373 that the additional data can fit. Several data types may be
10374 stored with an entry. Multiple data types may be specified after
10375 the "store" keyword, as a comma-separated list. Alternatively,
10376 it is possible to repeat the "store" keyword followed by one or
10377 several data types. Except for the "server_id" type which is
10378 automatically detected and enabled, all data types must be
10379 explicitly declared to be stored. If an ACL references a data
10380 type which is not stored, the ACL will simply not match. Some
10381 data types require an argument which must be passed just after
10382 the type between parenthesis. See below for the supported data
10383 types and their arguments.
10384
10385 The data types that can be stored with an entry are the following :
10386 - server_id : this is an integer which holds the numeric ID of the server a
10387 request was assigned to. It is used by the "stick match", "stick store",
10388 and "stick on" rules. It is automatically enabled when referenced.
10389
10390 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
10391 integer which may be used for anything. Most of the time it will be used
10392 to put a special tag on some entries, for instance to note that a
Davor Ocelice9ed2812017-12-25 17:49:28 +010010393 specific behavior was detected and must be known for future matches.
Willy Tarreauc9705a12010-07-27 20:05:50 +020010394
Willy Tarreauba2ffd12013-05-29 15:54:14 +020010395 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
10396 over a period. It is a positive 32-bit integer integer which may be used
10397 for anything. Just like <gpc0>, it counts events, but instead of keeping
Davor Ocelice9ed2812017-12-25 17:49:28 +010010398 a cumulative number, it maintains the rate at which the counter is
Willy Tarreauba2ffd12013-05-29 15:54:14 +020010399 incremented. Most of the time it will be used to measure the frequency of
Davor Ocelice9ed2812017-12-25 17:49:28 +010010400 occurrence of certain events (e.g. requests to a specific URL).
Willy Tarreauba2ffd12013-05-29 15:54:14 +020010401
Frédéric Lécaille6778b272018-01-29 15:22:53 +010010402 - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
10403 integer which may be used for anything. Most of the time it will be used
10404 to put a special tag on some entries, for instance to note that a
10405 specific behavior was detected and must be known for future matches.
10406
10407 - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
10408 over a period. It is a positive 32-bit integer integer which may be used
10409 for anything. Just like <gpc1>, it counts events, but instead of keeping
10410 a cumulative number, it maintains the rate at which the counter is
10411 incremented. Most of the time it will be used to measure the frequency of
10412 occurrence of certain events (e.g. requests to a specific URL).
10413
Willy Tarreauc9705a12010-07-27 20:05:50 +020010414 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
10415 the absolute number of connections received from clients which matched
10416 this entry. It does not mean the connections were accepted, just that
10417 they were received.
10418
10419 - conn_cur : Current Connections. It is a positive 32-bit integer which
10420 stores the concurrent connection counts for the entry. It is incremented
10421 once an incoming connection matches the entry, and decremented once the
10422 connection leaves. That way it is possible to know at any time the exact
10423 number of concurrent connections for an entry.
10424
10425 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
10426 integer parameter <period> which indicates in milliseconds the length
10427 of the period over which the average is measured. It reports the average
10428 incoming connection rate over that period, in connections per period. The
10429 result is an integer which can be matched using ACLs.
10430
10431 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
10432 the absolute number of sessions received from clients which matched this
10433 entry. A session is a connection that was accepted by the layer 4 rules.
10434
10435 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
10436 integer parameter <period> which indicates in milliseconds the length
10437 of the period over which the average is measured. It reports the average
10438 incoming session rate over that period, in sessions per period. The
10439 result is an integer which can be matched using ACLs.
10440
10441 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
10442 counts the absolute number of HTTP requests received from clients which
10443 matched this entry. It does not matter whether they are valid requests or
10444 not. Note that this is different from sessions when keep-alive is used on
10445 the client side.
10446
10447 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
10448 integer parameter <period> which indicates in milliseconds the length
10449 of the period over which the average is measured. It reports the average
10450 HTTP request rate over that period, in requests per period. The result is
10451 an integer which can be matched using ACLs. It does not matter whether
10452 they are valid requests or not. Note that this is different from sessions
10453 when keep-alive is used on the client side.
10454
10455 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
10456 counts the absolute number of HTTP requests errors induced by clients
10457 which matched this entry. Errors are counted on invalid and truncated
10458 requests, as well as on denied or tarpitted requests, and on failed
10459 authentications. If the server responds with 4xx, then the request is
10460 also counted as an error since it's an error triggered by the client
Davor Ocelice9ed2812017-12-25 17:49:28 +010010461 (e.g. vulnerability scan).
Willy Tarreauc9705a12010-07-27 20:05:50 +020010462
10463 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
10464 integer parameter <period> which indicates in milliseconds the length
10465 of the period over which the average is measured. It reports the average
10466 HTTP request error rate over that period, in requests per period (see
10467 http_err_cnt above for what is accounted as an error). The result is an
10468 integer which can be matched using ACLs.
10469
10470 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +010010471 integer which counts the cumulative number of bytes received from clients
Willy Tarreauc9705a12010-07-27 20:05:50 +020010472 which matched this entry. Headers are included in the count. This may be
10473 used to limit abuse of upload features on photo or video servers.
10474
10475 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
10476 integer parameter <period> which indicates in milliseconds the length
10477 of the period over which the average is measured. It reports the average
10478 incoming bytes rate over that period, in bytes per period. It may be used
10479 to detect users which upload too much and too fast. Warning: with large
10480 uploads, it is possible that the amount of uploaded data will be counted
10481 once upon termination, thus causing spikes in the average transfer speed
10482 instead of having a smooth one. This may partially be smoothed with
10483 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
10484 recommended for better fairness.
10485
10486 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +010010487 integer which counts the cumulative number of bytes sent to clients which
Willy Tarreauc9705a12010-07-27 20:05:50 +020010488 matched this entry. Headers are included in the count. This may be used
10489 to limit abuse of bots sucking the whole site.
10490
10491 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
10492 an integer parameter <period> which indicates in milliseconds the length
10493 of the period over which the average is measured. It reports the average
10494 outgoing bytes rate over that period, in bytes per period. It may be used
10495 to detect users which download too much and too fast. Warning: with large
10496 transfers, it is possible that the amount of transferred data will be
10497 counted once upon termination, thus causing spikes in the average
10498 transfer speed instead of having a smooth one. This may partially be
10499 smoothed with "option contstats" though this is not perfect yet. Use of
10500 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +020010501
Willy Tarreauc00cdc22010-06-06 16:48:26 +020010502 There is only one stick-table per proxy. At the moment of writing this doc,
10503 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010504 to be required, simply create a dummy backend with a stick-table in it and
10505 reference it.
10506
10507 It is important to understand that stickiness based on learning information
10508 has some limitations, including the fact that all learned associations are
Baptiste Assmann123ff042016-03-06 23:29:28 +010010509 lost upon restart unless peers are properly configured to transfer such
10510 information upon restart (recommended). In general it can be good as a
10511 complement but not always as an exclusive stickiness.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010512
Willy Tarreauc9705a12010-07-27 20:05:50 +020010513 Last, memory requirements may be important when storing many data types.
10514 Indeed, storing all indicators above at once in each entry requires 116 bytes
10515 per entry, or 116 MB for a 1-million entries table. This is definitely not
10516 something that can be ignored.
10517
10518 Example:
10519 # Keep track of counters of up to 1 million IP addresses over 5 minutes
10520 # and store a general purpose counter and the average connection rate
10521 # computed over a sliding window of 30 seconds.
10522 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
10523
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +030010524 See also : "stick match", "stick on", "stick store-request", section 2.4
David du Colombiera13d1b92011-03-17 10:40:22 +010010525 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +010010526
10527
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010528stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Baptiste Assmann2f2d2ec2016-03-06 23:27:24 +010010529 Define a response pattern used to create an entry in a stickiness table
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010530 May be used in sections : defaults | frontend | listen | backend
10531 no | no | yes | yes
10532
10533 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020010534 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010535 describes what elements of the response or connection will
Davor Ocelice9ed2812017-12-25 17:49:28 +010010536 be analyzed, extracted and stored in the table once a
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010537 server is selected.
10538
10539 <table> is an optional stickiness table name. If unspecified, the same
10540 backend's table is used. A stickiness table is declared using
10541 the "stick-table" statement.
10542
10543 <cond> is an optional storage condition. It makes it possible to store
10544 certain criteria only when some conditions are met (or not met).
10545 For instance, it could be used to store the SSL session ID only
10546 when the response is a SSL server hello.
10547
10548 Some protocols or applications require complex stickiness rules and cannot
10549 always simply rely on cookies nor hashing. The "stick store-response"
10550 statement describes a rule to decide what to extract from the response and
10551 when to do it, in order to store it into a stickiness table for further
10552 requests to match it using the "stick match" statement. Obviously the
10553 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010554 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010555 See section 7 for a complete list of possible patterns and transformation
10556 rules.
10557
10558 The table has to be declared using the "stick-table" statement. It must be of
10559 a type compatible with the pattern. By default it is the one which is present
10560 in the same backend. It is possible to share a table with other backends by
10561 referencing it using the "table" keyword. If another table is referenced,
10562 the server's ID inside the backends are used. By default, all server IDs
10563 start at 1 in each backend, so the server ordering is enough. But in case of
10564 doubt, it is highly recommended to force server IDs using their "id" setting.
10565
10566 It is possible to restrict the conditions where a "stick store-response"
10567 statement will apply, using "if" or "unless" followed by a condition. This
10568 condition will be evaluated while parsing the response, so any criteria can
10569 be used. See section 7 for ACL based conditions.
10570
10571 There is no limit on the number of "stick store-response" statements, but
10572 there is a limit of 8 simultaneous stores per request or response. This
10573 makes it possible to store up to 8 criteria, all extracted from either the
10574 request or the response, regardless of the number of rules. Only the 8 first
10575 ones which match will be kept. Using this, it is possible to feed multiple
10576 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +010010577 another protocol or access method. Using multiple store-response rules with
10578 the same table is possible and may be used to find the best criterion to rely
10579 on, by arranging the rules by decreasing preference order. Only the first
10580 extracted criterion for a given table will be stored. All subsequent store-
10581 response rules referencing the same table will be skipped and their ACLs will
10582 not be evaluated. However, even if a store-request rule references a table, a
10583 store-response rule may also use the same table. This means that each table
10584 may learn exactly one element from the request and one element from the
10585 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010586
10587 The table will contain the real server that processed the request.
10588
10589 Example :
10590 # Learn SSL session ID from both request and response and create affinity.
10591 backend https
10592 mode tcp
10593 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +020010594 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010595 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010596
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010597 acl clienthello req_ssl_hello_type 1
10598 acl serverhello rep_ssl_hello_type 2
10599
10600 # use tcp content accepts to detects ssl client and server hello.
10601 tcp-request inspect-delay 5s
10602 tcp-request content accept if clienthello
10603
10604 # no timeout on response inspect delay by default.
10605 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +020010606
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010607 # SSL session ID (SSLID) may be present on a client or server hello.
10608 # Its length is coded on 1 byte at offset 43 and its value starts
10609 # at offset 44.
10610
10611 # Match and learn on request if client hello.
10612 stick on payload_lv(43,1) if clienthello
10613
10614 # Learn on response if server hello.
10615 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +020010616
Emeric Brun6a1cefa2010-09-24 18:15:17 +020010617 server s1 192.168.1.1:443
10618 server s2 192.168.1.1:443
10619
10620 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
10621 extraction.
10622
10623
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010624tcp-check comment <string>
10625 Defines a comment for the following the tcp-check rule, reported in logs if
10626 it fails.
10627 May be used in sections : defaults | frontend | listen | backend
10628 yes | no | yes | yes
10629
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010630 Arguments :
10631 <string> is the comment message to add in logs if the following tcp-check
10632 rule fails.
10633
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010634 It only works for connect, send and expect rules. It is useful to make
10635 user-friendly error reporting.
10636
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010637 See also : "option tcp-check", "tcp-check connect", "tcp-check send" and
10638 "tcp-check expect".
10639
10640
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010641tcp-check connect [default] [port <expr>] [addr <ip>] [send-proxy] [via-socks4]
10642 [ssl] [sni <sni>] [alpn <alpn>] [linger]
Christopher Fauletedc6ed92020-04-23 16:27:59 +020010643 [proto <name>] [comment <msg>]
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010644 Opens a new connection
10645 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020010646 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010647
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010648 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010649 comment <msg> defines a message to report if the rule evaluation fails.
10650
Christopher Faulet4dce5922020-03-30 13:54:42 +020010651 default Use default options of the server line to do the health
Daniel Corbett67a82712020-07-06 23:01:19 -040010652 checks. The server options are used only if not redefined.
Christopher Faulet4dce5922020-03-30 13:54:42 +020010653
Christopher Fauletb7d30092020-03-30 15:19:03 +020010654 port <expr> if not set, check port or server port is used.
Christopher Faulet5c288742020-03-31 08:15:58 +020010655 It tells HAProxy where to open the connection to.
10656 <port> must be a valid TCP port source integer, from 1 to
Christopher Fauletb7d30092020-03-30 15:19:03 +020010657 65535 or an sample-fetch expression.
Christopher Faulet5c288742020-03-31 08:15:58 +020010658
10659 addr <ip> defines the IP address to do the health check.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010660
10661 send-proxy send a PROXY protocol string
10662
Christopher Faulet085426a2020-03-30 13:07:02 +020010663 via-socks4 enables outgoing health checks using upstream socks4 proxy.
10664
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010665 ssl opens a ciphered connection
10666
Christopher Faulet79b31d42020-03-30 13:00:05 +020010667 sni <sni> specifies the SNI to use to do health checks over SSL.
10668
Christopher Faulet98572322020-03-30 13:16:44 +020010669 alpn <alpn> defines which protocols to advertise with ALPN. The protocol
10670 list consists in a comma-delimited list of protocol names,
10671 for instance: "http/1.1,http/1.0" (without quotes).
10672 If it is not set, the server ALPN is used.
10673
Christopher Fauletedc6ed92020-04-23 16:27:59 +020010674 proto <name> forces the multiplexer's protocol to use for this connection.
10675 It must be a TCP mux protocol and it must be usable on the
10676 backend side. The list of available protocols is reported in
10677 haproxy -vv.
10678
Christopher Faulet5c288742020-03-31 08:15:58 +020010679 linger cleanly close the connection instead of using a single RST.
Gaetan Rivetf8ba6772020-02-07 15:37:17 +010010680
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010681 When an application lies on more than a single TCP port or when HAProxy
10682 load-balance many services in a single backend, it makes sense to probe all
10683 the services individually before considering a server as operational.
10684
10685 When there are no TCP port configured on the server line neither server port
10686 directive, then the 'tcp-check connect port <port>' must be the first step
10687 of the sequence.
10688
10689 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
10690 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
10691 do.
10692
10693 When a connect must start the ruleset, if may still be preceded by set-var,
10694 unset-var or comment rules.
10695
10696 Examples :
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010697 # check HTTP and HTTPs services on a server.
10698 # first open port 80 thanks to server line port directive, then
10699 # tcp-check opens port 443, ciphered and run a request on it:
10700 option tcp-check
10701 tcp-check connect
10702 tcp-check send GET\ /\ HTTP/1.0\r\n
10703 tcp-check send Host:\ haproxy.1wt.eu\r\n
10704 tcp-check send \r\n
10705 tcp-check expect rstring (2..|3..)
10706 tcp-check connect port 443 ssl
10707 tcp-check send GET\ /\ HTTP/1.0\r\n
10708 tcp-check send Host:\ haproxy.1wt.eu\r\n
10709 tcp-check send \r\n
10710 tcp-check expect rstring (2..|3..)
10711 server www 10.0.0.1 check port 80
10712
10713 # check both POP and IMAP from a single server:
10714 option tcp-check
Gaetan Rivetf8ba6772020-02-07 15:37:17 +010010715 tcp-check connect port 110 linger
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010716 tcp-check expect string +OK\ POP3\ ready
10717 tcp-check connect port 143
10718 tcp-check expect string *\ OK\ IMAP4\ ready
10719 server mail 10.0.0.1 check
10720
10721 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
10722
10723
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010724tcp-check expect [min-recv <int>] [comment <msg>]
Christopher Fauletec07e382020-04-07 14:56:26 +020010725 [ok-status <st>] [error-status <st>] [tout-status <st>]
Christopher Faulet98cc57c2020-04-01 20:52:31 +020010726 [on-success <fmt>] [on-error <fmt>] [status-code <expr>]
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020010727 [!] <match> <pattern>
Davor Ocelice9ed2812017-12-25 17:49:28 +010010728 Specify data to be collected and analyzed during a generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010729 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020010730 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010731
10732 Arguments :
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010733 comment <msg> defines a message to report if the rule evaluation fails.
10734
Gaetan Rivet1afd8262020-02-07 15:37:17 +010010735 min-recv is optional and can define the minimum amount of data required to
10736 evaluate the current expect rule. If the number of received bytes
10737 is under this limit, the check will wait for more data. This
10738 option can be used to resolve some ambiguous matching rules or to
10739 avoid executing costly regex matches on content known to be still
10740 incomplete. If an exact string (string or binary) is used, the
10741 minimum between the string length and this parameter is used.
10742 This parameter is ignored if it is set to -1. If the expect rule
10743 does not match, the check will wait for more data. If set to 0,
10744 the evaluation result is always conclusive.
10745
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010746 <match> is a keyword indicating how to look for a specific pattern in the
Gaetan Rivetefab6c62020-02-07 15:37:17 +010010747 response. The keyword may be one of "string", "rstring", "binary" or
10748 "rbinary".
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010749 The keyword may be preceded by an exclamation mark ("!") to negate
10750 the match. Spaces are allowed between the exclamation mark and the
10751 keyword. See below for more details on the supported keywords.
10752
Christopher Fauletec07e382020-04-07 14:56:26 +020010753 ok-status <st> is optional and can be used to set the check status if
10754 the expect rule is successfully evaluated and if it is
10755 the last rule in the tcp-check ruleset. "L7OK", "L7OKC",
Christopher Fauletd888f0f2020-05-07 07:40:17 +020010756 "L6OK" and "L4OK" are supported :
10757 - L7OK : check passed on layer 7
10758 - L7OKC : check conditionally passed on layer 7, for
10759 example 404 with disable-on-404
10760 - L6OK : check passed on layer 6
10761 - L4OK : check passed on layer 4
Christopher Fauletec07e382020-04-07 14:56:26 +020010762 By default "L7OK" is used.
10763
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020010764 error-status <st> is optional and can be used to set the check status if
10765 an error occurred during the expect rule evaluation.
Christopher Fauletd888f0f2020-05-07 07:40:17 +020010766 "L7RSP", "L7STS", "L6RSP" and "L4CON" are supported :
10767 - L7RSP : layer 7 invalid response - protocol error
10768 - L7STS : layer 7 response error, for example HTTP 5xx
10769 - L6RSP : layer 6 invalid response - protocol error
10770 - L4CON : layer 1-4 connection problem
10771 By default "L7RSP" is used.
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020010772
Christopher Fauletec07e382020-04-07 14:56:26 +020010773 tout-status <st> is optional and can be used to set the check status if
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020010774 a timeout occurred during the expect rule evaluation.
Christopher Fauletd888f0f2020-05-07 07:40:17 +020010775 "L7TOUT", "L6TOUT", and "L4TOUT" are supported :
10776 - L7TOUT : layer 7 (HTTP/SMTP) timeout
10777 - L6TOUT : layer 6 (SSL) timeout
10778 - L4TOUT : layer 1-4 timeout
Christopher Fauletcf80f2f2020-04-01 11:04:52 +020010779 By default "L7TOUT" is used.
10780
Christopher Fauletbe52b4d2020-04-01 16:30:22 +020010781 on-success <fmt> is optional and can be used to customize the
10782 informational message reported in logs if the expect
10783 rule is successfully evaluated and if it is the last rule
10784 in the tcp-check ruleset. <fmt> is a log-format string.
10785
10786 on-error <fmt> is optional and can be used to customize the
10787 informational message reported in logs if an error
10788 occurred during the expect rule evaluation. <fmt> is a
10789 log-format string.
10790
Christopher Faulet98cc57c2020-04-01 20:52:31 +020010791 status-code <expr> is optional and can be used to set the check status code
10792 reported in logs, on success or on error. <expr> is a
10793 standard HAProxy expression formed by a sample-fetch
10794 followed by some converters.
10795
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010796 <pattern> is the pattern to look for. It may be a string or a regular
10797 expression. If the pattern contains spaces, they must be escaped
10798 with the usual backslash ('\').
10799 If the match is set to binary, then the pattern must be passed as
Davor Ocelice9ed2812017-12-25 17:49:28 +010010800 a series of hexadecimal digits in an even number. Each sequence of
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010801 two digits will represent a byte. The hexadecimal digits may be
10802 used upper or lower case.
10803
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010804 The available matches are intentionally similar to their http-check cousins :
10805
10806 string <string> : test the exact string matches in the response buffer.
10807 A health check response will be considered valid if the
10808 response's buffer contains this exact string. If the
10809 "string" keyword is prefixed with "!", then the response
10810 will be considered invalid if the body contains this
10811 string. This can be used to look for a mandatory pattern
10812 in a protocol response, or to detect a failure when a
10813 specific error appears in a protocol banner.
10814
10815 rstring <regex> : test a regular expression on the response buffer.
10816 A health check response will be considered valid if the
10817 response's buffer matches this expression. If the
10818 "rstring" keyword is prefixed with "!", then the response
10819 will be considered invalid if the body matches the
10820 expression.
10821
Christopher Fauletaaab0832020-05-05 15:54:22 +020010822 string-lf <fmt> : test a log-format string match in the response's buffer.
10823 A health check response will be considered valid if the
10824 response's buffer contains the string resulting of the
10825 evaluation of <fmt>, which follows the log-format rules.
10826 If prefixed with "!", then the response will be
10827 considered invalid if the buffer contains the string.
10828
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010829 binary <hexstring> : test the exact string in its hexadecimal form matches
10830 in the response buffer. A health check response will
10831 be considered valid if the response's buffer contains
10832 this exact hexadecimal string.
10833 Purpose is to match data on binary protocols.
10834
Gaetan Rivetefab6c62020-02-07 15:37:17 +010010835 rbinary <regex> : test a regular expression on the response buffer, like
10836 "rstring". However, the response buffer is transformed
10837 into its hexadecimal form, including NUL-bytes. This
10838 allows using all regex engines to match any binary
10839 content. The hexadecimal transformation takes twice the
10840 size of the original response. As such, the expected
10841 pattern should work on at-most half the response buffer
10842 size.
10843
Christopher Fauletaaab0832020-05-05 15:54:22 +020010844 binary-lf <hexfmt> : test a log-format string in its hexadecimal form
10845 match in the response's buffer. A health check response
10846 will be considered valid if the response's buffer
10847 contains the hexadecimal string resulting of the
10848 evaluation of <fmt>, which follows the log-format
10849 rules. If prefixed with "!", then the response will be
10850 considered invalid if the buffer contains the
10851 hexadecimal string. The hexadecimal string is converted
10852 in a binary string before matching the response's
10853 buffer.
10854
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010855 It is important to note that the responses will be limited to a certain size
10856 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
10857 Thus, too large responses may not contain the mandatory pattern when using
10858 "string", "rstring" or binary. If a large response is absolutely required, it
10859 is possible to change the default max size by setting the global variable.
10860 However, it is worth keeping in mind that parsing very large responses can
10861 waste some CPU cycles, especially when regular expressions are used, and that
10862 it is always better to focus the checks on smaller resources. Also, in its
10863 current state, the check will not find any string nor regex past a null
10864 character in the response. Similarly it is not possible to request matching
10865 the null character.
10866
10867 Examples :
10868 # perform a POP check
10869 option tcp-check
10870 tcp-check expect string +OK\ POP3\ ready
10871
10872 # perform an IMAP check
10873 option tcp-check
10874 tcp-check expect string *\ OK\ IMAP4\ ready
10875
10876 # look for the redis master server
10877 option tcp-check
10878 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +020010879 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010880 tcp-check send info\ replication\r\n
10881 tcp-check expect string role:master
10882 tcp-check send QUIT\r\n
10883 tcp-check expect string +OK
10884
10885
10886 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
10887 "tcp-check send-binary", "http-check expect", tune.chksize
10888
10889
Christopher Fauletb50b3e62020-05-05 18:43:43 +020010890tcp-check send <data> [comment <msg>]
10891tcp-check send-lf <fmt> [comment <msg>]
10892 Specify a string or a log-format string to be sent as a question during a
10893 generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010894 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020010895 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010896
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010897 Arguments :
10898 comment <msg> defines a message to report if the rule evaluation fails.
10899
Christopher Fauletb50b3e62020-05-05 18:43:43 +020010900 <data> is the string that will be sent during a generic health
10901 check session.
Christopher Faulet16fff672020-04-30 07:50:54 +020010902
Christopher Fauletb50b3e62020-05-05 18:43:43 +020010903 <fmt> is the log-format string that will be sent, once evaluated,
10904 during a generic health check session.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010905
10906 Examples :
10907 # look for the redis master server
10908 option tcp-check
10909 tcp-check send info\ replication\r\n
10910 tcp-check expect string role:master
10911
10912 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
10913 "tcp-check send-binary", tune.chksize
10914
10915
Christopher Fauletb50b3e62020-05-05 18:43:43 +020010916tcp-check send-binary <hexstring> [comment <msg>]
10917tcp-check send-binary-lf <hexfmt> [comment <msg>]
10918 Specify an hex digits string or an hex digits log-format string to be sent as
10919 a binary question during a raw tcp health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010920 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020010921 yes | no | yes | yes
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010922
Christopher Faulet4f5c2e22020-04-23 15:22:33 +020010923 Arguments :
10924 comment <msg> defines a message to report if the rule evaluation fails.
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010925
Christopher Fauletb50b3e62020-05-05 18:43:43 +020010926 <hexstring> is the hexadecimal string that will be send, once converted
10927 to binary, during a generic health check session.
Christopher Faulet16fff672020-04-30 07:50:54 +020010928
Christopher Fauletb50b3e62020-05-05 18:43:43 +020010929 <hexfmt> is the hexadecimal log-format string that will be send, once
10930 evaluated and converted to binary, during a generic health
10931 check session.
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010932
10933 Examples :
10934 # redis check in binary
10935 option tcp-check
10936 tcp-check send-binary 50494e470d0a # PING\r\n
10937 tcp-check expect binary 2b504F4e47 # +PONG
10938
10939
10940 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
10941 "tcp-check send", tune.chksize
10942
10943
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010944tcp-check set-var(<var-name>) <expr>
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010945 This operation sets the content of a variable. The variable is declared inline.
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010946 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020010947 yes | no | yes | yes
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010948
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010949 Arguments :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010950 <var-name> The name of the variable starts with an indication about its
10951 scope. The scopes allowed for tcp-check are:
10952 "proc" : the variable is shared with the whole process.
10953 "sess" : the variable is shared with the tcp-check session.
10954 "check": the variable is declared for the lifetime of the tcp-check.
10955 This prefix is followed by a name. The separator is a '.'.
10956 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
10957 and '-'.
10958
10959 <expr> Is a sample-fetch expression potentially followed by converters.
10960
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010961 Examples :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010962 tcp-check set-var(check.port) int(1234)
10963
10964
10965tcp-check unset-var(<var-name>)
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010966 Free a reference to a variable within its scope.
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010967 May be used in sections: defaults | frontend | listen | backend
Christopher Faulet404f9192020-04-09 23:13:54 +020010968 yes | no | yes | yes
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010969
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010970 Arguments :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010971 <var-name> The name of the variable starts with an indication about its
10972 scope. The scopes allowed for tcp-check are:
10973 "proc" : the variable is shared with the whole process.
10974 "sess" : the variable is shared with the tcp-check session.
10975 "check": the variable is declared for the lifetime of the tcp-check.
10976 This prefix is followed by a name. The separator is a '.'.
10977 The name may only contain characters 'a-z', 'A-Z', '0-9', '.',
10978 and '-'.
10979
Christopher Fauletc52ea4d2020-04-23 15:43:35 +020010980 Examples :
Gaetan Rivet0c39ecc2020-02-24 17:34:11 +010010981 tcp-check unset-var(check.port)
10982
10983
Willy Tarreaue9656522010-08-17 15:40:09 +020010984tcp-request connection <action> [{if | unless} <condition>]
10985 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +020010986 May be used in sections : defaults | frontend | listen | backend
10987 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +020010988 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020010989 <action> defines the action to perform if the condition applies. See
10990 below.
Willy Tarreau1a687942010-05-23 22:40:30 +020010991
Willy Tarreaue9656522010-08-17 15:40:09 +020010992 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010993
10994 Immediately after acceptance of a new incoming connection, it is possible to
10995 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +020010996 or dropped or have its counters tracked. Those conditions cannot make use of
10997 any data contents because the connection has not been read from yet, and the
10998 buffers are not yet allocated. This is used to selectively and very quickly
10999 accept or drop connections from various sources with a very low overhead. If
11000 some contents need to be inspected in order to take the decision, the
11001 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011002
Willy Tarreaue9656522010-08-17 15:40:09 +020011003 The "tcp-request connection" rules are evaluated in their exact declaration
11004 order. If no rule matches or if there is no rule, the default action is to
11005 accept the incoming connection. There is no specific limit to the number of
11006 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011007
Willy Tarreaua9083d02015-05-08 15:27:59 +020011008 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +020011009 - accept :
11010 accepts the connection if the condition is true (when used with "if")
11011 or false (when used with "unless"). The first such rule executed ends
11012 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011013
Willy Tarreaue9656522010-08-17 15:40:09 +020011014 - reject :
11015 rejects the connection if the condition is true (when used with "if")
11016 or false (when used with "unless"). The first such rule executed ends
11017 the rules evaluation. Rejected connections do not even become a
11018 session, which is why they are accounted separately for in the stats,
11019 as "denied connections". They are not considered for the session
11020 rate-limit and are not logged either. The reason is that these rules
11021 should only be used to filter extremely high connection rates such as
11022 the ones encountered during a massive DDoS attack. Under these extreme
11023 conditions, the simple action of logging each event would make the
11024 system collapse and would considerably lower the filtering capacity. If
11025 logging is absolutely desired, then "tcp-request content" rules should
Willy Tarreau4f614292016-10-21 17:49:36 +020011026 be used instead, as "tcp-request session" rules will not log either.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011027
Willy Tarreau4f0d9192013-06-11 20:40:55 +020011028 - expect-proxy layer4 :
11029 configures the client-facing connection to receive a PROXY protocol
11030 header before any byte is read from the socket. This is equivalent to
11031 having the "accept-proxy" keyword on the "bind" line, except that using
11032 the TCP rule allows the PROXY protocol to be accepted only for certain
11033 IP address ranges using an ACL. This is convenient when multiple layers
11034 of load balancers are passed through by traffic coming from public
11035 hosts.
11036
Bertrand Jacquin90759682016-06-06 15:35:39 +010011037 - expect-netscaler-cip layer4 :
11038 configures the client-facing connection to receive a NetScaler Client
11039 IP insertion protocol header before any byte is read from the socket.
11040 This is equivalent to having the "accept-netscaler-cip" keyword on the
11041 "bind" line, except that using the TCP rule allows the PROXY protocol
11042 to be accepted only for certain IP address ranges using an ACL. This
11043 is convenient when multiple layers of load balancers are passed
11044 through by traffic coming from public hosts.
11045
Willy Tarreau18bf01e2014-06-13 16:18:52 +020011046 - capture <sample> len <length> :
11047 This only applies to "tcp-request content" rules. It captures sample
11048 expression <sample> from the request buffer, and converts it to a
11049 string of at most <len> characters. The resulting string is stored into
11050 the next request "capture" slot, so it will possibly appear next to
11051 some captured HTTP headers. It will then automatically appear in the
11052 logs, and it will be possible to extract it using sample fetch rules to
11053 feed it into headers or anything. The length should be limited given
11054 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +020011055 session life. Please check section 7.3 (Fetching samples) and "capture
11056 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +020011057
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011058 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +020011059 enables tracking of sticky counters from current connection. These
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020011060 rules do not stop evaluation and do not change default action. The
11061 number of counters that may be simultaneously tracked by the same
11062 connection is set in MAX_SESS_STKCTR at build time (reported in
John Roeslerfb2fce12019-07-10 15:45:51 -050011063 haproxy -vv) which defaults to 3, so the track-sc number is between 0
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020011064 and (MAX_SESS_STCKTR-1). The first "track-sc0" rule executed enables
11065 tracking of the counters of the specified table as the first set. The
11066 first "track-sc1" rule executed enables tracking of the counters of the
11067 specified table as the second set. The first "track-sc2" rule executed
11068 enables tracking of the counters of the specified table as the third
11069 set. It is a recommended practice to use the first set of counters for
11070 the per-frontend counters and the second set for the per-backend ones.
11071 But this is just a guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011072
Willy Tarreaue9656522010-08-17 15:40:09 +020011073 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020011074 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +020011075 in section 7.3. It describes what elements of the incoming
Davor Ocelice9ed2812017-12-25 17:49:28 +010011076 request or connection will be analyzed, extracted, combined,
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011077 and used to select which table entry to update the counters.
11078 Note that "tcp-request connection" cannot use content-based
11079 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011080
Willy Tarreaue9656522010-08-17 15:40:09 +020011081 <table> is an optional table to be used instead of the default one,
11082 which is the stick-table declared in the current proxy. All
11083 the counters for the matches and updates for the key will
11084 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011085
Willy Tarreaue9656522010-08-17 15:40:09 +020011086 Once a "track-sc*" rule is executed, the key is looked up in the table
11087 and if it is not found, an entry is allocated for it. Then a pointer to
11088 that entry is kept during all the session's life, and this entry's
11089 counters are updated as often as possible, every time the session's
11090 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011091 Counters are only updated for events that happen after the tracking has
11092 been started. For example, connection counters will not be updated when
11093 tracking layer 7 information, since the connection event happens before
11094 layer7 information is extracted.
11095
Willy Tarreaue9656522010-08-17 15:40:09 +020011096 If the entry tracks concurrent connection counters, one connection is
11097 counted for as long as the entry is tracked, and the entry will not
11098 expire during that time. Tracking counters also provides a performance
11099 advantage over just checking the keys, because only one table lookup is
11100 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011101
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020011102 - sc-inc-gpc0(<sc-id>):
11103 The "sc-inc-gpc0" increments the GPC0 counter according to the sticky
11104 counter designated by <sc-id>. If an error occurs, this action silently
11105 fails and the actions evaluation continues.
11106
Frédéric Lécaille6778b272018-01-29 15:22:53 +010011107 - sc-inc-gpc1(<sc-id>):
11108 The "sc-inc-gpc1" increments the GPC1 counter according to the sticky
11109 counter designated by <sc-id>. If an error occurs, this action silently
11110 fails and the actions evaluation continues.
11111
Cédric Dufour0d7712d2019-11-06 18:38:53 +010011112 - sc-set-gpt0(<sc-id>) { <int> | <expr> }:
11113 This action sets the 32-bit unsigned GPT0 tag according to the sticky
11114 counter designated by <sc-id> and the value of <int>/<expr>. The
11115 expected result is a boolean. If an error occurs, this action silently
11116 fails and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +020011117
William Lallemand2e785f22016-05-25 01:48:42 +020011118 - set-src <expr> :
11119 Is used to set the source IP address to the value of specified
11120 expression. Useful if you want to mask source IP for privacy.
11121 If you want to provide an IP from a HTTP header use "http-request
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020011122 set-src".
William Lallemand2e785f22016-05-25 01:48:42 +020011123
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020011124 Arguments:
11125 <expr> Is a standard HAProxy expression formed by a sample-fetch
11126 followed by some converters.
William Lallemand2e785f22016-05-25 01:48:42 +020011127
11128 Example:
William Lallemand2e785f22016-05-25 01:48:42 +020011129 tcp-request connection set-src src,ipmask(24)
11130
Willy Tarreau0c630532016-10-21 17:52:58 +020011131 When possible, set-src preserves the original source port as long as the
11132 address family allows it, otherwise the source port is set to 0.
William Lallemand2e785f22016-05-25 01:48:42 +020011133
William Lallemand44be6402016-05-25 01:51:35 +020011134 - set-src-port <expr> :
11135 Is used to set the source port address to the value of specified
11136 expression.
11137
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020011138 Arguments:
11139 <expr> Is a standard HAProxy expression formed by a sample-fetch
11140 followed by some converters.
William Lallemand44be6402016-05-25 01:51:35 +020011141
11142 Example:
William Lallemand44be6402016-05-25 01:51:35 +020011143 tcp-request connection set-src-port int(4000)
11144
Willy Tarreau0c630532016-10-21 17:52:58 +020011145 When possible, set-src-port preserves the original source address as long
11146 as the address family supports a port, otherwise it forces the source
11147 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +020011148
William Lallemand13e9b0c2016-05-25 02:34:07 +020011149 - set-dst <expr> :
11150 Is used to set the destination IP address to the value of specified
11151 expression. Useful if you want to mask IP for privacy in log.
11152 If you want to provide an IP from a HTTP header use "http-request
11153 set-dst". If you want to connect to the new address/port, use
11154 '0.0.0.0:0' as a server address in the backend.
11155
11156 <expr> Is a standard HAProxy expression formed by a sample-fetch
11157 followed by some converters.
11158
11159 Example:
11160
11161 tcp-request connection set-dst dst,ipmask(24)
11162 tcp-request connection set-dst ipv4(10.0.0.1)
11163
Willy Tarreau0c630532016-10-21 17:52:58 +020011164 When possible, set-dst preserves the original destination port as long as
11165 the address family allows it, otherwise the destination port is set to 0.
11166
William Lallemand13e9b0c2016-05-25 02:34:07 +020011167 - set-dst-port <expr> :
11168 Is used to set the destination port address to the value of specified
11169 expression. If you want to connect to the new address/port, use
11170 '0.0.0.0:0' as a server address in the backend.
11171
11172
11173 <expr> Is a standard HAProxy expression formed by a sample-fetch
11174 followed by some converters.
11175
11176 Example:
11177
11178 tcp-request connection set-dst-port int(4000)
11179
Willy Tarreau0c630532016-10-21 17:52:58 +020011180 When possible, set-dst-port preserves the original destination address as
11181 long as the address family supports a port, otherwise it forces the
11182 destination address to IPv4 "0.0.0.0" before rewriting the port.
11183
Willy Tarreau2d392c22015-08-24 01:43:45 +020011184 - "silent-drop" :
11185 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +010011186 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +020011187 to prevent the client from being notified. The effect it then that the
11188 client still sees an established connection while there's none on
11189 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
11190 except that it doesn't use any local resource at all on the machine
11191 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +010011192 slow down stronger attackers. It is important to understand the impact
11193 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +020011194 client and HAProxy (firewalls, proxies, load balancers) will also keep
11195 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +010011196 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +020011197 TCP_REPAIR socket option is used to block the emission of a TCP
11198 reset. On other systems, the socket's TTL is reduced to 1 so that the
11199 TCP reset doesn't pass the first router, though it's still delivered to
11200 local networks. Do not use it unless you fully understand how it works.
11201
Willy Tarreaue9656522010-08-17 15:40:09 +020011202 Note that the "if/unless" condition is optional. If no condition is set on
11203 the action, it is simply performed unconditionally. That can be useful for
11204 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011205
Willy Tarreaue9656522010-08-17 15:40:09 +020011206 Example: accept all connections from white-listed hosts, reject too fast
11207 connection without counting them, and track accepted connections.
11208 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011209
Willy Tarreaue9656522010-08-17 15:40:09 +020011210 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011211 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011212 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011213
Willy Tarreaue9656522010-08-17 15:40:09 +020011214 Example: accept all connections from white-listed hosts, count all other
11215 connections and reject too fast ones. This results in abusive ones
11216 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011217
Willy Tarreaue9656522010-08-17 15:40:09 +020011218 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011219 tcp-request connection track-sc0 src
11220 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011221
Willy Tarreau4f0d9192013-06-11 20:40:55 +020011222 Example: enable the PROXY protocol for traffic coming from all known proxies.
11223
11224 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
11225
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011226 See section 7 about ACL usage.
11227
Willy Tarreau4f614292016-10-21 17:49:36 +020011228 See also : "tcp-request session", "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011229
11230
Willy Tarreaue9656522010-08-17 15:40:09 +020011231tcp-request content <action> [{if | unless} <condition>]
11232 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +020011233 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +020011234 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +020011235 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020011236 <action> defines the action to perform if the condition applies. See
11237 below.
Willy Tarreau62644772008-07-16 18:36:06 +020011238
Willy Tarreaue9656522010-08-17 15:40:09 +020011239 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +020011240
Davor Ocelice9ed2812017-12-25 17:49:28 +010011241 A request's contents can be analyzed at an early stage of request processing
Willy Tarreaue9656522010-08-17 15:40:09 +020011242 called "TCP content inspection". During this stage, ACL-based rules are
11243 evaluated every time the request contents are updated, until either an
11244 "accept" or a "reject" rule matches, or the TCP request inspection delay
11245 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +020011246
Willy Tarreaue9656522010-08-17 15:40:09 +020011247 The first difference between these rules and "tcp-request connection" rules
11248 is that "tcp-request content" rules can make use of contents to take a
11249 decision. Most often, these decisions will consider a protocol recognition or
11250 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +010011251 both frontends and backends. In case of HTTP keep-alive with the client, all
11252 tcp-request content rules are evaluated again, so haproxy keeps a record of
11253 what sticky counters were assigned by a "tcp-request connection" versus a
11254 "tcp-request content" rule, and flushes all the content-related ones after
11255 processing an HTTP request, so that they may be evaluated again by the rules
11256 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011257 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +010011258 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +020011259
Willy Tarreaue9656522010-08-17 15:40:09 +020011260 Content-based rules are evaluated in their exact declaration order. If no
11261 rule matches or if there is no rule, the default action is to accept the
11262 contents. There is no specific limit to the number of rules which may be
11263 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +020011264
Thierry FOURNIER236657b2015-08-19 08:25:14 +020011265 Several types of actions are supported :
Willy Tarreau18bf01e2014-06-13 16:18:52 +020011266 - accept : the request is accepted
Baptiste Assmann333939c2019-01-21 08:34:50 +010011267 - do-resolve: perform a DNS resolution
Willy Tarreau18bf01e2014-06-13 16:18:52 +020011268 - reject : the request is rejected and the connection is closed
11269 - capture : the specified sample expression is captured
Patrick Hemmer268a7072018-05-11 12:52:31 -040011270 - set-priority-class <expr> | set-priority-offset <expr>
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011271 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020011272 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010011273 - sc-inc-gpc1(<sc-id>)
Cédric Dufour0d7712d2019-11-06 18:38:53 +010011274 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +020011275 - set-dst <expr>
11276 - set-dst-port <expr>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011277 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +010011278 - unset-var(<var-name>)
Willy Tarreau2d392c22015-08-24 01:43:45 +020011279 - silent-drop
Davor Ocelice9ed2812017-12-25 17:49:28 +010011280 - send-spoe-group <engine-name> <group-name>
Christopher Faulet579d83b2019-11-22 15:34:17 +010011281 - use-service <service-name>
Willy Tarreau62644772008-07-16 18:36:06 +020011282
Willy Tarreaue9656522010-08-17 15:40:09 +020011283 They have the same meaning as their counter-parts in "tcp-request connection"
11284 so please refer to that section for a complete description.
Baptiste Assmann333939c2019-01-21 08:34:50 +010011285 For "do-resolve" action, please check the "http-request do-resolve"
11286 configuration section.
Willy Tarreau62644772008-07-16 18:36:06 +020011287
Willy Tarreauf3338342014-01-28 21:40:28 +010011288 While there is nothing mandatory about it, it is recommended to use the
11289 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
11290 content" rules in the frontend, and track-sc2 for "tcp-request content"
11291 rules in the backend, because that makes the configuration more readable
11292 and easier to troubleshoot, but this is just a guideline and all counters
11293 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +020011294
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011295 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +020011296 the action, it is simply performed unconditionally. That can be useful for
11297 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +020011298
Willy Tarreaue9656522010-08-17 15:40:09 +020011299 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +020011300 rules, since HTTP-specific ACL matches are able to preliminarily parse the
11301 contents of a buffer before extracting the required data. If the buffered
11302 contents do not parse as a valid HTTP message, then the ACL does not match.
11303 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +010011304 processing, so there is no risk of parsing something differently. In an HTTP
11305 backend connected to from an HTTP frontend, it is guaranteed that HTTP
11306 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +020011307
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011308 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020011309 are present when the rule is processed. The rule processing engine is able to
11310 wait until the inspect delay expires when the data to be tracked is not yet
11311 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011312
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +020011313 The "set-dst" and "set-dst-port" are used to set respectively the destination
11314 IP and port. More information on how to use it at "http-request set-dst".
11315
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011316 The "set-var" is used to set the content of a variable. The variable is
Willy Tarreau4f614292016-10-21 17:49:36 +020011317 declared inline. For "tcp-request session" rules, only session-level
11318 variables can be used, without any layer7 contents.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011319
Daniel Schneller0b547052016-03-21 20:46:57 +010011320 <var-name> The name of the variable starts with an indication about
11321 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010011322 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010011323 "sess" : the variable is shared with the whole session
11324 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011325 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +010011326 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011327 processing
Daniel Schneller0b547052016-03-21 20:46:57 +010011328 "res" : the variable is shared only during response
11329 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011330 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +010011331 The name may only contain characters 'a-z', 'A-Z', '0-9',
11332 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011333
11334 <expr> Is a standard HAProxy expression formed by a sample-fetch
11335 followed by some converters.
11336
Christopher Faulet85d79c92016-11-09 16:54:56 +010011337 The "unset-var" is used to unset a variable. See above for details about
11338 <var-name>.
11339
Patrick Hemmer268a7072018-05-11 12:52:31 -040011340 The "set-priority-class" is used to set the queue priority class of the
11341 current request. The value must be a sample expression which converts to an
11342 integer in the range -2047..2047. Results outside this range will be
11343 truncated. The priority class determines the order in which queued requests
11344 are processed. Lower values have higher priority.
11345
11346 The "set-priority-offset" is used to set the queue priority timestamp offset
11347 of the current request. The value must be a sample expression which converts
11348 to an integer in the range -524287..524287. Results outside this range will be
11349 truncated. When a request is queued, it is ordered first by the priority
11350 class, then by the current timestamp adjusted by the given offset in
11351 milliseconds. Lower values have higher priority.
11352 Note that the resulting timestamp is is only tracked with enough precision for
11353 524,287ms (8m44s287ms). If the request is queued long enough to where the
11354 adjusted timestamp exceeds this value, it will be misidentified as highest
11355 priority. Thus it is important to set "timeout queue" to a value, where when
11356 combined with the offset, does not exceed this limit.
11357
Christopher Faulet76c09ef2017-09-21 11:03:52 +020011358 The "send-spoe-group" is used to trigger sending of a group of SPOE
11359 messages. To do so, the SPOE engine used to send messages must be defined, as
11360 well as the SPOE group to send. Of course, the SPOE engine must refer to an
11361 existing SPOE filter. If not engine name is provided on the SPOE filter line,
11362 the SPOE agent name must be used.
11363
11364 <engine-name> The SPOE engine name.
11365
11366 <group-name> The SPOE group name as specified in the engine configuration.
11367
Christopher Faulet579d83b2019-11-22 15:34:17 +010011368 The "use-service" is used to executes a TCP service which will reply to the
11369 request and stop the evaluation of the rules. This service may choose to
11370 reply by sending any valid response or it may immediately close the
11371 connection without sending anything. Outside natives services, it is possible
11372 to write your own services in Lua. No further "tcp-request" rules are
11373 evaluated.
11374
11375 Example:
11376 tcp-request content use-service lua.deny { src -f /etc/haproxy/blacklist.lst }
11377
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011378 Example:
11379
11380 tcp-request content set-var(sess.my_var) src
Christopher Faulet85d79c92016-11-09 16:54:56 +010011381 tcp-request content unset-var(sess.my_var2)
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011382
Willy Tarreau62644772008-07-16 18:36:06 +020011383 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +020011384 # Accept HTTP requests containing a Host header saying "example.com"
11385 # and reject everything else.
11386 acl is_host_com hdr(Host) -i example.com
11387 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +020011388 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +020011389 tcp-request content reject
11390
11391 Example:
Willy Tarreau62644772008-07-16 18:36:06 +020011392 # reject SMTP connection if client speaks first
11393 tcp-request inspect-delay 30s
11394 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011395 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +020011396
11397 # Forward HTTPS connection only if client speaks
11398 tcp-request inspect-delay 30s
11399 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +020011400 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +020011401 tcp-request content reject
11402
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011403 Example:
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030011404 # Track the last IP(stick-table type string) from X-Forwarded-For
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011405 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020011406 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030011407 # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
11408 tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011409
11410 Example:
11411 # track request counts per "base" (concatenation of Host+URL)
11412 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020011413 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010011414
Willy Tarreaue9656522010-08-17 15:40:09 +020011415 Example: track per-frontend and per-backend counters, block abusers at the
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030011416 frontend when the backend detects abuse(and marks gpc0).
Willy Tarreaue9656522010-08-17 15:40:09 +020011417
11418 frontend http
Davor Ocelice9ed2812017-12-25 17:49:28 +010011419 # Use General Purpose Counter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +020011420 # protecting all our sites
11421 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011422 tcp-request connection track-sc0 src
11423 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +020011424 ...
11425 use_backend http_dynamic if { path_end .php }
11426
11427 backend http_dynamic
11428 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011429 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +020011430 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011431 acl click_too_fast sc1_http_req_rate gt 10
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030011432 acl mark_as_abuser sc0_inc_gpc0(http) gt 0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020011433 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +020011434 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +020011435
Willy Tarreauc57f0e22009-05-10 13:12:33 +020011436 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +020011437
Jarno Huuskonen95b012b2017-04-06 13:59:14 +030011438 See also : "tcp-request connection", "tcp-request session",
11439 "tcp-request inspect-delay", and "http-request".
Willy Tarreau62644772008-07-16 18:36:06 +020011440
11441
11442tcp-request inspect-delay <timeout>
11443 Set the maximum allowed time to wait for data during content inspection
11444 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +020011445 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +020011446 Arguments :
11447 <timeout> is the timeout value specified in milliseconds by default, but
11448 can be in any other unit if the number is suffixed by the unit,
11449 as explained at the top of this document.
11450
11451 People using haproxy primarily as a TCP relay are often worried about the
11452 risk of passing any type of protocol to a server without any analysis. In
11453 order to be able to analyze the request contents, we must first withhold
11454 the data then analyze them. This statement simply enables withholding of
11455 data for at most the specified amount of time.
11456
Willy Tarreaufb356202010-08-03 14:02:05 +020011457 TCP content inspection applies very early when a connection reaches a
11458 frontend, then very early when the connection is forwarded to a backend. This
11459 means that a connection may experience a first delay in the frontend and a
11460 second delay in the backend if both have tcp-request rules.
11461
Willy Tarreau62644772008-07-16 18:36:06 +020011462 Note that when performing content inspection, haproxy will evaluate the whole
11463 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011464 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +020011465 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +010011466 contents are definitive. If no delay is set, haproxy will not wait at all
11467 and will immediately apply a verdict based on the available information.
11468 Obviously this is unlikely to be very useful and might even be racy, so such
11469 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +020011470
11471 As soon as a rule matches, the request is released and continues as usual. If
11472 the timeout is reached and no rule matches, the default policy will be to let
11473 it pass through unaffected.
11474
11475 For most protocols, it is enough to set it to a few seconds, as most clients
11476 send the full request immediately upon connection. Add 3 or more seconds to
11477 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +010011478 to use large values, for instance to ensure that the client never talks
Davor Ocelice9ed2812017-12-25 17:49:28 +010011479 before the server (e.g. SMTP), or to wait for a client to talk before passing
11480 data to the server (e.g. SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +020011481 least the inspection delay, otherwise it will expire first. If the client
11482 closes the connection or if the buffer is full, the delay immediately expires
11483 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +020011484
Willy Tarreau55165fe2009-05-10 12:02:55 +020011485 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +020011486 "timeout client".
11487
11488
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011489tcp-response content <action> [{if | unless} <condition>]
11490 Perform an action on a session response depending on a layer 4-7 condition
11491 May be used in sections : defaults | frontend | listen | backend
11492 no | no | yes | yes
11493 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020011494 <action> defines the action to perform if the condition applies. See
11495 below.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011496
11497 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
11498
Davor Ocelice9ed2812017-12-25 17:49:28 +010011499 Response contents can be analyzed at an early stage of response processing
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011500 called "TCP content inspection". During this stage, ACL-based rules are
11501 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020011502 "accept", "close" or a "reject" rule matches, or a TCP response inspection
11503 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011504
11505 Most often, these decisions will consider a protocol recognition or validity.
11506
11507 Content-based rules are evaluated in their exact declaration order. If no
11508 rule matches or if there is no rule, the default action is to accept the
11509 contents. There is no specific limit to the number of rules which may be
11510 inserted.
11511
Thierry FOURNIER236657b2015-08-19 08:25:14 +020011512 Several types of actions are supported :
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011513 - accept :
11514 accepts the response if the condition is true (when used with "if")
11515 or false (when used with "unless"). The first such rule executed ends
11516 the rules evaluation.
11517
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020011518 - close :
11519 immediately closes the connection with the server if the condition is
11520 true (when used with "if"), or false (when used with "unless"). The
11521 first such rule executed ends the rules evaluation. The main purpose of
11522 this action is to force a connection to be finished between a client
11523 and a server after an exchange when the application protocol expects
11524 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011525 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020011526 protocols.
11527
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011528 - reject :
11529 rejects the response if the condition is true (when used with "if")
11530 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011531 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011532
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011533 - set-var(<var-name>) <expr>
11534 Sets a variable.
11535
Christopher Faulet85d79c92016-11-09 16:54:56 +010011536 - unset-var(<var-name>)
11537 Unsets a variable.
11538
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020011539 - sc-inc-gpc0(<sc-id>):
11540 This action increments the GPC0 counter according to the sticky
11541 counter designated by <sc-id>. If an error occurs, this action fails
11542 silently and the actions evaluation continues.
11543
Frédéric Lécaille6778b272018-01-29 15:22:53 +010011544 - sc-inc-gpc1(<sc-id>):
11545 This action increments the GPC1 counter according to the sticky
11546 counter designated by <sc-id>. If an error occurs, this action fails
11547 silently and the actions evaluation continues.
11548
Cédric Dufour0d7712d2019-11-06 18:38:53 +010011549 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
11550 This action sets the 32-bit unsigned GPT0 tag according to the sticky
11551 counter designated by <sc-id> and the value of <int>/<expr>. The
11552 expected result is a boolean. If an error occurs, this action silently
11553 fails and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +020011554
Willy Tarreau2d392c22015-08-24 01:43:45 +020011555 - "silent-drop" :
11556 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +010011557 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +020011558 to prevent the client from being notified. The effect it then that the
11559 client still sees an established connection while there's none on
11560 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
11561 except that it doesn't use any local resource at all on the machine
11562 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +010011563 slow down stronger attackers. It is important to understand the impact
11564 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +020011565 client and HAProxy (firewalls, proxies, load balancers) will also keep
11566 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +010011567 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +020011568 TCP_REPAIR socket option is used to block the emission of a TCP
11569 reset. On other systems, the socket's TTL is reduced to 1 so that the
11570 TCP reset doesn't pass the first router, though it's still delivered to
11571 local networks. Do not use it unless you fully understand how it works.
11572
Christopher Faulet76c09ef2017-09-21 11:03:52 +020011573 - send-spoe-group <engine-name> <group-name>
11574 Send a group of SPOE messages.
11575
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011576 Note that the "if/unless" condition is optional. If no condition is set on
11577 the action, it is simply performed unconditionally. That can be useful for
11578 for changing the default action to a reject.
11579
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011580 It is perfectly possible to match layer 7 contents with "tcp-response
11581 content" rules, but then it is important to ensure that a full response has
11582 been buffered, otherwise no contents will match. In order to achieve this,
11583 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011584 period.
11585
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011586 The "set-var" is used to set the content of a variable. The variable is
11587 declared inline.
11588
Daniel Schneller0b547052016-03-21 20:46:57 +010011589 <var-name> The name of the variable starts with an indication about
11590 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010011591 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010011592 "sess" : the variable is shared with the whole session
11593 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011594 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +010011595 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011596 processing
Daniel Schneller0b547052016-03-21 20:46:57 +010011597 "res" : the variable is shared only during response
11598 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011599 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +010011600 The name may only contain characters 'a-z', 'A-Z', '0-9',
11601 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020011602
11603 <expr> Is a standard HAProxy expression formed by a sample-fetch
11604 followed by some converters.
11605
11606 Example:
11607
11608 tcp-request content set-var(sess.my_var) src
11609
Christopher Faulet85d79c92016-11-09 16:54:56 +010011610 The "unset-var" is used to unset a variable. See above for details about
11611 <var-name>.
11612
11613 Example:
11614
11615 tcp-request content unset-var(sess.my_var)
11616
Christopher Faulet76c09ef2017-09-21 11:03:52 +020011617 The "send-spoe-group" is used to trigger sending of a group of SPOE
11618 messages. To do so, the SPOE engine used to send messages must be defined, as
11619 well as the SPOE group to send. Of course, the SPOE engine must refer to an
11620 existing SPOE filter. If not engine name is provided on the SPOE filter line,
11621 the SPOE agent name must be used.
11622
11623 <engine-name> The SPOE engine name.
11624
11625 <group-name> The SPOE group name as specified in the engine configuration.
11626
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011627 See section 7 about ACL usage.
11628
11629 See also : "tcp-request content", "tcp-response inspect-delay"
11630
11631
Willy Tarreau4f614292016-10-21 17:49:36 +020011632tcp-request session <action> [{if | unless} <condition>]
11633 Perform an action on a validated session depending on a layer 5 condition
11634 May be used in sections : defaults | frontend | listen | backend
11635 no | yes | yes | no
11636 Arguments :
11637 <action> defines the action to perform if the condition applies. See
11638 below.
11639
11640 <condition> is a standard layer5-only ACL-based condition (see section 7).
11641
Davor Ocelice9ed2812017-12-25 17:49:28 +010011642 Once a session is validated, (i.e. after all handshakes have been completed),
Willy Tarreau4f614292016-10-21 17:49:36 +020011643 it is possible to evaluate some conditions to decide whether this session
11644 must be accepted or dropped or have its counters tracked. Those conditions
11645 cannot make use of any data contents because no buffers are allocated yet and
11646 the processing cannot wait at this stage. The main use case it to copy some
11647 early information into variables (since variables are accessible in the
11648 session), or to keep track of some information collected after the handshake,
11649 such as SSL-level elements (SNI, ciphers, client cert's CN) or information
Davor Ocelice9ed2812017-12-25 17:49:28 +010011650 from the PROXY protocol header (e.g. track a source forwarded this way). The
Willy Tarreau4f614292016-10-21 17:49:36 +020011651 extracted information can thus be copied to a variable or tracked using
11652 "track-sc" rules. Of course it is also possible to decide to accept/reject as
11653 with other rulesets. Most operations performed here could also be performed
11654 in "tcp-request content" rules, except that in HTTP these rules are evaluated
11655 for each new request, and that might not always be acceptable. For example a
11656 rule might increment a counter on each evaluation. It would also be possible
11657 that a country is resolved by geolocation from the source IP address,
11658 assigned to a session-wide variable, then the source address rewritten from
11659 an HTTP header for all requests. If some contents need to be inspected in
11660 order to take the decision, the "tcp-request content" statements must be used
11661 instead.
11662
11663 The "tcp-request session" rules are evaluated in their exact declaration
11664 order. If no rule matches or if there is no rule, the default action is to
11665 accept the incoming session. There is no specific limit to the number of
11666 rules which may be inserted.
11667
11668 Several types of actions are supported :
11669 - accept : the request is accepted
11670 - reject : the request is rejected and the connection is closed
11671 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
11672 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010011673 - sc-inc-gpc1(<sc-id>)
Cédric Dufour0d7712d2019-11-06 18:38:53 +010011674 - sc-set-gpt0(<sc-id>) { <int> | <expr> }
Willy Tarreau4f614292016-10-21 17:49:36 +020011675 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +010011676 - unset-var(<var-name>)
Willy Tarreau4f614292016-10-21 17:49:36 +020011677 - silent-drop
11678
11679 These actions have the same meaning as their respective counter-parts in
11680 "tcp-request connection" and "tcp-request content", so please refer to these
11681 sections for a complete description.
11682
11683 Note that the "if/unless" condition is optional. If no condition is set on
11684 the action, it is simply performed unconditionally. That can be useful for
11685 "track-sc*" actions as well as for changing the default action to a reject.
11686
11687 Example: track the original source address by default, or the one advertised
11688 in the PROXY protocol header for connection coming from the local
11689 proxies. The first connection-level rule enables receipt of the
11690 PROXY protocol for these ones, the second rule tracks whatever
11691 address we decide to keep after optional decoding.
11692
11693 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
11694 tcp-request session track-sc0 src
11695
11696 Example: accept all sessions from white-listed hosts, reject too fast
11697 sessions without counting them, and track accepted sessions.
11698 This results in session rate being capped from abusive sources.
11699
11700 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
11701 tcp-request session reject if { src_sess_rate gt 10 }
11702 tcp-request session track-sc0 src
11703
11704 Example: accept all sessions from white-listed hosts, count all other
11705 sessions and reject too fast ones. This results in abusive ones
11706 being blocked as long as they don't slow down.
11707
11708 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
11709 tcp-request session track-sc0 src
11710 tcp-request session reject if { sc0_sess_rate gt 10 }
11711
11712 See section 7 about ACL usage.
11713
11714 See also : "tcp-request connection", "tcp-request content", "stick-table"
11715
11716
Emeric Brun0a3b67f2010-09-24 15:34:53 +020011717tcp-response inspect-delay <timeout>
11718 Set the maximum allowed time to wait for a response during content inspection
11719 May be used in sections : defaults | frontend | listen | backend
11720 no | no | yes | yes
11721 Arguments :
11722 <timeout> is the timeout value specified in milliseconds by default, but
11723 can be in any other unit if the number is suffixed by the unit,
11724 as explained at the top of this document.
11725
11726 See also : "tcp-response content", "tcp-request inspect-delay".
11727
11728
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010011729timeout check <timeout>
11730 Set additional check timeout, but only after a connection has been already
11731 established.
11732
11733 May be used in sections: defaults | frontend | listen | backend
11734 yes | no | yes | yes
11735 Arguments:
11736 <timeout> is the timeout value specified in milliseconds by default, but
11737 can be in any other unit if the number is suffixed by the unit,
11738 as explained at the top of this document.
11739
11740 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
11741 for check and "timeout check" as an additional read timeout. The "min" is
Davor Ocelice9ed2812017-12-25 17:49:28 +010011742 used so that people running with *very* long "timeout connect" (e.g. those
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010011743 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +010011744 (Please also note that there is no valid reason to have such long connect
11745 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
11746 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010011747
11748 If "timeout check" is not set haproxy uses "inter" for complete check
11749 timeout (connect + read) exactly like all <1.3.15 version.
11750
11751 In most cases check request is much simpler and faster to handle than normal
11752 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +010011753 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010011754
11755 This parameter is specific to backends, but can be specified once for all in
11756 "defaults" sections. This is in fact one of the easiest solutions not to
11757 forget about it.
11758
Willy Tarreau41a340d2008-01-22 12:25:31 +010011759 See also: "timeout connect", "timeout queue", "timeout server",
11760 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010011761
11762
Willy Tarreau0ba27502007-12-24 16:55:16 +010011763timeout client <timeout>
Willy Tarreau0ba27502007-12-24 16:55:16 +010011764 Set the maximum inactivity time on the client side.
11765 May be used in sections : defaults | frontend | listen | backend
11766 yes | yes | yes | no
11767 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010011768 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010011769 can be in any other unit if the number is suffixed by the unit,
11770 as explained at the top of this document.
11771
11772 The inactivity timeout applies when the client is expected to acknowledge or
11773 send data. In HTTP mode, this timeout is particularly important to consider
11774 during the first phase, when the client sends the request, and during the
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010011775 response while it is reading data sent by the server. That said, for the
11776 first phase, it is preferable to set the "timeout http-request" to better
11777 protect HAProxy from Slowloris like attacks. The value is specified in
11778 milliseconds by default, but can be in any other unit if the number is
Willy Tarreau0ba27502007-12-24 16:55:16 +010011779 suffixed by the unit, as specified at the top of this document. In TCP mode
11780 (and to a lesser extent, in HTTP mode), it is highly recommended that the
11781 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010011782 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +010011783 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +010011784 (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
11785 sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +020011786 which overrides "timeout client" and "timeout server" for tunnels, as well as
11787 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +010011788
11789 This parameter is specific to frontends, but can be specified once for all in
11790 "defaults" sections. This is in fact one of the easiest solutions not to
11791 forget about it. An unspecified timeout results in an infinite timeout, which
11792 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050011793 during startup because it may result in accumulation of expired sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010011794 the system if the system's timeouts are not configured either.
11795
Willy Tarreau95c4e142017-11-26 12:18:55 +010011796 This also applies to HTTP/2 connections, which will be closed with GOAWAY.
Lukas Tribus75df9d72017-11-24 19:05:12 +010011797
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020011798 See also : "timeout server", "timeout tunnel", "timeout http-request".
Willy Tarreau0ba27502007-12-24 16:55:16 +010011799
Willy Tarreau0ba27502007-12-24 16:55:16 +010011800
Willy Tarreau05cdd962014-05-10 14:30:07 +020011801timeout client-fin <timeout>
11802 Set the inactivity timeout on the client side for half-closed connections.
11803 May be used in sections : defaults | frontend | listen | backend
11804 yes | yes | yes | no
11805 Arguments :
11806 <timeout> is the timeout value specified in milliseconds by default, but
11807 can be in any other unit if the number is suffixed by the unit,
11808 as explained at the top of this document.
11809
11810 The inactivity timeout applies when the client is expected to acknowledge or
11811 send data while one direction is already shut down. This timeout is different
11812 from "timeout client" in that it only applies to connections which are closed
11813 in one direction. This is particularly useful to avoid keeping connections in
11814 FIN_WAIT state for too long when clients do not disconnect cleanly. This
11815 problem is particularly common long connections such as RDP or WebSocket.
11816 Note that this timeout can override "timeout tunnel" when a connection shuts
Willy Tarreau599391a2017-11-24 10:16:00 +010011817 down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
11818 frame was sent, often indicating an expectation that the connection quickly
11819 ends.
Willy Tarreau05cdd962014-05-10 14:30:07 +020011820
11821 This parameter is specific to frontends, but can be specified once for all in
11822 "defaults" sections. By default it is not set, so half-closed connections
11823 will use the other timeouts (timeout.client or timeout.tunnel).
11824
11825 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
11826
11827
Willy Tarreau0ba27502007-12-24 16:55:16 +010011828timeout connect <timeout>
Willy Tarreau0ba27502007-12-24 16:55:16 +010011829 Set the maximum time to wait for a connection attempt to a server to succeed.
11830 May be used in sections : defaults | frontend | listen | backend
11831 yes | no | yes | yes
11832 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010011833 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010011834 can be in any other unit if the number is suffixed by the unit,
11835 as explained at the top of this document.
11836
11837 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010011838 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +010011839 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +010011840 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010011841 connect timeout also presets both queue and tarpit timeouts to the same value
11842 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +010011843
11844 This parameter is specific to backends, but can be specified once for all in
11845 "defaults" sections. This is in fact one of the easiest solutions not to
11846 forget about it. An unspecified timeout results in an infinite timeout, which
11847 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050011848 during startup because it may result in accumulation of failed sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010011849 the system if the system's timeouts are not configured either.
11850
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020011851 See also: "timeout check", "timeout queue", "timeout server", "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +010011852
Willy Tarreau0ba27502007-12-24 16:55:16 +010011853
Willy Tarreaub16a5742010-01-10 14:46:16 +010011854timeout http-keep-alive <timeout>
11855 Set the maximum allowed time to wait for a new HTTP request to appear
11856 May be used in sections : defaults | frontend | listen | backend
11857 yes | yes | yes | yes
11858 Arguments :
11859 <timeout> is the timeout value specified in milliseconds by default, but
11860 can be in any other unit if the number is suffixed by the unit,
11861 as explained at the top of this document.
11862
11863 By default, the time to wait for a new request in case of keep-alive is set
11864 by "timeout http-request". However this is not always convenient because some
11865 people want very short keep-alive timeouts in order to release connections
11866 faster, and others prefer to have larger ones but still have short timeouts
11867 once the request has started to present itself.
11868
11869 The "http-keep-alive" timeout covers these needs. It will define how long to
11870 wait for a new HTTP request to start coming after a response was sent. Once
11871 the first byte of request has been seen, the "http-request" timeout is used
11872 to wait for the complete request to come. Note that empty lines prior to a
11873 new request do not refresh the timeout and are not counted as a new request.
11874
11875 There is also another difference between the two timeouts : when a connection
11876 expires during timeout http-keep-alive, no error is returned, the connection
11877 just closes. If the connection expires in "http-request" while waiting for a
11878 connection to complete, a HTTP 408 error is returned.
11879
11880 In general it is optimal to set this value to a few tens to hundreds of
11881 milliseconds, to allow users to fetch all objects of a page at once but
Davor Ocelice9ed2812017-12-25 17:49:28 +010011882 without waiting for further clicks. Also, if set to a very small value (e.g.
Willy Tarreaub16a5742010-01-10 14:46:16 +010011883 1 millisecond) it will probably only accept pipelined requests but not the
11884 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +020011885 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +010011886
11887 If this parameter is not set, the "http-request" timeout applies, and if both
11888 are not set, "timeout client" still applies at the lower level. It should be
11889 set in the frontend to take effect, unless the frontend is in TCP mode, in
11890 which case the HTTP backend's timeout will be used.
11891
Willy Tarreau95c4e142017-11-26 12:18:55 +010011892 When using HTTP/2 "timeout client" is applied instead. This is so we can keep
11893 using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2
Lukas Tribus75df9d72017-11-24 19:05:12 +010011894 (where we only have one connection per client and a connection setup).
11895
Willy Tarreaub16a5742010-01-10 14:46:16 +010011896 See also : "timeout http-request", "timeout client".
11897
11898
Willy Tarreau036fae02008-01-06 13:24:40 +010011899timeout http-request <timeout>
11900 Set the maximum allowed time to wait for a complete HTTP request
11901 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +020011902 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +010011903 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010011904 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +010011905 can be in any other unit if the number is suffixed by the unit,
11906 as explained at the top of this document.
11907
11908 In order to offer DoS protection, it may be required to lower the maximum
11909 accepted time to receive a complete HTTP request without affecting the client
11910 timeout. This helps protecting against established connections on which
11911 nothing is sent. The client timeout cannot offer a good protection against
11912 this abuse because it is an inactivity timeout, which means that if the
11913 attacker sends one character every now and then, the timeout will not
11914 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +020011915 types, the request will be aborted if it does not complete in time. When the
11916 timeout expires, an HTTP 408 response is sent to the client to inform it
11917 about the problem, and the connection is closed. The logs will report
11918 termination codes "cR". Some recent browsers are having problems with this
Davor Ocelice9ed2812017-12-25 17:49:28 +010011919 standard, well-documented behavior, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +020011920 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
11921 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +010011922
Baptiste Assmanneccdf432015-10-28 13:49:01 +010011923 By default, this timeout only applies to the header part of the request,
11924 and not to any data. As soon as the empty line is received, this timeout is
11925 not used anymore. When combined with "option http-buffer-request", this
11926 timeout also applies to the body of the request..
11927 It is used again on keep-alive connections to wait for a second
Willy Tarreaub16a5742010-01-10 14:46:16 +010011928 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +010011929
11930 Generally it is enough to set it to a few seconds, as most clients send the
11931 full request immediately upon connection. Add 3 or more seconds to cover TCP
Davor Ocelice9ed2812017-12-25 17:49:28 +010011932 retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
Willy Tarreau036fae02008-01-06 13:24:40 +010011933 generally work on local networks as long as there are no packet losses. This
11934 will prevent people from sending bare HTTP requests using telnet.
11935
11936 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +020011937 chunk of the incoming request. It should be set in the frontend to take
11938 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
11939 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +010011940
Willy Tarreau0f228a02015-05-01 15:37:53 +020011941 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
Baptiste Assmanneccdf432015-10-28 13:49:01 +010011942 "timeout client", "option http-buffer-request".
Willy Tarreau036fae02008-01-06 13:24:40 +010011943
Willy Tarreau844e3c52008-01-11 16:28:18 +010011944
11945timeout queue <timeout>
11946 Set the maximum time to wait in the queue for a connection slot to be free
11947 May be used in sections : defaults | frontend | listen | backend
11948 yes | no | yes | yes
11949 Arguments :
11950 <timeout> is the timeout value specified in milliseconds by default, but
11951 can be in any other unit if the number is suffixed by the unit,
11952 as explained at the top of this document.
11953
11954 When a server's maxconn is reached, connections are left pending in a queue
11955 which may be server-specific or global to the backend. In order not to wait
11956 indefinitely, a timeout is applied to requests pending in the queue. If the
11957 timeout is reached, it is considered that the request will almost never be
11958 served, so it is dropped and a 503 error is returned to the client.
11959
11960 The "timeout queue" statement allows to fix the maximum time for a request to
11961 be left pending in a queue. If unspecified, the same value as the backend's
11962 connection timeout ("timeout connect") is used, for backwards compatibility
11963 with older versions with no "timeout queue" parameter.
11964
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020011965 See also : "timeout connect".
Willy Tarreau844e3c52008-01-11 16:28:18 +010011966
11967
11968timeout server <timeout>
Willy Tarreau844e3c52008-01-11 16:28:18 +010011969 Set the maximum inactivity time on the server side.
11970 May be used in sections : defaults | frontend | listen | backend
11971 yes | no | yes | yes
11972 Arguments :
11973 <timeout> is the timeout value specified in milliseconds by default, but
11974 can be in any other unit if the number is suffixed by the unit,
11975 as explained at the top of this document.
11976
11977 The inactivity timeout applies when the server is expected to acknowledge or
11978 send data. In HTTP mode, this timeout is particularly important to consider
11979 during the first phase of the server's response, when it has to send the
11980 headers, as it directly represents the server's processing time for the
11981 request. To find out what value to put there, it's often good to start with
11982 what would be considered as unacceptable response times, then check the logs
11983 to observe the response time distribution, and adjust the value accordingly.
11984
11985 The value is specified in milliseconds by default, but can be in any other
11986 unit if the number is suffixed by the unit, as specified at the top of this
11987 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
11988 recommended that the client timeout remains equal to the server timeout in
11989 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010011990 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +010011991 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +010011992 seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
11993 with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
Willy Tarreauce887fd2012-05-12 12:50:00 +020011994 "timeout tunnel", which overrides "timeout client" and "timeout server" for
11995 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011996
11997 This parameter is specific to backends, but can be specified once for all in
11998 "defaults" sections. This is in fact one of the easiest solutions not to
11999 forget about it. An unspecified timeout results in an infinite timeout, which
12000 is not recommended. Such a usage is accepted and works but reports a warning
John Roeslerfb2fce12019-07-10 15:45:51 -050012001 during startup because it may result in accumulation of expired sessions in
Willy Tarreau844e3c52008-01-11 16:28:18 +010012002 the system if the system's timeouts are not configured either.
12003
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012004 See also : "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +010012005
Willy Tarreau05cdd962014-05-10 14:30:07 +020012006
12007timeout server-fin <timeout>
12008 Set the inactivity timeout on the server side for half-closed connections.
12009 May be used in sections : defaults | frontend | listen | backend
12010 yes | no | yes | yes
12011 Arguments :
12012 <timeout> is the timeout value specified in milliseconds by default, but
12013 can be in any other unit if the number is suffixed by the unit,
12014 as explained at the top of this document.
12015
12016 The inactivity timeout applies when the server is expected to acknowledge or
12017 send data while one direction is already shut down. This timeout is different
12018 from "timeout server" in that it only applies to connections which are closed
12019 in one direction. This is particularly useful to avoid keeping connections in
12020 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
12021 This problem is particularly common long connections such as RDP or WebSocket.
12022 Note that this timeout can override "timeout tunnel" when a connection shuts
12023 down in one direction. This setting was provided for completeness, but in most
12024 situations, it should not be needed.
12025
12026 This parameter is specific to backends, but can be specified once for all in
12027 "defaults" sections. By default it is not set, so half-closed connections
12028 will use the other timeouts (timeout.server or timeout.tunnel).
12029
12030 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
12031
Willy Tarreau844e3c52008-01-11 16:28:18 +010012032
12033timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +010012034 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +010012035 May be used in sections : defaults | frontend | listen | backend
12036 yes | yes | yes | yes
12037 Arguments :
12038 <timeout> is the tarpit duration specified in milliseconds by default, but
12039 can be in any other unit if the number is suffixed by the unit,
12040 as explained at the top of this document.
12041
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020012042 When a connection is tarpitted using "http-request tarpit", it is maintained
12043 open with no activity for a certain amount of time, then closed. "timeout
12044 tarpit" defines how long it will be maintained open.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012045
12046 The value is specified in milliseconds by default, but can be in any other
12047 unit if the number is suffixed by the unit, as specified at the top of this
12048 document. If unspecified, the same value as the backend's connection timeout
12049 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +010012050 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012051
Tim Duesterhus86e6b6e2019-05-14 20:57:59 +020012052 See also : "timeout connect".
Willy Tarreau844e3c52008-01-11 16:28:18 +010012053
12054
Willy Tarreauce887fd2012-05-12 12:50:00 +020012055timeout tunnel <timeout>
12056 Set the maximum inactivity time on the client and server side for tunnels.
12057 May be used in sections : defaults | frontend | listen | backend
12058 yes | no | yes | yes
12059 Arguments :
12060 <timeout> is the timeout value specified in milliseconds by default, but
12061 can be in any other unit if the number is suffixed by the unit,
12062 as explained at the top of this document.
12063
Jamie Gloudonaaa21002012-08-25 00:18:33 -040012064 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +020012065 between a client and a server, and the connection remains inactive in both
12066 directions. This timeout supersedes both the client and server timeouts once
12067 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
Davor Ocelice9ed2812017-12-25 17:49:28 +010012068 analyzer remains attached to either connection (e.g. tcp content rules are
12069 accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
Willy Tarreauce887fd2012-05-12 12:50:00 +020012070 when switching to the WebSocket protocol, or forwarding a CONNECT request
12071 to a proxy), or after the first response when no keepalive/close option is
12072 specified.
12073
Willy Tarreau05cdd962014-05-10 14:30:07 +020012074 Since this timeout is usually used in conjunction with long-lived connections,
12075 it usually is a good idea to also set "timeout client-fin" to handle the
12076 situation where a client suddenly disappears from the net and does not
12077 acknowledge a close, or sends a shutdown and does not acknowledge pending
12078 data anymore. This can happen in lossy networks where firewalls are present,
12079 and is detected by the presence of large amounts of sessions in a FIN_WAIT
12080 state.
12081
Willy Tarreauce887fd2012-05-12 12:50:00 +020012082 The value is specified in milliseconds by default, but can be in any other
12083 unit if the number is suffixed by the unit, as specified at the top of this
12084 document. Whatever the expected normal idle time, it is a good practice to
12085 cover at least one or several TCP packet losses by specifying timeouts that
Davor Ocelice9ed2812017-12-25 17:49:28 +010012086 are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreauce887fd2012-05-12 12:50:00 +020012087
12088 This parameter is specific to backends, but can be specified once for all in
12089 "defaults" sections. This is in fact one of the easiest solutions not to
12090 forget about it.
12091
12092 Example :
12093 defaults http
12094 option http-server-close
12095 timeout connect 5s
12096 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +020012097 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +020012098 timeout server 30s
12099 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
12100
Willy Tarreau05cdd962014-05-10 14:30:07 +020012101 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +020012102
12103
Willy Tarreau844e3c52008-01-11 16:28:18 +010012104transparent (deprecated)
12105 Enable client-side transparent proxying
12106 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +010012107 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +010012108 Arguments : none
12109
12110 This keyword was introduced in order to provide layer 7 persistence to layer
12111 3 load balancers. The idea is to use the OS's ability to redirect an incoming
12112 connection for a remote address to a local process (here HAProxy), and let
12113 this process know what address was initially requested. When this option is
12114 used, sessions without cookies will be forwarded to the original destination
12115 IP address of the incoming request (which should match that of another
12116 equipment), while requests with cookies will still be forwarded to the
12117 appropriate server.
12118
12119 The "transparent" keyword is deprecated, use "option transparent" instead.
12120
12121 Note that contrary to a common belief, this option does NOT make HAProxy
12122 present the client's IP to the server when establishing the connection.
12123
Willy Tarreau844e3c52008-01-11 16:28:18 +010012124 See also: "option transparent"
12125
William Lallemanda73203e2012-03-12 12:48:57 +010012126unique-id-format <string>
12127 Generate a unique ID for each request.
12128 May be used in sections : defaults | frontend | listen | backend
12129 yes | yes | yes | no
12130 Arguments :
12131 <string> is a log-format string.
12132
Cyril Bonté108cf6e2012-04-21 23:30:29 +020012133 This keyword creates a ID for each request using the custom log format. A
12134 unique ID is useful to trace a request passing through many components of
12135 a complex infrastructure. The newly created ID may also be logged using the
12136 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +010012137
Cyril Bonté108cf6e2012-04-21 23:30:29 +020012138 The format should be composed from elements that are guaranteed to be
12139 unique when combined together. For instance, if multiple haproxy instances
12140 are involved, it might be important to include the node name. It is often
12141 needed to log the incoming connection's source and destination addresses
12142 and ports. Note that since multiple requests may be performed over the same
12143 connection, including a request counter may help differentiate them.
12144 Similarly, a timestamp may protect against a rollover of the counter.
12145 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +010012146
Cyril Bonté108cf6e2012-04-21 23:30:29 +020012147 It is recommended to use hexadecimal notation for many fields since it
12148 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +010012149
Cyril Bonté108cf6e2012-04-21 23:30:29 +020012150 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010012151
Julien Vehentf21be322014-03-07 08:27:34 -050012152 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010012153
12154 will generate:
12155
12156 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
12157
12158 See also: "unique-id-header"
12159
12160unique-id-header <name>
12161 Add a unique ID header in the HTTP request.
12162 May be used in sections : defaults | frontend | listen | backend
12163 yes | yes | yes | no
12164 Arguments :
12165 <name> is the name of the header.
12166
Cyril Bonté108cf6e2012-04-21 23:30:29 +020012167 Add a unique-id header in the HTTP request sent to the server, using the
12168 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +010012169
Cyril Bonté108cf6e2012-04-21 23:30:29 +020012170 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010012171
Julien Vehentf21be322014-03-07 08:27:34 -050012172 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010012173 unique-id-header X-Unique-ID
12174
12175 will generate:
12176
12177 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
12178
12179 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +010012180
Willy Tarreauf51658d2014-04-23 01:21:56 +020012181use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020012182 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012183 May be used in sections : defaults | frontend | listen | backend
12184 no | yes | yes | no
12185 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010012186 <backend> is the name of a valid backend or "listen" section, or a
12187 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012188
Willy Tarreauf51658d2014-04-23 01:21:56 +020012189 <condition> is a condition composed of ACLs, as described in section 7. If
12190 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012191
12192 When doing content-switching, connections arrive on a frontend and are then
12193 dispatched to various backends depending on a number of conditions. The
12194 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020012195 "use_backend" keyword. While it is normally used with HTTP processing, it can
Davor Ocelice9ed2812017-12-25 17:49:28 +010012196 also be used in pure TCP, either without content using stateless ACLs (e.g.
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020012197 source address validation) or combined with a "tcp-request" rule to wait for
12198 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +010012199
12200 There may be as many "use_backend" rules as desired. All of these rules are
12201 evaluated in their declaration order, and the first one which matches will
12202 assign the backend.
12203
12204 In the first form, the backend will be used if the condition is met. In the
12205 second form, the backend will be used if the condition is not met. If no
12206 condition is valid, the backend defined with "default_backend" will be used.
12207 If no default backend is defined, either the servers in the same section are
12208 used (in case of a "listen" section) or, in case of a frontend, no server is
12209 used and a 503 service unavailable response is returned.
12210
Willy Tarreau51aecc72009-07-12 09:47:04 +020012211 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012212 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +020012213 and backend processing will immediately follow, or the backend will wait for
12214 a complete HTTP request to get in. This feature is useful when a frontend
12215 must decode several protocols on a unique port, one of them being HTTP.
12216
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010012217 When <backend> is a simple name, it is resolved at configuration time, and an
12218 error is reported if the specified backend does not exist. If <backend> is
12219 a log-format string instead, no check may be done at configuration time, so
12220 the backend name is resolved dynamically at run time. If the resulting
12221 backend name does not correspond to any valid backend, no other rule is
12222 evaluated, and the default_backend directive is applied instead. Note that
12223 when using dynamic backend names, it is highly recommended to use a prefix
12224 that no other backend uses in order to ensure that an unauthorized backend
12225 cannot be forced from the request.
12226
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012227 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010012228 used to detect the association between frontends and backends to compute the
12229 backend's "fullconn" setting. This cannot be done for dynamic names.
12230
12231 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
12232 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +010012233
Christopher Fauletb30b3102019-09-12 23:03:09 +020012234use-fcgi-app <name>
12235 Defines the FastCGI application to use for the backend.
12236 May be used in sections : defaults | frontend | listen | backend
12237 no | no | yes | yes
12238 Arguments :
12239 <name> is the name of the FastCGI application to use.
12240
12241 See section 10.1 about FastCGI application setup for details.
Willy Tarreau036fae02008-01-06 13:24:40 +010012242
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012243use-server <server> if <condition>
12244use-server <server> unless <condition>
12245 Only use a specific server if/unless an ACL-based condition is matched.
12246 May be used in sections : defaults | frontend | listen | backend
12247 no | no | yes | yes
12248 Arguments :
Jerome Magnin824186b2020-03-29 09:37:12 +020012249 <server> is the name of a valid server in the same backend section
12250 or a "log-format" string resolving to a server name.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012251
12252 <condition> is a condition composed of ACLs, as described in section 7.
12253
12254 By default, connections which arrive to a backend are load-balanced across
12255 the available servers according to the configured algorithm, unless a
12256 persistence mechanism such as a cookie is used and found in the request.
12257
12258 Sometimes it is desirable to forward a particular request to a specific
12259 server without having to declare a dedicated backend for this server. This
12260 can be achieved using the "use-server" rules. These rules are evaluated after
12261 the "redirect" rules and before evaluating cookies, and they have precedence
12262 on them. There may be as many "use-server" rules as desired. All of these
12263 rules are evaluated in their declaration order, and the first one which
12264 matches will assign the server.
12265
12266 If a rule designates a server which is down, and "option persist" is not used
12267 and no force-persist rule was validated, it is ignored and evaluation goes on
12268 with the next rules until one matches.
12269
12270 In the first form, the server will be used if the condition is met. In the
12271 second form, the server will be used if the condition is not met. If no
12272 condition is valid, the processing continues and the server will be assigned
12273 according to other persistence mechanisms.
12274
12275 Note that even if a rule is matched, cookie processing is still performed but
12276 does not assign the server. This allows prefixed cookies to have their prefix
12277 stripped.
12278
12279 The "use-server" statement works both in HTTP and TCP mode. This makes it
12280 suitable for use with content-based inspection. For instance, a server could
Lukas Tribusa267b5d2020-07-19 00:25:06 +020012281 be selected in a farm according to the TLS SNI field when using protocols with
12282 implicit TLS (also see "req_ssl_sni"). And if these servers have their weight
12283 set to zero, they will not be used for other traffic.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012284
12285 Example :
12286 # intercept incoming TLS requests based on the SNI field
12287 use-server www if { req_ssl_sni -i www.example.com }
12288 server www 192.168.0.1:443 weight 0
12289 use-server mail if { req_ssl_sni -i mail.example.com }
Lukas Tribusa267b5d2020-07-19 00:25:06 +020012290 server mail 192.168.0.1:465 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012291 use-server imap if { req_ssl_sni -i imap.example.com }
Lukas Tribus98a3e3f2017-03-26 12:55:35 +000012292 server imap 192.168.0.1:993 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012293 # all the rest is forwarded to this server
12294 server default 192.168.0.2:443 check
12295
Jerome Magnin824186b2020-03-29 09:37:12 +020012296 When <server> is a simple name, it is checked against existing servers in the
12297 configuration and an error is reported if the specified server does not exist.
12298 If it is a log-format, no check is performed when parsing the configuration,
12299 and if we can't resolve a valid server name at runtime but the use-server rule
Ilya Shipitsin11057a32020-06-21 21:18:27 +050012300 was conditioned by an ACL returning true, no other use-server rule is applied
Jerome Magnin824186b2020-03-29 09:37:12 +020012301 and we fall back to load balancing.
12302
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012303 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012304
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012305
Davor Ocelice9ed2812017-12-25 17:49:28 +0100123065. Bind and server options
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012307--------------------------
12308
12309The "bind", "server" and "default-server" keywords support a number of settings
12310depending on some build options and on the system HAProxy was built on. These
12311settings generally each consist in one word sometimes followed by a value,
12312written on the same line as the "bind" or "server" line. All these options are
12313described in this section.
12314
12315
123165.1. Bind options
12317-----------------
12318
12319The "bind" keyword supports a certain number of settings which are all passed
12320as arguments on the same line. The order in which those arguments appear makes
12321no importance, provided that they appear after the bind address. All of these
12322parameters are optional. Some of them consist in a single words (booleans),
12323while other ones expect a value after them. In this case, the value must be
12324provided immediately after the setting name.
12325
12326The currently supported settings are the following ones.
12327
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010012328accept-netscaler-cip <magic number>
12329 Enforces the use of the NetScaler Client IP insertion protocol over any
12330 connection accepted by any of the TCP sockets declared on the same line. The
12331 NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
12332 the incoming connection to be used everywhere an address is used, with the
12333 only exception of "tcp-request connection" rules which will only see the
12334 real connection address. Logs will reflect the addresses indicated in the
12335 protocol, unless it is violated, in which case the real address will still
12336 be used. This keyword combined with support from external components can be
12337 used as an efficient and reliable alternative to the X-Forwarded-For
Bertrand Jacquin90759682016-06-06 15:35:39 +010012338 mechanism which is not always reliable and not even always usable. See also
12339 "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
12340 which client is allowed to use the protocol.
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010012341
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012342accept-proxy
12343 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +020012344 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
12345 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012346 3/4 addresses of the incoming connection to be used everywhere an address is
12347 used, with the only exception of "tcp-request connection" rules which will
12348 only see the real connection address. Logs will reflect the addresses
12349 indicated in the protocol, unless it is violated, in which case the real
Davor Ocelice9ed2812017-12-25 17:49:28 +010012350 address will still be used. This keyword combined with support from external
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012351 components can be used as an efficient and reliable alternative to the
12352 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +020012353 usable. See also "tcp-request connection expect-proxy" for a finer-grained
12354 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012355
Olivier Houchardc2aae742017-09-22 18:26:28 +020012356allow-0rtt
Bertrand Jacquina25282b2018-08-14 00:56:13 +010012357 Allow receiving early data when using TLSv1.3. This is disabled by default,
Olivier Houchard69752962019-01-08 15:35:32 +010012358 due to security considerations. Because it is vulnerable to replay attacks,
John Roeslerfb2fce12019-07-10 15:45:51 -050012359 you should only allow if for requests that are safe to replay, i.e. requests
Olivier Houchard69752962019-01-08 15:35:32 +010012360 that are idempotent. You can use the "wait-for-handshake" action for any
12361 request that wouldn't be safe with early data.
Olivier Houchardc2aae742017-09-22 18:26:28 +020012362
Willy Tarreauab861d32013-04-02 02:30:41 +020012363alpn <protocols>
12364 This enables the TLS ALPN extension and advertises the specified protocol
12365 list as supported on top of ALPN. The protocol list consists in a comma-
12366 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roeslerfb2fce12019-07-10 15:45:51 -050012367 quotes). This requires that the SSL library is built with support for TLS
Willy Tarreauab861d32013-04-02 02:30:41 +020012368 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
Willy Tarreau95c4e142017-11-26 12:18:55 +010012369 initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
12370 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
12371 now obsolete NPN extension. At the time of writing this, most browsers still
12372 support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
12373 a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
12374 are expected to be supported, both versions can be advertised, in order of
12375 preference, like below :
12376
12377 bind :443 ssl crt pub.pem alpn h2,http/1.1
Willy Tarreauab861d32013-04-02 02:30:41 +020012378
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012379backlog <backlog>
Willy Tarreaue2711c72019-02-27 15:39:41 +010012380 Sets the socket's backlog to this value. If unspecified or 0, the frontend's
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012381 backlog is used instead, which generally defaults to the maxconn value.
12382
Emmanuel Hocdete7f2b732017-01-09 16:15:54 +010012383curves <curves>
12384 This setting is only available when support for OpenSSL was built in. It sets
12385 the string describing the list of elliptic curves algorithms ("curve suite")
12386 that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
12387 string is a colon-delimited list of curve name.
12388 Example: "X25519:P-256" (without quote)
12389 When "curves" is set, "ecdhe" parameter is ignored.
12390
Emeric Brun7fb34422012-09-28 15:26:15 +020012391ecdhe <named curve>
12392 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +010012393 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
12394 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +020012395
Emeric Brunfd33a262012-10-11 16:28:27 +020012396ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +020012397 This setting is only available when support for OpenSSL was built in. It
12398 designates a PEM file from which to load CA certificates used to verify
12399 client's certificate.
12400
Emeric Brunb6dc9342012-09-28 17:55:37 +020012401ca-ignore-err [all|<errorID>,...]
12402 This setting is only available when support for OpenSSL was built in.
12403 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
12404 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
12405 error is ignored.
12406
Christopher Faulet31af49d2015-06-09 17:29:50 +020012407ca-sign-file <cafile>
12408 This setting is only available when support for OpenSSL was built in. It
12409 designates a PEM file containing both the CA certificate and the CA private
12410 key used to create and sign server's certificates. This is a mandatory
12411 setting when the dynamic generation of certificates is enabled. See
12412 'generate-certificates' for details.
12413
Bertrand Jacquind4d0a232016-11-13 16:37:12 +000012414ca-sign-pass <passphrase>
Christopher Faulet31af49d2015-06-09 17:29:50 +020012415 This setting is only available when support for OpenSSL was built in. It is
12416 the CA private key passphrase. This setting is optional and used only when
12417 the dynamic generation of certificates is enabled. See
12418 'generate-certificates' for details.
12419
Emmanuel Hocdet842e94e2019-12-16 16:39:17 +010012420ca-verify-file <cafile>
12421 This setting designates a PEM file from which to load CA certificates used to
12422 verify client's certificate. It designates CA certificates which must not be
12423 included in CA names sent in server hello message. Typically, "ca-file" must
12424 be defined with intermediate certificates, and "ca-verify-file" with
12425 certificates to ending the chain, like root CA.
12426
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012427ciphers <ciphers>
12428 This setting is only available when support for OpenSSL was built in. It sets
12429 the string describing the list of cipher algorithms ("cipher suite") that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +000012430 negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000012431 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
Dirkjan Bussink415150f2018-09-14 11:14:21 +020012432 information and recommendations see e.g.
12433 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
12434 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
12435 cipher configuration, please check the "ciphersuites" keyword.
12436
12437ciphersuites <ciphersuites>
12438 This setting is only available when support for OpenSSL was built in and
12439 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
12440 the list of cipher algorithms ("cipher suite") that are negotiated during the
12441 TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000012442 OpenSSL man pages under the "ciphersuites" section. For cipher configuration
12443 for TLSv1.2 and earlier, please check the "ciphers" keyword.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012444
Emeric Brunfd33a262012-10-11 16:28:27 +020012445crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +020012446 This setting is only available when support for OpenSSL was built in. It
12447 designates a PEM file from which to load certificate revocation list used
12448 to verify client's certificate.
12449
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012450crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +000012451 This setting is only available when support for OpenSSL was built in. It
12452 designates a PEM file containing both the required certificates and any
12453 associated private keys. This file can be built by concatenating multiple
12454 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
12455 requires an intermediate certificate, this can also be concatenated into this
Emmanuel Hocdet70df7bf2019-01-04 11:08:20 +010012456 file. Intermediate certificate can also be shared in a directory via
12457 "issuers-chain-path" directive.
Alex Davies0fbf0162013-03-02 16:04:50 +000012458
William Lallemand4c5adbf2020-02-24 14:23:22 +010012459 If the file does not contain a private key, HAProxy will try to load
12460 the key at the same path suffixed by a ".key".
12461
Alex Davies0fbf0162013-03-02 16:04:50 +000012462 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
12463 are loaded.
12464
12465 If a directory name is used instead of a PEM file, then all files found in
William Lallemand3f25ae32020-02-24 16:30:12 +010012466 that directory will be loaded in alphabetic order unless their name ends
12467 with '.key', '.issuer', '.ocsp' or '.sctl' (reserved extensions). This
12468 directive may be specified multiple times in order to load certificates from
12469 multiple files or directories. The certificates will be presented to clients
12470 who provide a valid TLS Server Name Indication field matching one of their
12471 CN or alt subjects. Wildcards are supported, where a wildcard character '*'
12472 is used instead of the first hostname component (e.g. *.example.org matches
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010012473 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +000012474
12475 If no SNI is provided by the client or if the SSL library does not support
12476 TLS extensions, or if the client provides an SNI hostname which does not
12477 match any certificate, then the first loaded certificate will be presented.
12478 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +010012479 recommended to load the default one first as a file or to ensure that it will
12480 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +000012481
Emeric Brune032bfa2012-09-28 13:01:45 +020012482 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012483
Davor Ocelice9ed2812017-12-25 17:49:28 +010012484 Some CAs (such as GoDaddy) offer a drop down list of server types that do not
Alex Davies0fbf0162013-03-02 16:04:50 +000012485 include HAProxy when obtaining a certificate. If this happens be sure to
Davor Ocelice9ed2812017-12-25 17:49:28 +010012486 choose a web server that the CA believes requires an intermediate CA (for
12487 GoDaddy, selection Apache Tomcat will get the correct bundle, but many
Alex Davies0fbf0162013-03-02 16:04:50 +000012488 others, e.g. nginx, result in a wrong bundle that will not work for some
12489 clients).
12490
Emeric Brun4147b2e2014-06-16 18:36:30 +020012491 For each PEM file, haproxy checks for the presence of file at the same path
12492 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
12493 Status Request extension (also known as "OCSP stapling") is automatically
12494 enabled. The content of this file is optional. If not empty, it must contain
12495 a valid OCSP Response in DER format. In order to be valid an OCSP Response
12496 must comply with the following rules: it has to indicate a good status,
12497 it has to be a single response for the certificate of the PEM file, and it
12498 has to be valid at the moment of addition. If these rules are not respected
12499 the OCSP Response is ignored and a warning is emitted. In order to identify
12500 which certificate an OCSP Response applies to, the issuer's certificate is
12501 necessary. If the issuer's certificate is not found in the PEM file, it will
12502 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
12503 if it exists otherwise it will fail with an error.
12504
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010012505 For each PEM file, haproxy also checks for the presence of file at the same
12506 path suffixed by ".sctl". If such file is found, support for Certificate
12507 Transparency (RFC6962) TLS extension is enabled. The file must contain a
12508 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
12509 to check basic syntax, but no signatures are verified.
12510
yanbzhu6c25e9e2016-01-05 12:52:02 -050012511 There are cases where it is desirable to support multiple key types, e.g. RSA
12512 and ECDSA in the cipher suites offered to the clients. This allows clients
12513 that support EC certificates to be able to use EC ciphers, while
12514 simultaneously supporting older, RSA only clients.
yanbzhud19630c2015-12-14 15:10:25 -050012515
William Lallemand98d215e2020-09-16 17:42:37 +020012516 In order to provide this feature, multiple PEM files, each with a different
12517 key type, are required. Since HAProxy 2.3, at least OpenSSL 1.1.1 is
12518 required to use this feature. It can be configured by adding each file in
12519 the configuration, which is the recommended way, or by using a "cert
12520 bundle".
12521
12522 To associate these PEM files into a "cert bundle" that is recognized by
12523 haproxy, they must be named in the following way: All PEM files that are to
12524 be bundled must have the same base name, with a suffix indicating the key
12525 type. Currently, three suffixes are supported: rsa, dsa and ecdsa. For
12526 example, if www.example.com has two PEM files, an RSA file and an ECDSA
12527 file, they must be named: "example.pem.rsa" and "example.pem.ecdsa". The
12528 first part of the filename is arbitrary; only the suffix matters. To load
12529 this bundle into haproxy, specify the base name only:
yanbzhud19630c2015-12-14 15:10:25 -050012530
12531 Example : bind :8443 ssl crt example.pem
12532
yanbzhu6c25e9e2016-01-05 12:52:02 -050012533 Note that the suffix is not given to haproxy; this tells haproxy to look for
yanbzhud19630c2015-12-14 15:10:25 -050012534 a cert bundle.
12535
Davor Ocelice9ed2812017-12-25 17:49:28 +010012536 HAProxy will load all PEM files in the bundle at the same time to try to
yanbzhud19630c2015-12-14 15:10:25 -050012537 support multiple key types. PEM files are combined based on Common Name
12538 (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means
12539 that even if you give haproxy a cert bundle, if there are no shared CN/SAN
12540 entries in the certificates in that bundle, haproxy will not be able to
12541 provide multi-cert support.
12542
12543 Assuming bundle in the example above contained the following:
12544
12545 Filename | CN | SAN
12546 -------------------+-----------------+-------------------
12547 example.pem.rsa | www.example.com | rsa.example.com
yanbzhu6c25e9e2016-01-05 12:52:02 -050012548 -------------------+-----------------+-------------------
yanbzhud19630c2015-12-14 15:10:25 -050012549 example.pem.ecdsa | www.example.com | ecdsa.example.com
12550 -------------------+-----------------+-------------------
12551
12552 Users connecting with an SNI of "www.example.com" will be able
12553 to use both RSA and ECDSA cipher suites. Users connecting with an SNI of
12554 "rsa.example.com" will only be able to use RSA cipher suites, and users
12555 connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020012556 suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
12557 no need to bundle certificates. ECDSA certificate will be preferred if client
12558 support it.
yanbzhud19630c2015-12-14 15:10:25 -050012559
12560 If a directory name is given as the <cert> argument, haproxy will
12561 automatically search and load bundled files in that directory.
12562
12563 OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
12564 bundling. Each certificate can have its own .ocsp and .issuer file. At this
12565 time, sctl is not supported in multi-certificate bundling.
12566
Emeric Brunb6dc9342012-09-28 17:55:37 +020012567crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +000012568 This setting is only available when support for OpenSSL was built in. Sets a
Davor Ocelice9ed2812017-12-25 17:49:28 +010012569 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012570 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +000012571 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +020012572
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010012573crt-list <file>
12574 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet98263292016-12-29 18:26:15 +010012575 designates a list of PEM file with an optional ssl configuration and a SNI
12576 filter per certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010012577
Emmanuel Hocdet98263292016-12-29 18:26:15 +010012578 <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
12579
William Lallemand5d036392020-06-30 16:11:36 +020012580 sslbindconf supports "allow-0rtt", "alpn", "ca-file", "ca-verify-file",
12581 "ciphers", "ciphersuites", "crl-file", "curves", "ecdhe", "no-ca-names",
12582 "npn", "verify" configuration. With BoringSSL and Openssl >= 1.1.1
12583 "ssl-min-ver" and "ssl-max-ver" are also supported. It overrides the
12584 configuration set in bind line for the certificate.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010012585
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020012586 Wildcards are supported in the SNI filter. Negative filter are also supported,
12587 only useful in combination with a wildcard filter to exclude a particular SNI.
12588 The certificates will be presented to clients who provide a valid TLS Server
12589 Name Indication field matching one of the SNI filters. If no SNI filter is
12590 specified, the CN and alt subjects are used. This directive may be specified
12591 multiple times. See the "crt" option for more information. The default
12592 certificate is still needed to meet OpenSSL expectations. If it is not used,
12593 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010012594
yanbzhu6c25e9e2016-01-05 12:52:02 -050012595 Multi-cert bundling (see "crt") is supported with crt-list, as long as only
Emmanuel Hocdetd294aea2016-05-13 11:14:06 +020012596 the base name is given in the crt-list. SNI filter will do the same work on
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020012597 all bundled certificates. With BoringSSL and Openssl >= 1.1.1 multi-cert is
12598 natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
12599 be declared in a row, and set different ssl and filter parameter.
yanbzhud19630c2015-12-14 15:10:25 -050012600
William Lallemand7c26ed72020-06-03 17:34:48 +020012601 Empty lines as well as lines beginning with a hash ('#') will be ignored.
12602
Emmanuel Hocdet98263292016-12-29 18:26:15 +010012603 crt-list file example:
12604 cert1.pem
William Lallemand7c26ed72020-06-03 17:34:48 +020012605 # comment
Emmanuel Hocdet05942112017-02-20 16:11:50 +010012606 cert2.pem [alpn h2,http/1.1]
Emmanuel Hocdet98263292016-12-29 18:26:15 +010012607 certW.pem *.domain.tld !secure.domain.tld
Emmanuel Hocdet05942112017-02-20 16:11:50 +010012608 certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
Emmanuel Hocdet98263292016-12-29 18:26:15 +010012609
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012610defer-accept
12611 Is an optional keyword which is supported only on certain Linux kernels. It
12612 states that a connection will only be accepted once some data arrive on it,
12613 or at worst after the first retransmit. This should be used only on protocols
Davor Ocelice9ed2812017-12-25 17:49:28 +010012614 for which the client talks first (e.g. HTTP). It can slightly improve
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012615 performance by ensuring that most of the request is already available when
12616 the connection is accepted. On the other hand, it will not be able to detect
12617 connections which don't talk. It is important to note that this option is
12618 broken in all kernels up to 2.6.31, as the connection is never accepted until
12619 the client talks. This can cause issues with front firewalls which would see
12620 an established connection while the proxy will only see it in SYN_RECV. This
12621 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
12622
William Lallemandf6975e92017-05-26 17:42:10 +020012623expose-fd listeners
12624 This option is only usable with the stats socket. It gives your stats socket
12625 the capability to pass listeners FD to another HAProxy process.
William Lallemande202b1e2017-06-01 17:38:56 +020012626 During a reload with the master-worker mode, the process is automatically
12627 reexecuted adding -x and one of the stats socket with this option.
Davor Ocelice9ed2812017-12-25 17:49:28 +010012628 See also "-x" in the management guide.
William Lallemandf6975e92017-05-26 17:42:10 +020012629
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012630force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012631 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012632 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012633 for high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012634 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012635
12636force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012637 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012638 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012639 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012640
12641force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012642 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012643 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012644 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012645
12646force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012647 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012648 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012649 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012650
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012651force-tlsv13
12652 This option enforces use of TLSv1.3 only on SSL connections instantiated from
12653 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012654 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012655
Christopher Faulet31af49d2015-06-09 17:29:50 +020012656generate-certificates
12657 This setting is only available when support for OpenSSL was built in. It
12658 enables the dynamic SSL certificates generation. A CA certificate and its
12659 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
12660 a transparent forward proxy, SSL requests generate errors because of a common
12661 name mismatch on the certificate presented to the client. With this option
12662 enabled, HAProxy will try to forge a certificate using the SNI hostname
12663 indicated by the client. This is done only if no certificate matches the SNI
12664 hostname (see 'crt-list'). If an error occurs, the default certificate is
12665 used, else the 'strict-sni' option is set.
12666 It can also be used when HAProxy is configured as a reverse proxy to ease the
12667 deployment of an architecture with many backends.
12668
12669 Creating a SSL certificate is an expensive operation, so a LRU cache is used
12670 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
Davor Ocelice9ed2812017-12-25 17:49:28 +010012671 increases the HAProxy's memory footprint to reduce latency when the same
Christopher Faulet31af49d2015-06-09 17:29:50 +020012672 certificate is used many times.
12673
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012674gid <gid>
12675 Sets the group of the UNIX sockets to the designated system gid. It can also
12676 be set by default in the global section's "unix-bind" statement. Note that
12677 some platforms simply ignore this. This setting is equivalent to the "group"
12678 setting except that the group ID is used instead of its name. This setting is
12679 ignored by non UNIX sockets.
12680
12681group <group>
12682 Sets the group of the UNIX sockets to the designated system group. It can
12683 also be set by default in the global section's "unix-bind" statement. Note
12684 that some platforms simply ignore this. This setting is equivalent to the
12685 "gid" setting except that the group name is used instead of its gid. This
12686 setting is ignored by non UNIX sockets.
12687
12688id <id>
12689 Fixes the socket ID. By default, socket IDs are automatically assigned, but
12690 sometimes it is more convenient to fix them to ease monitoring. This value
12691 must be strictly positive and unique within the listener/frontend. This
12692 option can only be used when defining only a single socket.
12693
12694interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +010012695 Restricts the socket to a specific interface. When specified, only packets
12696 received from that particular interface are processed by the socket. This is
12697 currently only supported on Linux. The interface must be a primary system
12698 interface, not an aliased interface. It is also possible to bind multiple
12699 frontends to the same address if they are bound to different interfaces. Note
12700 that binding to a network interface requires root privileges. This parameter
Jérôme Magnin61275192018-02-07 11:39:58 +010012701 is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic
12702 uses the same interface as inbound traffic, and its associated routing table,
12703 even if there are explicit routes through different interfaces configured.
12704 This can prove useful to address asymmetric routing issues when the same
12705 client IP addresses need to be able to reach frontends hosted on different
12706 interfaces.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012707
Willy Tarreauabb175f2012-09-24 12:43:26 +020012708level <level>
12709 This setting is used with the stats sockets only to restrict the nature of
12710 the commands that can be issued on the socket. It is ignored by other
12711 sockets. <level> can be one of :
Davor Ocelice9ed2812017-12-25 17:49:28 +010012712 - "user" is the least privileged level; only non-sensitive stats can be
Willy Tarreauabb175f2012-09-24 12:43:26 +020012713 read, and no change is allowed. It would make sense on systems where it
12714 is not easy to restrict access to the socket.
12715 - "operator" is the default level and fits most common uses. All data can
Davor Ocelice9ed2812017-12-25 17:49:28 +010012716 be read, and only non-sensitive changes are permitted (e.g. clear max
Willy Tarreauabb175f2012-09-24 12:43:26 +020012717 counters).
Davor Ocelice9ed2812017-12-25 17:49:28 +010012718 - "admin" should be used with care, as everything is permitted (e.g. clear
Willy Tarreauabb175f2012-09-24 12:43:26 +020012719 all counters).
12720
Andjelko Iharosc4df59e2017-07-20 11:59:48 +020012721severity-output <format>
12722 This setting is used with the stats sockets only to configure severity
12723 level output prepended to informational feedback messages. Severity
12724 level of messages can range between 0 and 7, conforming to syslog
12725 rfc5424. Valid and successful socket commands requesting data
12726 (i.e. "show map", "get acl foo" etc.) will never have a severity level
12727 prepended. It is ignored by other sockets. <format> can be one of :
12728 - "none" (default) no severity level is prepended to feedback messages.
12729 - "number" severity level is prepended as a number.
12730 - "string" severity level is prepended as a string following the
12731 rfc5424 convention.
12732
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012733maxconn <maxconn>
12734 Limits the sockets to this number of concurrent connections. Extraneous
12735 connections will remain in the system's backlog until a connection is
12736 released. If unspecified, the limit will be the same as the frontend's
12737 maxconn. Note that in case of port ranges or multiple addresses, the same
12738 value will be applied to each socket. This setting enables different
12739 limitations on expensive sockets, for instance SSL entries which may easily
12740 eat all memory.
12741
12742mode <mode>
12743 Sets the octal mode used to define access permissions on the UNIX socket. It
12744 can also be set by default in the global section's "unix-bind" statement.
12745 Note that some platforms simply ignore this. This setting is ignored by non
12746 UNIX sockets.
12747
12748mss <maxseg>
12749 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
12750 connections. This can be used to force a lower MSS for certain specific
12751 ports, for instance for connections passing through a VPN. Note that this
12752 relies on a kernel feature which is theoretically supported under Linux but
12753 was buggy in all versions prior to 2.6.28. It may or may not work on other
12754 operating systems. It may also not change the advertised value but change the
12755 effective size of outgoing segments. The commonly advertised value for TCPv4
12756 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
12757 positive, it will be used as the advertised MSS. If it is negative, it will
12758 indicate by how much to reduce the incoming connection's advertised MSS for
12759 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
12760
12761name <name>
12762 Sets an optional name for these sockets, which will be reported on the stats
12763 page.
12764
Willy Tarreaud72f0f32015-10-13 14:50:22 +020012765namespace <name>
12766 On Linux, it is possible to specify which network namespace a socket will
12767 belong to. This directive makes it possible to explicitly bind a listener to
12768 a namespace different from the default one. Please refer to your operating
12769 system's documentation to find more details about network namespaces.
12770
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012771nice <nice>
12772 Sets the 'niceness' of connections initiated from the socket. Value must be
12773 in the range -1024..1024 inclusive, and defaults to zero. Positive values
12774 means that such connections are more friendly to others and easily offer
12775 their place in the scheduler. On the opposite, negative values mean that
12776 connections want to run with a higher priority than others. The difference
12777 only happens under high loads when the system is close to saturation.
12778 Negative values are appropriate for low-latency or administration services,
12779 and high values are generally recommended for CPU intensive tasks such as SSL
12780 processing or bulk transfers which are less sensible to latency. For example,
12781 it may make sense to use a positive value for an SMTP socket and a negative
12782 one for an RDP socket.
12783
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020012784no-ca-names
12785 This setting is only available when support for OpenSSL was built in. It
12786 prevents from send CA names in server hello message when ca-file is used.
Emmanuel Hocdet842e94e2019-12-16 16:39:17 +010012787 Use "ca-verify-file" instead of "ca-file" with "no-ca-names".
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020012788
Emeric Brun9b3009b2012-10-05 11:55:06 +020012789no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012790 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012791 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012792 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012793 be enabled using any configuration option. This option is also available on
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012794 global statement "ssl-default-bind-options". Use "ssl-min-ver" and
12795 "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012796
Emeric Brun90ad8722012-10-02 14:00:59 +020012797no-tls-tickets
12798 This setting is only available when support for OpenSSL was built in. It
12799 disables the stateless session resumption (RFC 5077 TLS Ticket
12800 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012801 session resumption is more expensive in CPU usage. This option is also
12802 available on global statement "ssl-default-bind-options".
Lukas Tribusbdb386d2020-03-10 00:56:09 +010012803 The TLS ticket mechanism is only used up to TLS 1.2.
12804 Forward Secrecy is compromised with TLS tickets, unless ticket keys
12805 are periodically rotated (via reload or by using "tls-ticket-keys").
Emeric Brun90ad8722012-10-02 14:00:59 +020012806
Emeric Brun9b3009b2012-10-05 11:55:06 +020012807no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012808 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012809 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012810 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012811 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012812 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
12813 and "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012814
Emeric Brun9b3009b2012-10-05 11:55:06 +020012815no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +020012816 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012817 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012818 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012819 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012820 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
12821 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020012822
Emeric Brun9b3009b2012-10-05 11:55:06 +020012823no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +020012824 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012825 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020012826 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012827 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012828 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
12829 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020012830
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012831no-tlsv13
12832 This setting is only available when support for OpenSSL was built in. It
12833 disables support for TLSv1.3 on any sockets instantiated from the listener
12834 when SSL is supported. Note that SSLv2 is forced disabled in the code and
12835 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012836 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
12837 and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012838
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020012839npn <protocols>
12840 This enables the NPN TLS extension and advertises the specified protocol list
12841 as supported on top of NPN. The protocol list consists in a comma-delimited
12842 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roeslerfb2fce12019-07-10 15:45:51 -050012843 This requires that the SSL library is built with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +020012844 enabled (check with haproxy -vv). Note that the NPN extension has been
Willy Tarreau95c4e142017-11-26 12:18:55 +010012845 replaced with the ALPN extension (see the "alpn" keyword), though this one is
12846 only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
12847 version of OpenSSL, NPN might still be used as most clients still support it
12848 at the time of writing this. It is possible to enable both NPN and ALPN
12849 though it probably doesn't make any sense out of testing.
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020012850
Lukas Tribus53ae85c2017-05-04 15:45:40 +000012851prefer-client-ciphers
12852 Use the client's preference when selecting the cipher suite, by default
12853 the server's preference is enforced. This option is also available on
12854 global statement "ssl-default-bind-options".
Lukas Tribus926594f2018-05-18 17:55:57 +020012855 Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
12856 (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
12857 the client cipher list.
Lukas Tribus53ae85c2017-05-04 15:45:40 +000012858
Christopher Fauletc644fa92017-11-23 22:44:11 +010012859process <process-set>[/<thread-set>]
Willy Tarreaua36b3242019-02-02 13:14:34 +010012860 This restricts the list of processes or threads on which this listener is
Christopher Fauletc644fa92017-11-23 22:44:11 +010012861 allowed to run. It does not enforce any process but eliminates those which do
Davor Ocelice9ed2812017-12-25 17:49:28 +010012862 not match. If the frontend uses a "bind-process" setting, the intersection
Christopher Fauletc644fa92017-11-23 22:44:11 +010012863 between the two is applied. If in the end the listener is not allowed to run
12864 on any remaining process, a warning is emitted, and the listener will either
12865 run on the first process of the listener if a single process was specified,
12866 or on all of its processes if multiple processes were specified. If a thread
Davor Ocelice9ed2812017-12-25 17:49:28 +010012867 set is specified, it limits the threads allowed to process incoming
Willy Tarreaua36b3242019-02-02 13:14:34 +010012868 connections for this listener, for the the process set. If multiple processes
12869 and threads are configured, a warning is emitted, as it either results from a
12870 configuration error or a misunderstanding of these models. For the unlikely
12871 case where several ranges are needed, this directive may be repeated.
12872 <process-set> and <thread-set> must use the format
Christopher Fauletc644fa92017-11-23 22:44:11 +010012873
12874 all | odd | even | number[-[number]]
12875
12876 Ranges can be partially defined. The higher bound can be omitted. In such
12877 case, it is replaced by the corresponding maximum value. The main purpose of
12878 this directive is to be used with the stats sockets and have one different
12879 socket per process. The second purpose is to have multiple bind lines sharing
12880 the same IP:port but not the same process in a listener, so that the system
12881 can distribute the incoming connections into multiple queues and allow a
12882 smoother inter-process load balancing. Currently Linux 3.9 and above is known
12883 for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +020012884
Christopher Fauleta717b992018-04-10 14:43:00 +020012885proto <name>
12886 Forces the multiplexer's protocol to use for the incoming connections. It
12887 must be compatible with the mode of the frontend (TCP or HTTP). It must also
12888 be usable on the frontend side. The list of available protocols is reported
12889 in haproxy -vv.
Daniel Corbett67a82712020-07-06 23:01:19 -040012890 Idea behind this option is to bypass the selection of the best multiplexer's
Christopher Fauleta717b992018-04-10 14:43:00 +020012891 protocol for all connections instantiated from this listening socket. For
Joseph Herlant71b4b152018-11-13 16:55:16 -080012892 instance, it is possible to force the http/2 on clear TCP by specifying "proto
Christopher Fauleta717b992018-04-10 14:43:00 +020012893 h2" on the bind line.
12894
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012895ssl
12896 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012897 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012898 certificate is necessary (see "crt" above). All contents in the buffers will
12899 appear in clear text, so that ACLs and HTTP processing will only have access
Emmanuel Hocdetbd695fe2017-05-15 15:53:41 +020012900 to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
12901 to enable it.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012902
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012903ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12904 This option enforces use of <version> or lower on SSL connections instantiated
William Lallemand50df1cb2020-06-02 10:52:24 +020012905 from this listener. Using this setting without "ssl-min-ver" can be
12906 ambiguous because the default ssl-min-ver value could change in future HAProxy
12907 versions. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012908 "ssl-default-bind-options". See also "ssl-min-ver".
12909
12910ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
William Lallemand50df1cb2020-06-02 10:52:24 +020012911 This option enforces use of <version> or upper on SSL connections
12912 instantiated from this listener. The default value is "TLSv1.2". This option
12913 is also available on global statement "ssl-default-bind-options".
12914 See also "ssl-max-ver".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012915
Emmanuel Hocdet65623372013-01-24 17:17:15 +010012916strict-sni
12917 This setting is only available when support for OpenSSL was built in. The
12918 SSL/TLS negotiation is allow only if the client provided an SNI which match
12919 a certificate. The default certificate is not used.
12920 See the "crt" option for more information.
12921
Willy Tarreau2af207a2015-02-04 00:45:58 +010012922tcp-ut <delay>
Tim Düsterhus4896c442016-11-29 02:15:19 +010012923 Sets the TCP User Timeout for all incoming connections instantiated from this
Willy Tarreau2af207a2015-02-04 00:45:58 +010012924 listening socket. This option is available on Linux since version 2.6.37. It
12925 allows haproxy to configure a timeout for sockets which contain data not
Davor Ocelice9ed2812017-12-25 17:49:28 +010012926 receiving an acknowledgment for the configured delay. This is especially
Willy Tarreau2af207a2015-02-04 00:45:58 +010012927 useful on long-lived connections experiencing long idle periods such as
12928 remote terminals or database connection pools, where the client and server
12929 timeouts must remain high to allow a long period of idle, but where it is
12930 important to detect that the client has disappeared in order to release all
12931 resources associated with its connection (and the server's session). The
12932 argument is a delay expressed in milliseconds by default. This only works
12933 for regular TCP connections, and is ignored for other protocols.
12934
Willy Tarreau1c862c52012-10-05 16:21:00 +020012935tfo
Lukas Tribus0defb902013-02-13 23:35:39 +010012936 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +020012937 enables TCP Fast Open on the listening socket, which means that clients which
12938 support this feature will be able to send a request and receive a response
12939 during the 3-way handshake starting from second connection, thus saving one
12940 round-trip after the first connection. This only makes sense with protocols
12941 that use high connection rates and where each round trip matters. This can
12942 possibly cause issues with many firewalls which do not accept data on SYN
12943 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +020012944 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
12945 need to build HAProxy with USE_TFO=1 if your libc doesn't define
12946 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +020012947
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010012948tls-ticket-keys <keyfile>
12949 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
Emeric Brun9e754772019-01-10 17:51:55 +010012950 or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64
12951 with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo).
12952 The first key determines the key length used for next keys: you can't mix
12953 aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO
12954 build option (default 3) and at least as many keys need to be present in
12955 the file. Last TLS_TICKETS_NO keys will be used for decryption and the
12956 penultimate one for encryption. This enables easy key rotation by just
12957 appending new key to the file and reloading the process. Keys must be
12958 periodically rotated (ex. every 12h) or Perfect Forward Secrecy is
12959 compromised. It is also a good idea to keep the keys off any permanent
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010012960 storage such as hard drives (hint: use tmpfs and don't swap those files).
12961 Lifetime hint can be changed using tune.ssl.timeout.
12962
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012963transparent
12964 Is an optional keyword which is supported only on certain Linux kernels. It
12965 indicates that the addresses will be bound even if they do not belong to the
12966 local machine, and that packets targeting any of these addresses will be
12967 intercepted just as if the addresses were locally configured. This normally
12968 requires that IP forwarding is enabled. Caution! do not use this with the
12969 default address '*', as it would redirect any traffic for the specified port.
12970 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
12971 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
12972 kernel version. Some distribution kernels include backports of the feature,
12973 so check for support with your vendor.
12974
Willy Tarreau77e3af92012-11-24 15:07:23 +010012975v4v6
12976 Is an optional keyword which is supported only on most recent systems
12977 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
12978 and IPv6 when it uses the default address. Doing so is sometimes necessary
12979 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012980 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +010012981
Willy Tarreau9b6700f2012-11-24 11:55:28 +010012982v6only
12983 Is an optional keyword which is supported only on most recent systems
12984 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
12985 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +010012986 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
12987 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +010012988
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012989uid <uid>
12990 Sets the owner of the UNIX sockets to the designated system uid. It can also
12991 be set by default in the global section's "unix-bind" statement. Note that
12992 some platforms simply ignore this. This setting is equivalent to the "user"
12993 setting except that the user numeric ID is used instead of its name. This
12994 setting is ignored by non UNIX sockets.
12995
12996user <user>
12997 Sets the owner of the UNIX sockets to the designated system user. It can also
12998 be set by default in the global section's "unix-bind" statement. Note that
12999 some platforms simply ignore this. This setting is equivalent to the "uid"
13000 setting except that the user name is used instead of its uid. This setting is
13001 ignored by non UNIX sockets.
13002
Emeric Brun1a073b42012-09-28 17:07:34 +020013003verify [none|optional|required]
13004 This setting is only available when support for OpenSSL was built in. If set
13005 to 'none', client certificate is not requested. This is the default. In other
13006 cases, a client certificate is requested. If the client does not provide a
13007 certificate after the request and if 'verify' is set to 'required', then the
13008 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +020013009 certificate provided by the client is always verified using CAs from
13010 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
13011 is aborted, regardless of the 'verify' option, unless the error code exactly
13012 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020013013
Willy Tarreaub6205fd2012-09-24 12:27:33 +0200130145.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +010013015------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020013016
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010013017The "server" and "default-server" keywords support a certain number of settings
13018which are all passed as arguments on the server line. The order in which those
13019arguments appear does not count, and they are all optional. Some of those
13020settings are single words (booleans) while others expect one or several values
13021after them. In this case, the values must immediately follow the setting name.
13022Except default-server, all those settings must be specified after the server's
13023address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +020013024
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013025 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010013026 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +020013027
Frédéric Lécailled2376272017-03-21 18:52:12 +010013028Note that all these settings are supported both by "server" and "default-server"
13029keywords, except "id" which is only supported by "server".
13030
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013031The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +010013032
Willy Tarreauceb4ac92012-04-28 00:41:46 +020013033addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013034 Using the "addr" parameter, it becomes possible to use a different IP address
Baptiste Assmann13f83532016-03-06 23:14:36 +010013035 to send health-checks or to probe the agent-check. On some servers, it may be
13036 desirable to dedicate an IP address to specific component able to perform
13037 complex tests which are more suitable to health-checks than the application.
13038 This parameter is ignored if the "check" parameter is not set. See also the
13039 "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013040
Simon Hormand60d6912013-11-25 10:46:36 +090013041agent-check
13042 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +010013043 health check. An agent health check is performed by making a TCP connection
Willy Tarreau7a0139e2018-12-16 08:42:56 +010013044 to the port set by the "agent-port" parameter and reading an ASCII string
13045 terminated by the first '\r' or '\n' met. The string is made of a series of
13046 words delimited by spaces, tabs or commas in any order, each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +090013047
Willy Tarreau81f5d942013-12-09 20:51:51 +010013048 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +090013049 Values in this format will set the weight proportional to the initial
Willy Tarreauc5af3a62014-10-07 15:27:33 +020013050 weight of a server as configured when haproxy starts. Note that a zero
13051 weight is reported on the stats page as "DRAIN" since it has the same
13052 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +090013053
Davor Ocelice9ed2812017-12-25 17:49:28 +010013054 - The string "maxconn:" followed by an integer (no space between). Values
13055 in this format will set the maxconn of a server. The maximum number of
13056 connections advertised needs to be multiplied by the number of load
13057 balancers and different backends that use this health check to get the
13058 total number of connections the server might receive. Example: maxconn:30
Nenad Merdanovic174dd372016-04-24 23:10:06 +020013059
Willy Tarreau81f5d942013-12-09 20:51:51 +010013060 - The word "ready". This will turn the server's administrative state to the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013061 READY mode, thus canceling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +090013062
Willy Tarreau81f5d942013-12-09 20:51:51 +010013063 - The word "drain". This will turn the server's administrative state to the
13064 DRAIN mode, thus it will not accept any new connections other than those
13065 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +090013066
Willy Tarreau81f5d942013-12-09 20:51:51 +010013067 - The word "maint". This will turn the server's administrative state to the
13068 MAINT mode, thus it will not accept any new connections at all, and health
13069 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +090013070
Willy Tarreau81f5d942013-12-09 20:51:51 +010013071 - The words "down", "failed", or "stopped", optionally followed by a
13072 description string after a sharp ('#'). All of these mark the server's
13073 operating state as DOWN, but since the word itself is reported on the stats
13074 page, the difference allows an administrator to know if the situation was
13075 expected or not : the service may intentionally be stopped, may appear up
Davor Ocelice9ed2812017-12-25 17:49:28 +010013076 but fail some validity tests, or may be seen as down (e.g. missing process,
Willy Tarreau81f5d942013-12-09 20:51:51 +010013077 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +090013078
Willy Tarreau81f5d942013-12-09 20:51:51 +010013079 - The word "up" sets back the server's operating state as UP if health checks
13080 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +090013081
Willy Tarreau81f5d942013-12-09 20:51:51 +010013082 Parameters which are not advertised by the agent are not changed. For
13083 example, an agent might be designed to monitor CPU usage and only report a
13084 relative weight and never interact with the operating status. Similarly, an
13085 agent could be designed as an end-user interface with 3 radio buttons
13086 allowing an administrator to change only the administrative state. However,
13087 it is important to consider that only the agent may revert its own actions,
13088 so if a server is set to DRAIN mode or to DOWN state using the agent, the
13089 agent must implement the other equivalent actions to bring the service into
13090 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +090013091
Simon Horman2f1f9552013-11-25 10:46:37 +090013092 Failure to connect to the agent is not considered an error as connectivity
13093 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +010013094 parameter. Warning though, it is not a good idea to stop an agent after it
13095 reports "down", since only an agent reporting "up" will be able to turn the
13096 server up again. Note that the CLI on the Unix stats socket is also able to
Willy Tarreau989222a2016-01-15 10:26:26 +010013097 force an agent's result in order to work around a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +090013098
Willy Tarreau81f5d942013-12-09 20:51:51 +010013099 Requires the "agent-port" parameter to be set. See also the "agent-inter"
Frédéric Lécailled2376272017-03-21 18:52:12 +010013100 and "no-agent-check" parameters.
Simon Hormand60d6912013-11-25 10:46:36 +090013101
James Brown55f9ff12015-10-21 18:19:05 -070013102agent-send <string>
13103 If this option is specified, haproxy will send the given string (verbatim)
13104 to the agent server upon connection. You could, for example, encode
13105 the backend name into this string, which would enable your agent to send
13106 different responses based on the backend. Make sure to include a '\n' if
13107 you want to terminate your request with a newline.
13108
Simon Hormand60d6912013-11-25 10:46:36 +090013109agent-inter <delay>
13110 The "agent-inter" parameter sets the interval between two agent checks
13111 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
13112
13113 Just as with every other time-based parameter, it may be entered in any
13114 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
13115 parameter also serves as a timeout for agent checks "timeout check" is
13116 not set. In order to reduce "resonance" effects when multiple servers are
13117 hosted on the same hardware, the agent and health checks of all servers
13118 are started with a small time offset between them. It is also possible to
13119 add some random noise in the agent and health checks interval using the
13120 global "spread-checks" keyword. This makes sense for instance when a lot
13121 of backends use the same servers.
13122
13123 See also the "agent-check" and "agent-port" parameters.
13124
Misiek768d8602017-01-09 09:52:43 +010013125agent-addr <addr>
13126 The "agent-addr" parameter sets address for agent check.
13127
13128 You can offload agent-check to another target, so you can make single place
13129 managing status and weights of servers defined in haproxy in case you can't
13130 make self-aware and self-managing services. You can specify both IP or
13131 hostname, it will be resolved.
13132
Simon Hormand60d6912013-11-25 10:46:36 +090013133agent-port <port>
13134 The "agent-port" parameter sets the TCP port used for agent checks.
13135
13136 See also the "agent-check" and "agent-inter" parameters.
13137
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020013138allow-0rtt
13139 Allow sending early data to the server when using TLS 1.3.
Olivier Houchard22c9b442019-05-06 19:01:04 +020013140 Note that early data will be sent only if the client used early data, or
13141 if the backend uses "retry-on" with the "0rtt-rejected" keyword.
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020013142
Olivier Houchardc7566002018-11-20 23:33:50 +010013143alpn <protocols>
13144 This enables the TLS ALPN extension and advertises the specified protocol
13145 list as supported on top of ALPN. The protocol list consists in a comma-
13146 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roeslerfb2fce12019-07-10 15:45:51 -050013147 quotes). This requires that the SSL library is built with support for TLS
Olivier Houchardc7566002018-11-20 23:33:50 +010013148 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
13149 initial NPN extension. ALPN is required to connect to HTTP/2 servers.
13150 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
13151 now obsolete NPN extension.
13152 If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can
13153 be advertised, in order of preference, like below :
13154
13155 server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1
13156
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013157backup
13158 When "backup" is present on a server line, the server is only used in load
13159 balancing when all other non-backup servers are unavailable. Requests coming
13160 with a persistence cookie referencing the server will always be served
13161 though. By default, only the first operational backup server is used, unless
Frédéric Lécailled2376272017-03-21 18:52:12 +010013162 the "allbackups" option is set in the backend. See also the "no-backup" and
13163 "allbackups" options.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013164
Emeric Brunef42d922012-10-11 16:11:36 +020013165ca-file <cafile>
13166 This setting is only available when support for OpenSSL was built in. It
13167 designates a PEM file from which to load CA certificates used to verify
13168 server's certificate.
13169
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013170check
Jerome Magnin90702bc2020-04-26 14:23:04 +020013171 This option enables health checks on a server:
13172 - when not set, no health checking is performed, and the server is always
13173 considered available.
13174 - when set and no other check method is configured, the server is considered
13175 available when a connection can be established at the highest configured
13176 transport layer. This means TCP by default, or SSL/TLS when "ssl" or
13177 "check-ssl" are set, both possibly combined with connection prefixes such
13178 as a PROXY protocol header when "send-proxy" or "check-send-proxy" are
13179 set.
13180 - when set and an application-level health check is defined, the
13181 application-level exchanges are performed on top of the configured
13182 transport layer and the server is considered available if all of the
13183 exchanges succeed.
13184
13185 By default, health checks are performed on the same address and port as
13186 configured on the server, using the same encapsulation parameters (SSL/TLS,
13187 proxy-protocol header, etc... ). It is possible to change the destination
13188 address using "addr" and the port using "port". When done, it is assumed the
13189 server isn't checked on the service port, and configured encapsulation
Ilya Shipitsin4329a9a2020-05-05 21:17:10 +050013190 parameters are not reused. One must explicitly set "check-send-proxy" to send
Jerome Magnin90702bc2020-04-26 14:23:04 +020013191 connection headers, "check-ssl" to use SSL/TLS.
13192
13193 When "sni" or "alpn" are set on the server line, their value is not used for
13194 health checks and one must use "check-sni" or "check-alpn".
13195
13196 The default source address for health check traffic is the same as the one
13197 defined in the backend. It can be changed with the "source" keyword.
13198
13199 The interval between checks can be set using the "inter" keyword, and the
13200 "rise" and "fall" keywords can be used to define how many successful or
13201 failed health checks are required to flag a server available or not
13202 available.
13203
13204 Optional application-level health checks can be configured with "option
13205 httpchk", "option mysql-check" "option smtpchk", "option pgsql-check",
13206 "option ldap-check", or "option redis-check".
13207
13208 Example:
13209 # simple tcp check
13210 backend foo
13211 server s1 192.168.0.1:80 check
13212 # this does a tcp connect + tls handshake
13213 backend foo
13214 server s1 192.168.0.1:443 ssl check
13215 # simple tcp check is enough for check success
13216 backend foo
13217 option tcp-check
13218 tcp-check connect
13219 server s1 192.168.0.1:443 ssl check
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013220
Willy Tarreau6c16adc2012-10-05 00:04:16 +020013221check-send-proxy
13222 This option forces emission of a PROXY protocol line with outgoing health
13223 checks, regardless of whether the server uses send-proxy or not for the
13224 normal traffic. By default, the PROXY protocol is enabled for health checks
13225 if it is already enabled for normal traffic and if no "port" nor "addr"
13226 directive is present. However, if such a directive is present, the
13227 "check-send-proxy" option needs to be used to force the use of the
13228 protocol. See also the "send-proxy" option for more information.
13229
Olivier Houchard92150142018-12-21 19:47:01 +010013230check-alpn <protocols>
13231 Defines which protocols to advertise with ALPN. The protocol list consists in
13232 a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0"
13233 (without quotes). If it is not set, the server ALPN is used.
13234
Christopher Fauletedc6ed92020-04-23 16:27:59 +020013235check-proto <name>
13236 Forces the multiplexer's protocol to use for the server's health-check
13237 connections. It must be compatible with the health-check type (TCP or
13238 HTTP). It must also be usable on the backend side. The list of available
13239 protocols is reported in haproxy -vv.
Daniel Corbett67a82712020-07-06 23:01:19 -040013240 Idea behind this option is to bypass the selection of the best multiplexer's
Christopher Fauletedc6ed92020-04-23 16:27:59 +020013241 protocol for health-check connections established to this server.
13242 If not defined, the server one will be used, if set.
13243
Jérôme Magninae9bb762018-12-09 16:08:26 +010013244check-sni <sni>
Olivier Houchard9130a962017-10-17 17:33:43 +020013245 This option allows you to specify the SNI to be used when doing health checks
Jérôme Magninae9bb762018-12-09 16:08:26 +010013246 over SSL. It is only possible to use a string to set <sni>. If you want to
13247 set a SNI for proxied traffic, see "sni".
Olivier Houchard9130a962017-10-17 17:33:43 +020013248
Willy Tarreau763a95b2012-10-04 23:15:39 +020013249check-ssl
13250 This option forces encryption of all health checks over SSL, regardless of
13251 whether the server uses SSL or not for the normal traffic. This is generally
13252 used when an explicit "port" or "addr" directive is specified and SSL health
13253 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013254 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +020013255 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
13256 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
Davor Ocelice9ed2812017-12-25 17:49:28 +010013257 All SSL settings are common to health checks and traffic (e.g. ciphers).
Frédéric Lécailled2376272017-03-21 18:52:12 +010013258 See the "ssl" option for more information and "no-check-ssl" to disable
13259 this option.
Willy Tarreau763a95b2012-10-04 23:15:39 +020013260
Alexander Liu2a54bb72019-05-22 19:44:48 +080013261check-via-socks4
John Roeslerfb2fce12019-07-10 15:45:51 -050013262 This option enables outgoing health checks using upstream socks4 proxy. By
Alexander Liu2a54bb72019-05-22 19:44:48 +080013263 default, the health checks won't go through socks tunnel even it was enabled
13264 for normal traffic.
13265
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013266ciphers <ciphers>
Dirkjan Bussink415150f2018-09-14 11:14:21 +020013267 This setting is only available when support for OpenSSL was built in. This
13268 option sets the string describing the list of cipher algorithms that is
13269 negotiated during the SSL/TLS handshake with the server. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000013270 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
13271 information and recommendations see e.g.
13272 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
13273 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
13274 cipher configuration, please check the "ciphersuites" keyword.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013275
Dirkjan Bussink415150f2018-09-14 11:14:21 +020013276ciphersuites <ciphersuites>
13277 This setting is only available when support for OpenSSL was built in and
13278 OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string
13279 describing the list of cipher algorithms that is negotiated during the TLS
13280 1.3 handshake with the server. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000013281 "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section.
13282 For cipher configuration for TLSv1.2 and earlier, please check the "ciphers"
13283 keyword.
Dirkjan Bussink415150f2018-09-14 11:14:21 +020013284
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013285cookie <value>
13286 The "cookie" parameter sets the cookie value assigned to the server to
13287 <value>. This value will be checked in incoming requests, and the first
13288 operational server possessing the same value will be selected. In return, in
13289 cookie insertion or rewrite modes, this value will be assigned to the cookie
13290 sent to the client. There is nothing wrong in having several servers sharing
13291 the same cookie value, and it is in fact somewhat common between normal and
13292 backup servers. See also the "cookie" keyword in backend section.
13293
Emeric Brunef42d922012-10-11 16:11:36 +020013294crl-file <crlfile>
13295 This setting is only available when support for OpenSSL was built in. It
13296 designates a PEM file from which to load certificate revocation list used
13297 to verify server's certificate.
13298
Emeric Bruna7aa3092012-10-26 12:58:00 +020013299crt <cert>
13300 This setting is only available when support for OpenSSL was built in.
13301 It designates a PEM file from which to load both a certificate and the
13302 associated private key. This file can be built by concatenating both PEM
13303 files into one. This certificate will be sent if the server send a client
13304 certificate request.
13305
Willy Tarreau96839092010-03-29 10:02:24 +020013306disabled
13307 The "disabled" keyword starts the server in the "disabled" state. That means
13308 that it is marked down in maintenance mode, and no connection other than the
13309 ones allowed by persist mode will reach it. It is very well suited to setup
13310 new servers, because normal traffic will never reach them, while it is still
13311 possible to test the service by making use of the force-persist mechanism.
Frédéric Lécailled2376272017-03-21 18:52:12 +010013312 See also "enabled" setting.
Willy Tarreau96839092010-03-29 10:02:24 +020013313
Frédéric Lécailled2376272017-03-21 18:52:12 +010013314enabled
13315 This option may be used as 'server' setting to reset any 'disabled'
13316 setting which would have been inherited from 'default-server' directive as
13317 default value.
13318 It may also be used as 'default-server' setting to reset any previous
13319 'default-server' 'disabled' setting.
Willy Tarreau96839092010-03-29 10:02:24 +020013320
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013321error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +010013322 If health observing is enabled, the "error-limit" parameter specifies the
13323 number of consecutive errors that triggers event selected by the "on-error"
13324 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010013325
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013326 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010013327
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013328fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013329 The "fall" parameter states that a server will be considered as dead after
13330 <count> consecutive unsuccessful health checks. This value defaults to 3 if
13331 unspecified. See also the "check", "inter" and "rise" parameters.
13332
Emeric Brun8694b9a2012-10-05 14:39:07 +020013333force-sslv3
13334 This option enforces use of SSLv3 only when SSL is used to communicate with
13335 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013336 high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013337 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020013338
13339force-tlsv10
13340 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013341 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013342 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020013343
13344force-tlsv11
13345 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013346 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013347 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020013348
13349force-tlsv12
13350 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013351 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013352 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020013353
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013354force-tlsv13
13355 This option enforces use of TLSv1.3 only when SSL is used to communicate with
13356 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013357 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013358
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013359id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +020013360 Set a persistent ID for the server. This ID must be positive and unique for
13361 the proxy. An unused ID will automatically be assigned if unset. The first
13362 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013363
Willy Tarreau6a031d12016-11-07 19:42:35 +010013364init-addr {last | libc | none | <ip>},[...]*
13365 Indicate in what order the server's address should be resolved upon startup
13366 if it uses an FQDN. Attempts are made to resolve the address by applying in
Davor Ocelice9ed2812017-12-25 17:49:28 +010013367 turn each of the methods mentioned in the comma-delimited list. The first
Willy Tarreau6a031d12016-11-07 19:42:35 +010013368 method which succeeds is used. If the end of the list is reached without
13369 finding a working method, an error is thrown. Method "last" suggests to pick
13370 the address which appears in the state file (see "server-state-file"). Method
13371 "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
13372 depending on the operating system and build options). Method "none"
13373 specifically indicates that the server should start without any valid IP
13374 address in a down state. It can be useful to ignore some DNS issues upon
13375 startup, waiting for the situation to get fixed later. Finally, an IP address
13376 (IPv4 or IPv6) may be provided. It can be the currently known address of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013377 server (e.g. filled by a configuration generator), or the address of a dummy
Willy Tarreau6a031d12016-11-07 19:42:35 +010013378 server used to catch old sessions and present them with a decent error
13379 message for example. When the "first" load balancing algorithm is used, this
13380 IP address could point to a fake server used to trigger the creation of new
13381 instances on the fly. This option defaults to "last,libc" indicating that the
13382 previous address found in the state file (if any) is used first, otherwise
13383 the libc's resolver is used. This ensures continued compatibility with the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013384 historic behavior.
Willy Tarreau6a031d12016-11-07 19:42:35 +010013385
13386 Example:
13387 defaults
13388 # never fail on address resolution
13389 default-server init-addr last,libc,none
13390
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013391inter <delay>
13392fastinter <delay>
13393downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013394 The "inter" parameter sets the interval between two consecutive health checks
13395 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
13396 It is also possible to use "fastinter" and "downinter" to optimize delays
13397 between checks depending on the server state :
13398
Pieter Baauw44fc9df2015-09-17 21:30:46 +020013399 Server state | Interval used
13400 ----------------------------------------+----------------------------------
13401 UP 100% (non-transitional) | "inter"
13402 ----------------------------------------+----------------------------------
13403 Transitionally UP (going down "fall"), | "fastinter" if set,
13404 Transitionally DOWN (going up "rise"), | "inter" otherwise.
13405 or yet unchecked. |
13406 ----------------------------------------+----------------------------------
13407 DOWN 100% (non-transitional) | "downinter" if set,
13408 | "inter" otherwise.
13409 ----------------------------------------+----------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +010013410
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013411 Just as with every other time-based parameter, they can be entered in any
13412 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
13413 serves as a timeout for health checks sent to servers if "timeout check" is
13414 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +090013415 hosted on the same hardware, the agent and health checks of all servers
13416 are started with a small time offset between them. It is also possible to
13417 add some random noise in the agent and health checks interval using the
13418 global "spread-checks" keyword. This makes sense for instance when a lot
13419 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013420
Emeric Brun97556472020-05-30 01:42:45 +020013421log-proto <logproto>
13422 The "log-proto" specifies the protocol used to forward event messages to
13423 a server configured in a ring section. Possible values are "legacy"
13424 and "octet-count" corresponding respectively to "Non-transparent-framing"
13425 and "Octet counting" in rfc6587. "legacy" is the default.
13426
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013427maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013428 The "maxconn" parameter specifies the maximal number of concurrent
13429 connections that will be sent to this server. If the number of incoming
Tim Duesterhuscefbbd92019-11-27 22:35:27 +010013430 concurrent connections goes higher than this value, they will be queued,
13431 waiting for a slot to be released. This parameter is very important as it can
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013432 save fragile servers from going down under extreme loads. If a "minconn"
13433 parameter is specified, the limit becomes dynamic. The default value is "0"
13434 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
13435 the backend's "fullconn" keyword.
13436
Tim Duesterhuscefbbd92019-11-27 22:35:27 +010013437 In HTTP mode this parameter limits the number of concurrent requests instead
13438 of the number of connections. Multiple requests might be multiplexed over a
13439 single TCP connection to the server. As an example if you specify a maxconn
13440 of 50 you might see between 1 and 50 actual server connections, but no more
13441 than 50 concurrent requests.
13442
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013443maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013444 The "maxqueue" parameter specifies the maximal number of connections which
13445 will wait in the queue for this server. If this limit is reached, next
13446 requests will be redispatched to other servers instead of indefinitely
13447 waiting to be served. This will break persistence but may allow people to
13448 quickly re-log in when the server they try to connect to is dying. The
13449 default value is "0" which means the queue is unlimited. See also the
13450 "maxconn" and "minconn" parameters.
13451
Willy Tarreau9c538e02019-01-23 10:21:49 +010013452max-reuse <count>
13453 The "max-reuse" argument indicates the HTTP connection processors that they
13454 should not reuse a server connection more than this number of times to send
13455 new requests. Permitted values are -1 (the default), which disables this
13456 limit, or any positive value. Value zero will effectively disable keep-alive.
13457 This is only used to work around certain server bugs which cause them to leak
13458 resources over time. The argument is not necessarily respected by the lower
13459 layers as there might be technical limitations making it impossible to
13460 enforce. At least HTTP/2 connections to servers will respect it.
13461
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013462minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013463 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
13464 limit following the backend's load. The server will always accept at least
13465 <minconn> connections, never more than <maxconn>, and the limit will be on
13466 the ramp between both values when the backend has less than <fullconn>
13467 concurrent connections. This makes it possible to limit the load on the
13468 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010013469 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013470 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010013471
Willy Tarreaud72f0f32015-10-13 14:50:22 +020013472namespace <name>
13473 On Linux, it is possible to specify which network namespace a socket will
13474 belong to. This directive makes it possible to explicitly bind a server to
13475 a namespace different from the default one. Please refer to your operating
13476 system's documentation to find more details about network namespaces.
13477
Frédéric Lécailled2376272017-03-21 18:52:12 +010013478no-agent-check
13479 This option may be used as "server" setting to reset any "agent-check"
13480 setting which would have been inherited from "default-server" directive as
13481 default value.
13482 It may also be used as "default-server" setting to reset any previous
13483 "default-server" "agent-check" setting.
13484
13485no-backup
13486 This option may be used as "server" setting to reset any "backup"
13487 setting which would have been inherited from "default-server" directive as
13488 default value.
13489 It may also be used as "default-server" setting to reset any previous
13490 "default-server" "backup" setting.
13491
13492no-check
13493 This option may be used as "server" setting to reset any "check"
13494 setting which would have been inherited from "default-server" directive as
13495 default value.
13496 It may also be used as "default-server" setting to reset any previous
13497 "default-server" "check" setting.
13498
13499no-check-ssl
13500 This option may be used as "server" setting to reset any "check-ssl"
13501 setting which would have been inherited from "default-server" directive as
13502 default value.
13503 It may also be used as "default-server" setting to reset any previous
13504 "default-server" "check-ssl" setting.
13505
Frédéric Lécailled2376272017-03-21 18:52:12 +010013506no-send-proxy
13507 This option may be used as "server" setting to reset any "send-proxy"
13508 setting which would have been inherited from "default-server" directive as
13509 default value.
13510 It may also be used as "default-server" setting to reset any previous
13511 "default-server" "send-proxy" setting.
13512
13513no-send-proxy-v2
13514 This option may be used as "server" setting to reset any "send-proxy-v2"
13515 setting which would have been inherited from "default-server" directive as
13516 default value.
13517 It may also be used as "default-server" setting to reset any previous
13518 "default-server" "send-proxy-v2" setting.
13519
13520no-send-proxy-v2-ssl
13521 This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
13522 setting which would have been inherited from "default-server" directive as
13523 default value.
13524 It may also be used as "default-server" setting to reset any previous
13525 "default-server" "send-proxy-v2-ssl" setting.
13526
13527no-send-proxy-v2-ssl-cn
13528 This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
13529 setting which would have been inherited from "default-server" directive as
13530 default value.
13531 It may also be used as "default-server" setting to reset any previous
13532 "default-server" "send-proxy-v2-ssl-cn" setting.
13533
13534no-ssl
13535 This option may be used as "server" setting to reset any "ssl"
13536 setting which would have been inherited from "default-server" directive as
13537 default value.
13538 It may also be used as "default-server" setting to reset any previous
13539 "default-server" "ssl" setting.
13540
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010013541no-ssl-reuse
13542 This option disables SSL session reuse when SSL is used to communicate with
13543 the server. It will force the server to perform a full handshake for every
13544 new connection. It's probably only useful for benchmarking, troubleshooting,
13545 and for paranoid users.
13546
Emeric Brun9b3009b2012-10-05 11:55:06 +020013547no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013548 This option disables support for SSLv3 when SSL is used to communicate with
13549 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013550 using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013551
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020013552 Supported in default-server: No
13553
Emeric Brunf9c5c472012-10-11 15:28:34 +020013554no-tls-tickets
13555 This setting is only available when support for OpenSSL was built in. It
13556 disables the stateless session resumption (RFC 5077 TLS Ticket
13557 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013558 session resumption is more expensive in CPU usage for servers. This option
13559 is also available on global statement "ssl-default-server-options".
Lukas Tribusbdb386d2020-03-10 00:56:09 +010013560 The TLS ticket mechanism is only used up to TLS 1.2.
13561 Forward Secrecy is compromised with TLS tickets, unless ticket keys
13562 are periodically rotated (via reload or by using "tls-ticket-keys").
Frédéric Lécailled2376272017-03-21 18:52:12 +010013563 See also "tls-tickets".
Emeric Brunf9c5c472012-10-11 15:28:34 +020013564
Emeric Brun9b3009b2012-10-05 11:55:06 +020013565no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020013566 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020013567 the server. Note that SSLv2 is disabled in the code and cannot be enabled
13568 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013569 often makes sense to disable it when communicating with local servers. This
13570 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013571 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020013572
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020013573 Supported in default-server: No
13574
Emeric Brun9b3009b2012-10-05 11:55:06 +020013575no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020013576 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020013577 the server. Note that SSLv2 is disabled in the code and cannot be enabled
13578 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013579 often makes sense to disable it when communicating with local servers. This
13580 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013581 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020013582
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020013583 Supported in default-server: No
13584
Emeric Brun9b3009b2012-10-05 11:55:06 +020013585no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020013586 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013587 the server. Note that SSLv2 is disabled in the code and cannot be enabled
13588 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010013589 often makes sense to disable it when communicating with local servers. This
13590 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013591 Use "ssl-min-ver" and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020013592
13593 Supported in default-server: No
13594
13595no-tlsv13
13596 This option disables support for TLSv1.3 when SSL is used to communicate with
13597 the server. Note that SSLv2 is disabled in the code and cannot be enabled
13598 using any configuration option. TLSv1 is more expensive than SSLv3 so it
13599 often makes sense to disable it when communicating with local servers. This
13600 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013601 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013602
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020013603 Supported in default-server: No
13604
Frédéric Lécailled2376272017-03-21 18:52:12 +010013605no-verifyhost
13606 This option may be used as "server" setting to reset any "verifyhost"
13607 setting which would have been inherited from "default-server" directive as
13608 default value.
13609 It may also be used as "default-server" setting to reset any previous
13610 "default-server" "verifyhost" setting.
Willy Tarreau763a95b2012-10-04 23:15:39 +020013611
Frédéric Lécaille1b9423d2019-07-04 14:19:06 +020013612no-tfo
13613 This option may be used as "server" setting to reset any "tfo"
13614 setting which would have been inherited from "default-server" directive as
13615 default value.
13616 It may also be used as "default-server" setting to reset any previous
13617 "default-server" "tfo" setting.
13618
Simon Hormanfa461682011-06-25 09:39:49 +090013619non-stick
13620 Never add connections allocated to this sever to a stick-table.
13621 This may be used in conjunction with backup to ensure that
13622 stick-table persistence is disabled for backup servers.
13623
Olivier Houchardc7566002018-11-20 23:33:50 +010013624npn <protocols>
13625 This enables the NPN TLS extension and advertises the specified protocol list
13626 as supported on top of NPN. The protocol list consists in a comma-delimited
13627 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roeslerfb2fce12019-07-10 15:45:51 -050013628 This requires that the SSL library is built with support for TLS extensions
Olivier Houchardc7566002018-11-20 23:33:50 +010013629 enabled (check with haproxy -vv). Note that the NPN extension has been
13630 replaced with the ALPN extension (see the "alpn" keyword), though this one is
13631 only available starting with OpenSSL 1.0.2.
13632
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010013633observe <mode>
13634 This option enables health adjusting based on observing communication with
13635 the server. By default this functionality is disabled and enabling it also
13636 requires to enable health checks. There are two supported modes: "layer4" and
13637 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
13638 significant. In layer7, which is only allowed for http proxies, responses
13639 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010013640 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010013641
13642 See also the "check", "on-error" and "error-limit".
13643
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013644on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010013645 Select what should happen when enough consecutive errors are detected.
13646 Currently, four modes are available:
13647 - fastinter: force fastinter
13648 - fail-check: simulate a failed check, also forces fastinter (default)
13649 - sudden-death: simulate a pre-fatal failed health check, one more failed
13650 check will mark a server down, forces fastinter
13651 - mark-down: mark the server immediately down and force fastinter
13652
13653 See also the "check", "observe" and "error-limit".
13654
Simon Hormane0d1bfb2011-06-21 14:34:58 +090013655on-marked-down <action>
13656 Modify what occurs when a server is marked down.
13657 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070013658 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
13659 all connections to the server are immediately terminated when the server
13660 goes down. It might be used if the health check detects more complex cases
13661 than a simple connection status, and long timeouts would cause the service
13662 to remain unresponsive for too long a time. For instance, a health check
13663 might detect that a database is stuck and that there's no chance to reuse
13664 existing connections anymore. Connections killed this way are logged with
13665 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090013666
13667 Actions are disabled by default
13668
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070013669on-marked-up <action>
13670 Modify what occurs when a server is marked up.
13671 Currently one action is available:
13672 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
13673 done only if the server is not in backup state and if it is not disabled
13674 (it must have an effective weight > 0). This can be used sometimes to force
13675 an active server to take all the traffic back after recovery when dealing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013676 with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble
13677 than it tries to solve (e.g. incomplete transactions), so use this feature
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070013678 with extreme care. Sessions killed because a server comes up are logged
13679 with an 'U' termination code (for "Up").
13680
13681 Actions are disabled by default
13682
Willy Tarreau2f3f4d32020-07-01 07:43:51 +020013683pool-low-conn <max>
13684 Set a low threshold on the number of idling connections for a server, below
13685 which a thread will not try to steal a connection from another thread. This
13686 can be useful to improve CPU usage patterns in scenarios involving many very
13687 fast servers, in order to ensure all threads will keep a few idle connections
13688 all the time instead of letting them accumulate over one thread and migrating
13689 them from thread to thread. Typical values of twice the number of threads
13690 seem to show very good performance already with sub-millisecond response
13691 times. The default is zero, indicating that any idle connection can be used
13692 at any time. It is the recommended setting for normal use. This only applies
13693 to connections that can be shared according to the same principles as those
13694 applying to "http-reuse".
13695
Olivier Houchard006e3102018-12-10 18:30:32 +010013696pool-max-conn <max>
13697 Set the maximum number of idling connections for a server. -1 means unlimited
13698 connections, 0 means no idle connections. The default is -1. When idle
13699 connections are enabled, orphaned idle connections which do not belong to any
13700 client session anymore are moved to a dedicated pool so that they remain
13701 usable by future clients. This only applies to connections that can be shared
13702 according to the same principles as those applying to "http-reuse".
13703
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010013704pool-purge-delay <delay>
13705 Sets the delay to start purging idle connections. Each <delay> interval, half
Olivier Houcharda56eebf2019-03-19 16:44:02 +010013706 of the idle connections are closed. 0 means we don't keep any idle connection.
Willy Tarreaufb553652019-06-04 14:06:31 +020013707 The default is 5s.
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010013708
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013709port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013710 Using the "port" parameter, it becomes possible to use a different port to
13711 send health-checks. On some servers, it may be desirable to dedicate a port
13712 to a specific component able to perform complex tests which are more suitable
13713 to health-checks than the application. It is common to run a simple script in
13714 inetd for instance. This parameter is ignored if the "check" parameter is not
13715 set. See also the "addr" parameter.
13716
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020013717proto <name>
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020013718 Forces the multiplexer's protocol to use for the outgoing connections to this
13719 server. It must be compatible with the mode of the backend (TCP or HTTP). It
13720 must also be usable on the backend side. The list of available protocols is
13721 reported in haproxy -vv.
Daniel Corbett67a82712020-07-06 23:01:19 -040013722 Idea behind this option is to bypass the selection of the best multiplexer's
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020013723 protocol for all connections established to this server.
13724
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013725redir <prefix>
13726 The "redir" parameter enables the redirection mode for all GET and HEAD
13727 requests addressing this server. This means that instead of having HAProxy
13728 forward the request to the server, it will send an "HTTP 302" response with
13729 the "Location" header composed of this prefix immediately followed by the
13730 requested URI beginning at the leading '/' of the path component. That means
13731 that no trailing slash should be used after <prefix>. All invalid requests
13732 will be rejected, and all non-GET or HEAD requests will be normally served by
13733 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010013734 mangling nor cookie insertion is possible in the response. However, cookies in
Davor Ocelice9ed2812017-12-25 17:49:28 +010013735 requests are still analyzed, making this solution completely usable to direct
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013736 users to a remote location in case of local disaster. Main use consists in
13737 increasing bandwidth for static servers by having the clients directly
13738 connect to them. Note: never use a relative location here, it would cause a
13739 loop between the client and HAProxy!
13740
13741 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
13742
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013743rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013744 The "rise" parameter states that a server will be considered as operational
13745 after <count> consecutive successful health checks. This value defaults to 2
13746 if unspecified. See also the "check", "inter" and "fall" parameters.
13747
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020013748resolve-opts <option>,<option>,...
13749 Comma separated list of options to apply to DNS resolution linked to this
13750 server.
13751
13752 Available options:
13753
13754 * allow-dup-ip
13755 By default, HAProxy prevents IP address duplication in a backend when DNS
13756 resolution at runtime is in operation.
13757 That said, for some cases, it makes sense that two servers (in the same
13758 backend, being resolved by the same FQDN) have the same IP address.
13759 For such case, simply enable this option.
13760 This is the opposite of prevent-dup-ip.
13761
Daniel Corbettf8716912019-11-17 09:48:56 -050013762 * ignore-weight
13763 Ignore any weight that is set within an SRV record. This is useful when
13764 you would like to control the weights using an alternate method, such as
13765 using an "agent-check" or through the runtime api.
13766
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020013767 * prevent-dup-ip
13768 Ensure HAProxy's default behavior is enforced on a server: prevent re-using
13769 an IP address already set to a server in the same backend and sharing the
13770 same fqdn.
13771 This is the opposite of allow-dup-ip.
13772
13773 Example:
13774 backend b_myapp
13775 default-server init-addr none resolvers dns
13776 server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
13777 server s2 myapp.example.com:81 check resolve-opts allow-dup-ip
13778
13779 With the option allow-dup-ip set:
13780 * if the nameserver returns a single IP address, then both servers will use
13781 it
13782 * If the nameserver returns 2 IP addresses, then each server will pick up a
13783 different address
13784
13785 Default value: not set
13786
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013787resolve-prefer <family>
13788 When DNS resolution is enabled for a server and multiple IP addresses from
13789 different families are returned, HAProxy will prefer using an IP address
13790 from the family mentioned in the "resolve-prefer" parameter.
13791 Available families: "ipv4" and "ipv6"
13792
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020013793 Default value: ipv6
13794
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020013795 Example:
13796
13797 server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013798
Thierry Fournierac88cfe2016-02-17 22:05:30 +010013799resolve-net <network>[,<network[,...]]
John Roeslerfb2fce12019-07-10 15:45:51 -050013800 This option prioritizes the choice of an ip address matching a network. This is
Thierry Fournierac88cfe2016-02-17 22:05:30 +010013801 useful with clouds to prefer a local ip. In some cases, a cloud high
Tim Düsterhus4896c442016-11-29 02:15:19 +010013802 availability service can be announced with many ip addresses on many
Davor Ocelice9ed2812017-12-25 17:49:28 +010013803 different datacenters. The latency between datacenter is not negligible, so
13804 this patch permits to prefer a local datacenter. If no address matches the
Thierry Fournierac88cfe2016-02-17 22:05:30 +010013805 configured network, another address is selected.
13806
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020013807 Example:
13808
13809 server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8
Thierry Fournierac88cfe2016-02-17 22:05:30 +010013810
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013811resolvers <id>
13812 Points to an existing "resolvers" section to resolve current server's
13813 hostname.
13814
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020013815 Example:
13816
13817 server s1 app1.domain.com:80 check resolvers mydns
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013818
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020013819 See also section 5.3
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013820
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010013821send-proxy
13822 The "send-proxy" parameter enforces use of the PROXY protocol over any
13823 connection established to this server. The PROXY protocol informs the other
13824 end about the layer 3/4 addresses of the incoming connection, so that it can
13825 know the client's address or the public address it accessed to, whatever the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010013826 upper layer protocol. For connections accepted by an "accept-proxy" or
13827 "accept-netscaler-cip" listener, the advertised address will be used. Only
13828 TCPv4 and TCPv6 address families are supported. Other families such as
13829 Unix sockets, will report an UNKNOWN family. Servers using this option can
13830 fully be chained to another instance of haproxy listening with an
13831 "accept-proxy" setting. This setting must not be used if the server isn't
13832 aware of the protocol. When health checks are sent to the server, the PROXY
13833 protocol is automatically used when this option is set, unless there is an
13834 explicit "port" or "addr" directive, in which case an explicit
13835 "check-send-proxy" directive would also be needed to use the PROXY protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010013836 See also the "no-send-proxy" option of this section and "accept-proxy" and
13837 "accept-netscaler-cip" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010013838
David Safb76832014-05-08 23:42:08 -040013839send-proxy-v2
13840 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
13841 over any connection established to this server. The PROXY protocol informs
13842 the other end about the layer 3/4 addresses of the incoming connection, so
13843 that it can know the client's address or the public address it accessed to,
Emmanuel Hocdet404d9782017-10-24 10:55:14 +020013844 whatever the upper layer protocol. It also send ALPN information if an alpn
13845 have been negotiated. This setting must not be used if the server isn't aware
13846 of this version of the protocol. See also the "no-send-proxy-v2" option of
13847 this section and send-proxy" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040013848
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010013849proxy-v2-options <option>[,<option>]*
Tim Duesterhuscf6e0c82020-03-13 12:34:24 +010013850 The "proxy-v2-options" parameter add options to send in PROXY protocol
13851 version 2 when "send-proxy-v2" is used. Options available are:
13852
13853 - ssl : See also "send-proxy-v2-ssl".
13854 - cert-cn : See also "send-proxy-v2-ssl-cn".
13855 - ssl-cipher: Name of the used cipher.
13856 - cert-sig : Signature algorithm of the used certificate.
13857 - cert-key : Key algorithm of the used certificate
13858 - authority : Host name value passed by the client (only SNI from a TLS
13859 connection is supported).
13860 - crc32c : Checksum of the PROXYv2 header.
13861 - unique-id : Send a unique ID generated using the frontend's
13862 "unique-id-format" within the PROXYv2 header.
13863 This unique-id is primarily meant for "mode tcp". It can
13864 lead to unexpected results in "mode http", because the
13865 generated unique ID is also used for the first HTTP request
13866 within a Keep-Alive connection.
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010013867
David Safb76832014-05-08 23:42:08 -040013868send-proxy-v2-ssl
13869 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
13870 2 over any connection established to this server. The PROXY protocol informs
13871 the other end about the layer 3/4 addresses of the incoming connection, so
13872 that it can know the client's address or the public address it accessed to,
13873 whatever the upper layer protocol. In addition, the SSL information extension
13874 of the PROXY protocol is added to the PROXY protocol header. This setting
13875 must not be used if the server isn't aware of this version of the protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010013876 See also the "no-send-proxy-v2-ssl" option of this section and the
13877 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040013878
13879send-proxy-v2-ssl-cn
13880 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
13881 2 over any connection established to this server. The PROXY protocol informs
13882 the other end about the layer 3/4 addresses of the incoming connection, so
13883 that it can know the client's address or the public address it accessed to,
13884 whatever the upper layer protocol. In addition, the SSL information extension
13885 of the PROXY protocol, along along with the Common Name from the subject of
13886 the client certificate (if any), is added to the PROXY protocol header. This
13887 setting must not be used if the server isn't aware of this version of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013888 protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and
13889 the "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040013890
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010013891slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013892 The "slowstart" parameter for a server accepts a value in milliseconds which
13893 indicates after how long a server which has just come back up will run at
13894 full speed. Just as with every other time-based parameter, it can be entered
13895 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
13896 linearly from 0 to 100% during this time. The limitation applies to two
13897 parameters :
13898
13899 - maxconn: the number of connections accepted by the server will grow from 1
13900 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
13901
13902 - weight: when the backend uses a dynamic weighted algorithm, the weight
13903 grows linearly from 1 to 100%. In this case, the weight is updated at every
13904 health-check. For this reason, it is important that the "inter" parameter
13905 is smaller than the "slowstart", in order to maximize the number of steps.
13906
13907 The slowstart never applies when haproxy starts, otherwise it would cause
13908 trouble to running servers. It only applies when a server has been previously
13909 seen as failed.
13910
Willy Tarreau732eac42015-07-09 11:40:25 +020013911sni <expression>
13912 The "sni" parameter evaluates the sample fetch expression, converts it to a
13913 string and uses the result as the host name sent in the SNI TLS extension to
13914 the server. A typical use case is to send the SNI received from the client in
13915 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
Willy Tarreau2ab88672017-07-05 18:23:03 +020013916 expression, though alternatives such as req.hdr(host) can also make sense. If
13917 "verify required" is set (which is the recommended setting), the resulting
Willy Tarreauad92a9a2017-07-28 11:38:41 +020013918 name will also be matched against the server certificate's names. See the
Jérôme Magninb36a6d22018-12-09 16:03:40 +010013919 "verify" directive for more details. If you want to set a SNI for health
13920 checks, see the "check-sni" directive for more details.
Willy Tarreau732eac42015-07-09 11:40:25 +020013921
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020013922source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020013923source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020013924source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013925 The "source" parameter sets the source address which will be used when
13926 connecting to the server. It follows the exact same parameters and principle
13927 as the backend "source" keyword, except that it only applies to the server
13928 referencing it. Please consult the "source" keyword for details.
13929
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020013930 Additionally, the "source" statement on a server line allows one to specify a
13931 source port range by indicating the lower and higher bounds delimited by a
13932 dash ('-'). Some operating systems might require a valid IP address when a
13933 source port range is specified. It is permitted to have the same IP/range for
13934 several servers. Doing so makes it possible to bypass the maximum of 64k
13935 total concurrent connections. The limit will then reach 64k connections per
13936 server.
13937
Lukas Tribus7d56c6d2016-09-13 09:51:15 +000013938 Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
13939 specifying the source address without port(s).
13940
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013941ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020013942 This option enables SSL ciphering on outgoing connections to the server. It
13943 is critical to verify server certificates using "verify" when using SSL to
13944 connect to servers, otherwise the communication is prone to trivial man in
13945 the-middle attacks rendering SSL useless. When this option is used, health
13946 checks are automatically sent in SSL too unless there is a "port" or an
13947 "addr" directive indicating the check should be sent to a different location.
Frédéric Lécailled2376272017-03-21 18:52:12 +010013948 See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
13949 SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020013950
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020013951ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
13952 This option enforces use of <version> or lower when SSL is used to communicate
13953 with the server. This option is also available on global statement
13954 "ssl-default-server-options". See also "ssl-min-ver".
13955
13956ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
13957 This option enforces use of <version> or upper when SSL is used to communicate
13958 with the server. This option is also available on global statement
13959 "ssl-default-server-options". See also "ssl-max-ver".
13960
Frédéric Lécailled2376272017-03-21 18:52:12 +010013961ssl-reuse
13962 This option may be used as "server" setting to reset any "no-ssl-reuse"
13963 setting which would have been inherited from "default-server" directive as
13964 default value.
13965 It may also be used as "default-server" setting to reset any previous
13966 "default-server" "no-ssl-reuse" setting.
13967
13968stick
13969 This option may be used as "server" setting to reset any "non-stick"
13970 setting which would have been inherited from "default-server" directive as
13971 default value.
13972 It may also be used as "default-server" setting to reset any previous
13973 "default-server" "non-stick" setting.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020013974
Alexander Liu2a54bb72019-05-22 19:44:48 +080013975socks4 <addr>:<port>
John Roeslerfb2fce12019-07-10 15:45:51 -050013976 This option enables upstream socks4 tunnel for outgoing connections to the
Alexander Liu2a54bb72019-05-22 19:44:48 +080013977 server. Using this option won't force the health check to go via socks4 by
13978 default. You will have to use the keyword "check-via-socks4" to enable it.
13979
Willy Tarreau163d4622015-10-13 16:16:41 +020013980tcp-ut <delay>
13981 Sets the TCP User Timeout for all outgoing connections to this server. This
13982 option is available on Linux since version 2.6.37. It allows haproxy to
13983 configure a timeout for sockets which contain data not receiving an
Davor Ocelice9ed2812017-12-25 17:49:28 +010013984 acknowledgment for the configured delay. This is especially useful on
Willy Tarreau163d4622015-10-13 16:16:41 +020013985 long-lived connections experiencing long idle periods such as remote
13986 terminals or database connection pools, where the client and server timeouts
13987 must remain high to allow a long period of idle, but where it is important to
13988 detect that the server has disappeared in order to release all resources
13989 associated with its connection (and the client's session). One typical use
13990 case is also to force dead server connections to die when health checks are
13991 too slow or during a soft reload since health checks are then disabled. The
13992 argument is a delay expressed in milliseconds by default. This only works for
13993 regular TCP connections, and is ignored for other protocols.
13994
Willy Tarreau034c88c2017-01-23 23:36:45 +010013995tfo
13996 This option enables using TCP fast open when connecting to servers, on
13997 systems that support it (currently only the Linux kernel >= 4.11).
13998 See the "tfo" bind option for more information about TCP fast open.
13999 Please note that when using tfo, you should also use the "conn-failure",
14000 "empty-response" and "response-timeout" keywords for "retry-on", or haproxy
Frédéric Lécaille1b9423d2019-07-04 14:19:06 +020014001 won't be able to retry the connection on failure. See also "no-tfo".
Willy Tarreau034c88c2017-01-23 23:36:45 +010014002
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014003track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020014004 This option enables ability to set the current state of the server by tracking
14005 another one. It is possible to track a server which itself tracks another
14006 server, provided that at the end of the chain, a server has health checks
14007 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014008 used, it has to be enabled on both proxies.
14009
Frédéric Lécailled2376272017-03-21 18:52:12 +010014010tls-tickets
14011 This option may be used as "server" setting to reset any "no-tls-tickets"
14012 setting which would have been inherited from "default-server" directive as
14013 default value.
Lukas Tribusbdb386d2020-03-10 00:56:09 +010014014 The TLS ticket mechanism is only used up to TLS 1.2.
14015 Forward Secrecy is compromised with TLS tickets, unless ticket keys
14016 are periodically rotated (via reload or by using "tls-ticket-keys").
Frédéric Lécailled2376272017-03-21 18:52:12 +010014017 It may also be used as "default-server" setting to reset any previous
Bjoern Jacke5ab7eb62020-02-13 14:16:16 +010014018 "default-server" "no-tls-tickets" setting.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014019
Emeric Brunef42d922012-10-11 16:11:36 +020014020verify [none|required]
14021 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010014022 to 'none', server certificate is not verified. In the other case, The
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014023 certificate provided by the server is verified using CAs from 'ca-file' and
14024 optional CRLs from 'crl-file' after having checked that the names provided in
Davor Ocelice9ed2812017-12-25 17:49:28 +010014025 the certificate's subject and subjectAlternateNames attributes match either
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014026 the name passed using the "sni" directive, or if not provided, the static
14027 host name passed using the "verifyhost" directive. When no name is found, the
14028 certificate's names are ignored. For this reason, without SNI it's important
14029 to use "verifyhost". On verification failure the handshake is aborted. It is
14030 critically important to verify server certificates when using SSL to connect
14031 to servers, otherwise the communication is prone to trivial man-in-the-middle
14032 attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
14033 the global section, "verify" is set to "required" by default.
Emeric Brunef42d922012-10-11 16:11:36 +020014034
Evan Broderbe554312013-06-27 00:05:25 -070014035verifyhost <hostname>
14036 This setting is only available when support for OpenSSL was built in, and
Willy Tarreauad92a9a2017-07-28 11:38:41 +020014037 only takes effect if 'verify required' is also specified. This directive sets
14038 a default static hostname to check the server's certificate against when no
14039 SNI was used to connect to the server. If SNI is not used, this is the only
14040 way to enable hostname verification. This static hostname, when set, will
14041 also be used for health checks (which cannot provide an SNI value). If none
14042 of the hostnames in the certificate match the specified hostname, the
14043 handshake is aborted. The hostnames in the server-provided certificate may
14044 include wildcards. See also "verify", "sni" and "no-verifyhost" options.
Evan Broderbe554312013-06-27 00:05:25 -070014045
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010014046weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014047 The "weight" parameter is used to adjust the server's weight relative to
14048 other servers. All servers will receive a load proportional to their weight
14049 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020014050 load. The default weight is 1, and the maximal value is 256. A value of 0
14051 means the server will not participate in load-balancing but will still accept
14052 persistent connections. If this parameter is used to distribute the load
14053 according to server's capacity, it is recommended to start with values which
14054 can both grow and shrink, for instance between 10 and 100 to leave enough
14055 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014056
14057
Cyril Bonté46175dd2015-07-02 22:45:32 +0200140585.3. Server IP address resolution using DNS
14059-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014060
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014061HAProxy allows using a host name on the server line to retrieve its IP address
14062using name servers. By default, HAProxy resolves the name when parsing the
14063configuration file, at startup and cache the result for the process' life.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014064This is not sufficient in some cases, such as in Amazon where a server's IP
14065can change after a reboot or an ELB Virtual IP can change based on current
14066workload.
14067This chapter describes how HAProxy can be configured to process server's name
14068resolution at run time.
14069Whether run time server name resolution has been enable or not, HAProxy will
14070carry on doing the first resolution when parsing the configuration.
14071
14072
Cyril Bonté46175dd2015-07-02 22:45:32 +0200140735.3.1. Global overview
14074----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014075
14076As we've seen in introduction, name resolution in HAProxy occurs at two
14077different steps of the process life:
14078
14079 1. when starting up, HAProxy parses the server line definition and matches a
14080 host name. It uses libc functions to get the host name resolved. This
14081 resolution relies on /etc/resolv.conf file.
14082
Christopher Faulet67957bd2017-09-27 11:00:59 +020014083 2. at run time, HAProxy performs periodically name resolutions for servers
14084 requiring DNS resolutions.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014085
14086A few other events can trigger a name resolution at run time:
14087 - when a server's health check ends up in a connection timeout: this may be
14088 because the server has a new IP address. So we need to trigger a name
14089 resolution to know this new IP.
14090
Christopher Faulet67957bd2017-09-27 11:00:59 +020014091When using resolvers, the server name can either be a hostname, or a SRV label.
Davor Ocelice9ed2812017-12-25 17:49:28 +010014092HAProxy considers anything that starts with an underscore as a SRV label. If a
Christopher Faulet67957bd2017-09-27 11:00:59 +020014093SRV label is specified, then the corresponding SRV records will be retrieved
14094from the DNS server, and the provided hostnames will be used. The SRV label
14095will be checked periodically, and if any server are added or removed, haproxy
14096will automatically do the same.
Olivier Houchardecfa18d2017-08-07 17:30:03 +020014097
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014098A few things important to notice:
John Roeslerfb2fce12019-07-10 15:45:51 -050014099 - all the name servers are queried in the meantime. HAProxy will process the
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014100 first valid response.
14101
14102 - a resolution is considered as invalid (NX, timeout, refused), when all the
14103 servers return an error.
14104
14105
Cyril Bonté46175dd2015-07-02 22:45:32 +0200141065.3.2. The resolvers section
14107----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014108
14109This section is dedicated to host information related to name resolution in
Christopher Faulet67957bd2017-09-27 11:00:59 +020014110HAProxy. There can be as many as resolvers section as needed. Each section can
14111contain many name servers.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014112
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014113When multiple name servers are configured in a resolvers section, then HAProxy
14114uses the first valid response. In case of invalid responses, only the last one
14115is treated. Purpose is to give the chance to a slow server to deliver a valid
14116answer after a fast faulty or outdated server.
14117
14118When each server returns a different error type, then only the last error is
Christopher Faulet67957bd2017-09-27 11:00:59 +020014119used by HAProxy. The following processing is applied on this error:
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014120
Christopher Faulet67957bd2017-09-27 11:00:59 +020014121 1. HAProxy retries the same DNS query with a new query type. The A queries are
14122 switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
14123 errors are also excluded.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014124
Christopher Faulet67957bd2017-09-27 11:00:59 +020014125 2. When the fallback on the query type was done (or not applicable), HAProxy
14126 retries the original DNS query, with the preferred query type.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014127
Christopher Faulet67957bd2017-09-27 11:00:59 +020014128 3. HAProxy retries previous steps <resolve_retires> times. If no valid
14129 response is received after that, it stops the DNS resolution and reports
14130 the error.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014131
Christopher Faulet67957bd2017-09-27 11:00:59 +020014132For example, with 2 name servers configured in a resolvers section, the
14133following scenarios are possible:
14134
14135 - First response is valid and is applied directly, second response is
14136 ignored
14137
14138 - First response is invalid and second one is valid, then second response is
14139 applied
14140
14141 - First response is a NX domain and second one a truncated response, then
14142 HAProxy retries the query with a new type
14143
14144 - First response is a NX domain and second one is a timeout, then HAProxy
14145 retries the query with a new type
14146
14147 - Query timed out for both name servers, then HAProxy retries it with the
14148 same query type
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014149
Olivier Houcharda8c6db82017-07-06 18:46:47 +020014150As a DNS server may not answer all the IPs in one DNS request, haproxy keeps
14151a cache of previous answers, an answer will be considered obsolete after
Christopher Faulet67957bd2017-09-27 11:00:59 +020014152<hold obsolete> seconds without the IP returned.
Olivier Houcharda8c6db82017-07-06 18:46:47 +020014153
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014154
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014155resolvers <resolvers id>
Davor Ocelice9ed2812017-12-25 17:49:28 +010014156 Creates a new name server list labeled <resolvers id>
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014157
14158A resolvers section accept the following parameters:
14159
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020014160accepted_payload_size <nb>
Davor Ocelice9ed2812017-12-25 17:49:28 +010014161 Defines the maximum payload size accepted by HAProxy and announced to all the
Christopher Faulet67957bd2017-09-27 11:00:59 +020014162 name servers configured in this resolvers section.
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020014163 <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
14164 by RFC 6891)
14165
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020014166 Note: the maximum allowed value is 8192.
14167
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014168nameserver <id> <ip>:<port>
14169 DNS server description:
14170 <id> : label of the server, should be unique
14171 <ip> : IP address of the server
14172 <port> : port where the DNS service actually runs
14173
Ben Draut44e609b2018-05-29 15:40:08 -060014174parse-resolv-conf
14175 Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers
14176 list. Ordered as if each nameserver in /etc/resolv.conf was individually
14177 placed in the resolvers section in place of this directive.
14178
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014179hold <status> <period>
14180 Defines <period> during which the last name resolution should be kept based
14181 on last resolution <status>
Baptiste Assmann987e16d2016-11-02 22:23:31 +010014182 <status> : last name resolution status. Acceptable values are "nx",
Olivier Houcharda8c6db82017-07-06 18:46:47 +020014183 "other", "refused", "timeout", "valid", "obsolete".
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014184 <period> : interval between two successive name resolution when the last
14185 answer was in <status>. It follows the HAProxy time format.
14186 <period> is in milliseconds by default.
14187
Baptiste Assmann686408b2017-08-18 10:15:42 +020014188 Default value is 10s for "valid", 0s for "obsolete" and 30s for others.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014189
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014190resolve_retries <nb>
14191 Defines the number <nb> of queries to send to resolve a server name before
14192 giving up.
14193 Default value: 3
14194
Baptiste Assmann62b75b42015-09-09 01:11:36 +020014195 A retry occurs on name server timeout or when the full sequence of DNS query
14196 type failover is over and we need to start up from the default ANY query
14197 type.
14198
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014199timeout <event> <time>
14200 Defines timeouts related to name resolution
14201 <event> : the event on which the <time> timeout period applies to.
14202 events available are:
Frédéric Lécaille93d33162019-03-06 09:35:59 +010014203 - resolve : default time to trigger name resolutions when no
14204 other time applied.
Christopher Faulet67957bd2017-09-27 11:00:59 +020014205 Default value: 1s
14206 - retry : time between two DNS queries, when no valid response
Frédéric Lécaille93d33162019-03-06 09:35:59 +010014207 have been received.
Christopher Faulet67957bd2017-09-27 11:00:59 +020014208 Default value: 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014209 <time> : time related to the event. It follows the HAProxy time format.
14210 <time> is expressed in milliseconds.
14211
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020014212 Example:
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014213
14214 resolvers mydns
14215 nameserver dns1 10.0.0.1:53
14216 nameserver dns2 10.0.0.2:53
Ben Draut44e609b2018-05-29 15:40:08 -060014217 parse-resolv-conf
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014218 resolve_retries 3
Christopher Faulet67957bd2017-09-27 11:00:59 +020014219 timeout resolve 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014220 timeout retry 1s
Baptiste Assmann987e16d2016-11-02 22:23:31 +010014221 hold other 30s
14222 hold refused 30s
14223 hold nx 30s
14224 hold timeout 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014225 hold valid 10s
Olivier Houcharda8c6db82017-07-06 18:46:47 +020014226 hold obsolete 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020014227
14228
Christopher Faulet87f1f3d2019-07-18 14:51:20 +0200142296. Cache
14230---------
14231
14232HAProxy provides a cache, which was designed to perform cache on small objects
14233(favicon, css...). This is a minimalist low-maintenance cache which runs in
14234RAM.
14235
14236The cache is based on a memory which is shared between processes and threads,
14237this memory is split in blocks of 1k.
14238
14239If an object is not used anymore, it can be deleted to store a new object
14240independently of its expiration date. The oldest objects are deleted first
14241when we try to allocate a new one.
14242
14243The cache uses a hash of the host header and the URI as the key.
14244
14245It's possible to view the status of a cache using the Unix socket command
14246"show cache" consult section 9.3 "Unix Socket commands" of Management Guide
14247for more details.
14248
14249When an object is delivered from the cache, the server name in the log is
14250replaced by "<CACHE>".
14251
14252
142536.1. Limitation
14254----------------
14255
14256The cache won't store and won't deliver objects in these cases:
14257
14258- If the response is not a 200
14259- If the response contains a Vary header
14260- If the Content-Length + the headers size is greater than "max-object-size"
14261- If the response is not cacheable
14262
14263- If the request is not a GET
14264- If the HTTP version of the request is smaller than 1.1
14265- If the request contains an Authorization header
14266
14267
142686.2. Setup
14269-----------
14270
14271To setup a cache, you must define a cache section and use it in a proxy with
14272the corresponding http-request and response actions.
14273
14274
142756.2.1. Cache section
14276---------------------
14277
14278cache <name>
14279 Declare a cache section, allocate a shared cache memory named <name>, the
14280 size of cache is mandatory.
14281
14282total-max-size <megabytes>
14283 Define the size in RAM of the cache in megabytes. This size is split in
14284 blocks of 1kB which are used by the cache entries. Its maximum value is 4095.
14285
14286max-object-size <bytes>
14287 Define the maximum size of the objects to be cached. Must not be greater than
14288 an half of "total-max-size". If not set, it equals to a 256th of the cache size.
14289 All objects with sizes larger than "max-object-size" will not be cached.
14290
14291max-age <seconds>
14292 Define the maximum expiration duration. The expiration is set has the lowest
14293 value between the s-maxage or max-age (in this order) directive in the
14294 Cache-Control response header and this value. The default value is 60
14295 seconds, which means that you can't cache an object more than 60 seconds by
14296 default.
14297
14298
142996.2.2. Proxy section
14300---------------------
14301
14302http-request cache-use <name> [ { if | unless } <condition> ]
14303 Try to deliver a cached object from the cache <name>. This directive is also
14304 mandatory to store the cache as it calculates the cache hash. If you want to
14305 use a condition for both storage and delivering that's a good idea to put it
14306 after this one.
14307
14308http-response cache-store <name> [ { if | unless } <condition> ]
14309 Store an http-response within the cache. The storage of the response headers
14310 is done at this step, which means you can use others http-response actions
14311 to modify headers before or after the storage of the response. This action
14312 is responsible for the setup of the cache storage filter.
14313
14314
14315Example:
14316
14317 backend bck1
14318 mode http
14319
14320 http-request cache-use foobar
14321 http-response cache-store foobar
14322 server srv1 127.0.0.1:80
14323
14324 cache foobar
14325 total-max-size 4
14326 max-age 240
14327
14328
Willy Tarreau74ca5042013-06-11 23:12:07 +0200143297. Using ACLs and fetching samples
14330----------------------------------
14331
Davor Ocelice9ed2812017-12-25 17:49:28 +010014332HAProxy is capable of extracting data from request or response streams, from
Willy Tarreau74ca5042013-06-11 23:12:07 +020014333client or server information, from tables, environmental information etc...
14334The action of extracting such data is called fetching a sample. Once retrieved,
14335these samples may be used for various purposes such as a key to a stick-table,
14336but most common usages consist in matching them against predefined constant
14337data called patterns.
14338
14339
143407.1. ACL basics
14341---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014342
14343The use of Access Control Lists (ACL) provides a flexible solution to perform
14344content switching and generally to take decisions based on content extracted
14345from the request, the response or any environmental status. The principle is
14346simple :
14347
Willy Tarreau74ca5042013-06-11 23:12:07 +020014348 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014349 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020014350 - apply one or multiple pattern matching methods on this sample
14351 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014352
Willy Tarreau74ca5042013-06-11 23:12:07 +020014353The actions generally consist in blocking a request, selecting a backend, or
14354adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014355
14356In order to define a test, the "acl" keyword is used. The syntax is :
14357
Willy Tarreau74ca5042013-06-11 23:12:07 +020014358 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014359
14360This creates a new ACL <aclname> or completes an existing one with new tests.
14361Those tests apply to the portion of request/response specified in <criterion>
14362and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014363an operator which may be specified before the set of values. Optionally some
14364conversion operators may be applied to the sample, and they will be specified
14365as a comma-delimited list of keywords just after the first keyword. The values
14366are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014367
14368ACL names must be formed from upper and lower case letters, digits, '-' (dash),
14369'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
14370which means that "my_acl" and "My_Acl" are two different ACLs.
14371
14372There is no enforced limit to the number of ACLs. The unused ones do not affect
14373performance, they just consume a small amount of memory.
14374
Willy Tarreau74ca5042013-06-11 23:12:07 +020014375The criterion generally is the name of a sample fetch method, or one of its ACL
14376specific declinations. The default test method is implied by the output type of
14377this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014378methods of a same sample fetch method. The sample fetch methods are the only
14379ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014380
14381Sample fetch methods return data which can be of the following types :
14382 - boolean
14383 - integer (signed or unsigned)
14384 - IPv4 or IPv6 address
14385 - string
14386 - data block
14387
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014388Converters transform any of these data into any of these. For example, some
14389converters might convert a string to a lower-case string while other ones
14390would turn a string to an IPv4 address, or apply a netmask to an IP address.
14391The resulting sample is of the type of the last converter applied to the list,
14392which defaults to the type of the sample fetch method.
14393
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014394Each sample or converter returns data of a specific type, specified with its
14395keyword in this documentation. When an ACL is declared using a standard sample
14396fetch method, certain types automatically involved a default matching method
14397which are summarized in the table below :
14398
14399 +---------------------+-----------------+
14400 | Sample or converter | Default |
14401 | output type | matching method |
14402 +---------------------+-----------------+
14403 | boolean | bool |
14404 +---------------------+-----------------+
14405 | integer | int |
14406 +---------------------+-----------------+
14407 | ip | ip |
14408 +---------------------+-----------------+
14409 | string | str |
14410 +---------------------+-----------------+
14411 | binary | none, use "-m" |
14412 +---------------------+-----------------+
14413
14414Note that in order to match a binary samples, it is mandatory to specify a
14415matching method, see below.
14416
Willy Tarreau74ca5042013-06-11 23:12:07 +020014417The ACL engine can match these types against patterns of the following types :
14418 - boolean
14419 - integer or integer range
14420 - IP address / network
14421 - string (exact, substring, suffix, prefix, subdir, domain)
14422 - regular expression
14423 - hex block
14424
Willy Tarreauc57f0e22009-05-10 13:12:33 +020014425The following ACL flags are currently supported :
14426
Willy Tarreau2b5285d2010-05-09 23:45:24 +020014427 -i : ignore case during matching of all subsequent patterns.
14428 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014429 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010014430 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010014431 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010014432 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020014433 -- : force end of flags. Useful when a string looks like one of the flags.
14434
Willy Tarreau74ca5042013-06-11 23:12:07 +020014435The "-f" flag is followed by the name of a file from which all lines will be
14436read as individual values. It is even possible to pass multiple "-f" arguments
14437if the patterns are to be loaded from multiple files. Empty lines as well as
14438lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
14439will be stripped. If it is absolutely necessary to insert a valid pattern
14440beginning with a sharp, just prefix it with a space so that it is not taken for
14441a comment. Depending on the data type and match method, haproxy may load the
14442lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
14443exact string matching. In this case, duplicates will automatically be removed.
14444
Thierry FOURNIER9860c412014-01-29 14:23:29 +010014445The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
14446parsed as two column file. The first column contains the patterns used by the
14447ACL, and the second column contain the samples. The sample can be used later by
14448a map. This can be useful in some rare cases where an ACL would just be used to
14449check for the existence of a pattern in a map before a mapping is applied.
14450
Thierry FOURNIER3534d882014-01-20 17:01:44 +010014451The "-u" flag forces the unique id of the ACL. This unique id is used with the
14452socket interface to identify ACL and dynamically change its values. Note that a
14453file is always identified by its name even if an id is set.
14454
Willy Tarreau74ca5042013-06-11 23:12:07 +020014455Also, note that the "-i" flag applies to subsequent entries and not to entries
14456loaded from files preceding it. For instance :
14457
14458 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
14459
14460In this example, each line of "exact-ua.lst" will be exactly matched against
14461the "user-agent" header of the request. Then each line of "generic-ua" will be
14462case-insensitively matched. Then the word "test" will be insensitively matched
14463as well.
14464
14465The "-m" flag is used to select a specific pattern matching method on the input
14466sample. All ACL-specific criteria imply a pattern matching method and generally
14467do not need this flag. However, this flag is useful with generic sample fetch
14468methods to describe how they're going to be matched against the patterns. This
14469is required for sample fetches which return data type for which there is no
Davor Ocelice9ed2812017-12-25 17:49:28 +010014470obvious matching method (e.g. string or binary). When "-m" is specified and
Willy Tarreau74ca5042013-06-11 23:12:07 +020014471followed by a pattern matching method name, this method is used instead of the
14472default one for the criterion. This makes it possible to match contents in ways
14473that were not initially planned, or with sample fetch methods which return a
14474string. The matching method also affects the way the patterns are parsed.
14475
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010014476The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
14477By default, if the parser cannot parse ip address it considers that the parsed
14478string is maybe a domain name and try dns resolution. The flag "-n" disable this
14479resolution. It is useful for detecting malformed ip lists. Note that if the DNS
14480server is not reachable, the haproxy configuration parsing may last many minutes
John Roeslerfb2fce12019-07-10 15:45:51 -050014481waiting for the timeout. During this time no error messages are displayed. The
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010014482flag "-n" disable this behavior. Note also that during the runtime, this
14483function is disabled for the dynamic acl modifications.
14484
Willy Tarreau74ca5042013-06-11 23:12:07 +020014485There are some restrictions however. Not all methods can be used with all
14486sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
14487be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020014488
14489 - "found" : only check if the requested sample could be found in the stream,
14490 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020014491 to pass any pattern to avoid confusion. This matching method is
14492 particularly useful to detect presence of certain contents such
14493 as headers, cookies, etc... even if they are empty and without
14494 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014495
14496 - "bool" : check the value as a boolean. It can only be applied to fetches
14497 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014498 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014499
14500 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020014501 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014502
14503 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020014504 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014505
Davor Ocelice9ed2812017-12-25 17:49:28 +010014506 - "bin" : match the contents against a hexadecimal string representing a
Willy Tarreau5adeda12013-03-31 22:13:34 +020014507 binary sequence. This may be used with binary or string samples.
14508
14509 - "len" : match the sample's length as an integer. This may be used with
14510 binary or string samples.
14511
Willy Tarreau74ca5042013-06-11 23:12:07 +020014512 - "str" : exact match : match the contents against a string. This may be
14513 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014514
Willy Tarreau74ca5042013-06-11 23:12:07 +020014515 - "sub" : substring match : check that the contents contain at least one of
14516 the provided string patterns. This may be used with binary or
14517 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014518
Willy Tarreau74ca5042013-06-11 23:12:07 +020014519 - "reg" : regex match : match the contents against a list of regular
14520 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014521
Willy Tarreau74ca5042013-06-11 23:12:07 +020014522 - "beg" : prefix match : check that the contents begin like the provided
14523 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014524
Willy Tarreau74ca5042013-06-11 23:12:07 +020014525 - "end" : suffix match : check that the contents end like the provided
14526 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014527
Willy Tarreau74ca5042013-06-11 23:12:07 +020014528 - "dir" : subdir match : check that a slash-delimited portion of the
14529 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014530 This may be used with binary or string samples.
14531
Willy Tarreau74ca5042013-06-11 23:12:07 +020014532 - "dom" : domain match : check that a dot-delimited portion of the contents
14533 exactly match one of the provided string patterns. This may be
14534 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020014535
14536For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
14537request, it is possible to do :
14538
14539 acl jsess_present cook(JSESSIONID) -m found
14540
14541In order to apply a regular expression on the 500 first bytes of data in the
14542buffer, one would use the following acl :
14543
14544 acl script_tag payload(0,500) -m reg -i <script>
14545
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014546On systems where the regex library is much slower when using "-i", it is
14547possible to convert the sample to lowercase before matching, like this :
14548
14549 acl script_tag payload(0,500),lower -m reg <script>
14550
Willy Tarreau74ca5042013-06-11 23:12:07 +020014551All ACL-specific criteria imply a default matching method. Most often, these
14552criteria are composed by concatenating the name of the original sample fetch
14553method and the matching method. For example, "hdr_beg" applies the "beg" match
14554to samples retrieved using the "hdr" fetch method. Since all ACL-specific
14555criteria rely on a sample fetch method, it is always possible instead to use
14556the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020014557
Willy Tarreau74ca5042013-06-11 23:12:07 +020014558If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014559the matching method is simply applied to the underlying sample fetch method.
14560For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020014561
Willy Tarreau74ca5042013-06-11 23:12:07 +020014562 acl short_form hdr_beg(host) www.
14563 acl alternate1 hdr_beg(host) -m beg www.
14564 acl alternate2 hdr_dom(host) -m beg www.
14565 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020014566
Willy Tarreau2b5285d2010-05-09 23:45:24 +020014567
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014568The table below summarizes the compatibility matrix between sample or converter
14569types and the pattern types to fetch against. It indicates for each compatible
14570combination the name of the matching method to be used, surrounded with angle
14571brackets ">" and "<" when the method is the default one and will work by
14572default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010014573
Willy Tarreau74ca5042013-06-11 23:12:07 +020014574 +-------------------------------------------------+
14575 | Input sample type |
14576 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014577 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014578 +----------------------+---------+---------+---------+---------+---------+
14579 | none (presence only) | found | found | found | found | found |
14580 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014581 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014582 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014583 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014584 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014585 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014586 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014587 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014588 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020014589 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014590 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014591 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014592 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014593 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014594 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014595 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014596 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014597 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014598 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014599 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014600 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010014601 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020014602 +----------------------+---------+---------+---------+---------+---------+
14603 | hex block | | | | bin | bin |
14604 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020014605
14606
Willy Tarreau74ca5042013-06-11 23:12:07 +0200146077.1.1. Matching booleans
14608------------------------
14609
14610In order to match a boolean, no value is needed and all values are ignored.
14611Boolean matching is used by default for all fetch methods of type "boolean".
14612When boolean matching is used, the fetched value is returned as-is, which means
14613that a boolean "true" will always match and a boolean "false" will never match.
14614
14615Boolean matching may also be enforced using "-m bool" on fetch methods which
14616return an integer value. Then, integer value 0 is converted to the boolean
14617"false" and all other values are converted to "true".
14618
Willy Tarreau6a06a402007-07-15 20:15:28 +020014619
Willy Tarreau74ca5042013-06-11 23:12:07 +0200146207.1.2. Matching integers
14621------------------------
14622
14623Integer matching applies by default to integer fetch methods. It can also be
14624enforced on boolean fetches using "-m int". In this case, "false" is converted
14625to the integer 0, and "true" is converted to the integer 1.
14626
14627Integer matching also supports integer ranges and operators. Note that integer
14628matching only applies to positive values. A range is a value expressed with a
14629lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020014630
14631For instance, "1024:65535" is a valid range to represent a range of
14632unprivileged ports, and "1024:" would also work. "0:1023" is a valid
14633representation of privileged ports, and ":1023" would also work.
14634
Willy Tarreau62644772008-07-16 18:36:06 +020014635As a special case, some ACL functions support decimal numbers which are in fact
14636two integers separated by a dot. This is used with some version checks for
14637instance. All integer properties apply to those decimal numbers, including
14638ranges and operators.
14639
Willy Tarreau6a06a402007-07-15 20:15:28 +020014640For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010014641operators with ranges does not make much sense and is strongly discouraged.
14642Similarly, it does not make much sense to perform order comparisons with a set
14643of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020014644
Willy Tarreau0ba27502007-12-24 16:55:16 +010014645Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020014646
14647 eq : true if the tested value equals at least one value
14648 ge : true if the tested value is greater than or equal to at least one value
14649 gt : true if the tested value is greater than at least one value
14650 le : true if the tested value is less than or equal to at least one value
14651 lt : true if the tested value is less than at least one value
14652
Willy Tarreau0ba27502007-12-24 16:55:16 +010014653For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020014654
14655 acl negative-length hdr_val(content-length) lt 0
14656
Willy Tarreau62644772008-07-16 18:36:06 +020014657This one matches SSL versions between 3.0 and 3.1 (inclusive) :
14658
14659 acl sslv3 req_ssl_ver 3:3.1
14660
Willy Tarreau6a06a402007-07-15 20:15:28 +020014661
Willy Tarreau74ca5042013-06-11 23:12:07 +0200146627.1.3. Matching strings
14663-----------------------
14664
14665String matching applies to string or binary fetch methods, and exists in 6
14666different forms :
14667
14668 - exact match (-m str) : the extracted string must exactly match the
Davor Ocelice9ed2812017-12-25 17:49:28 +010014669 patterns;
Willy Tarreau74ca5042013-06-11 23:12:07 +020014670
14671 - substring match (-m sub) : the patterns are looked up inside the
Davor Ocelice9ed2812017-12-25 17:49:28 +010014672 extracted string, and the ACL matches if any of them is found inside;
Willy Tarreau74ca5042013-06-11 23:12:07 +020014673
14674 - prefix match (-m beg) : the patterns are compared with the beginning of
14675 the extracted string, and the ACL matches if any of them matches.
14676
14677 - suffix match (-m end) : the patterns are compared with the end of the
14678 extracted string, and the ACL matches if any of them matches.
14679
Baptiste Assmann33db6002016-03-06 23:32:10 +010014680 - subdir match (-m dir) : the patterns are looked up inside the extracted
Willy Tarreau74ca5042013-06-11 23:12:07 +020014681 string, delimited with slashes ("/"), and the ACL matches if any of them
14682 matches.
14683
14684 - domain match (-m dom) : the patterns are looked up inside the extracted
14685 string, delimited with dots ("."), and the ACL matches if any of them
14686 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020014687
14688String matching applies to verbatim strings as they are passed, with the
14689exception of the backslash ("\") which makes it possible to escape some
14690characters such as the space. If the "-i" flag is passed before the first
14691string, then the matching will be performed ignoring the case. In order
14692to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010014693before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020014694
Mathias Weiersmuellercb250fc2019-12-02 09:43:40 +010014695Do not use string matches for binary fetches which might contain null bytes
14696(0x00), as the comparison stops at the occurrence of the first null byte.
14697Instead, convert the binary fetch to a hex string with the hex converter first.
14698
14699Example:
14700 # matches if the string <tag> is present in the binary sample
14701 acl tag_found req.payload(0,0),hex -m sub 3C7461673E
14702
Willy Tarreau6a06a402007-07-15 20:15:28 +020014703
Willy Tarreau74ca5042013-06-11 23:12:07 +0200147047.1.4. Matching regular expressions (regexes)
14705---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020014706
14707Just like with string matching, regex matching applies to verbatim strings as
14708they are passed, with the exception of the backslash ("\") which makes it
14709possible to escape some characters such as the space. If the "-i" flag is
14710passed before the first regex, then the matching will be performed ignoring
14711the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010014712the "--" flag before the first string. Same principle applies of course to
14713match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020014714
14715
Willy Tarreau74ca5042013-06-11 23:12:07 +0200147167.1.5. Matching arbitrary data blocks
14717-------------------------------------
14718
14719It is possible to match some extracted samples against a binary block which may
14720not safely be represented as a string. For this, the patterns must be passed as
14721a series of hexadecimal digits in an even number, when the match method is set
14722to binary. Each sequence of two digits will represent a byte. The hexadecimal
14723digits may be used upper or lower case.
14724
14725Example :
14726 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
14727 acl hello payload(0,6) -m bin 48656c6c6f0a
14728
14729
147307.1.6. Matching IPv4 and IPv6 addresses
14731---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020014732
14733IPv4 addresses values can be specified either as plain addresses or with a
14734netmask appended, in which case the IPv4 address matches whenever it is
14735within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010014736host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010014737difficult to read and debug configurations. If hostnames are used, you should
14738at least ensure that they are present in /etc/hosts so that the configuration
14739does not depend on any random DNS match at the moment the configuration is
14740parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020014741
Daniel Schnellereba56342016-04-13 00:26:52 +020014742The dotted IPv4 address notation is supported in both regular as well as the
14743abbreviated form with all-0-octets omitted:
14744
14745 +------------------+------------------+------------------+
14746 | Example 1 | Example 2 | Example 3 |
14747 +------------------+------------------+------------------+
14748 | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 |
14749 | 192.168.1 | 10.12 | 127.1 |
14750 | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 |
14751 | 192.168.1/22 | 10.12/8 | 127.1/8 |
14752 +------------------+------------------+------------------+
14753
14754Notice that this is different from RFC 4632 CIDR address notation in which
14755192.168.42/24 would be equivalent to 192.168.42.0/24.
14756
Willy Tarreauceb4ac92012-04-28 00:41:46 +020014757IPv6 may be entered in their usual form, with or without a netmask appended.
14758Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
14759trouble with randomly resolved IP addresses, host names are never allowed in
14760IPv6 patterns.
14761
14762HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
14763following situations :
14764 - tested address is IPv4, pattern address is IPv4, the match applies
14765 in IPv4 using the supplied mask if any.
14766 - tested address is IPv6, pattern address is IPv6, the match applies
14767 in IPv6 using the supplied mask if any.
14768 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
14769 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
14770 ::IPV4 or ::ffff:IPV4, otherwise it fails.
14771 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
14772 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
14773 applied in IPv6 using the supplied IPv6 mask.
14774
Willy Tarreau74ca5042013-06-11 23:12:07 +020014775
147767.2. Using ACLs to form conditions
14777----------------------------------
14778
14779Some actions are only performed upon a valid condition. A condition is a
14780combination of ACLs with operators. 3 operators are supported :
14781
14782 - AND (implicit)
14783 - OR (explicit with the "or" keyword or the "||" operator)
14784 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020014785
Willy Tarreau74ca5042013-06-11 23:12:07 +020014786A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020014787
Willy Tarreau74ca5042013-06-11 23:12:07 +020014788 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020014789
Willy Tarreau74ca5042013-06-11 23:12:07 +020014790Such conditions are generally used after an "if" or "unless" statement,
14791indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020014792
Willy Tarreau74ca5042013-06-11 23:12:07 +020014793For instance, to block HTTP requests to the "*" URL with methods other than
14794"OPTIONS", as well as POST requests without content-length, and GET or HEAD
14795requests with a content-length greater than 0, and finally every request which
14796is not either GET/HEAD/POST/OPTIONS !
14797
14798 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030014799 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
14800 http-request deny if METH_GET HTTP_CONTENT
14801 http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreau74ca5042013-06-11 23:12:07 +020014802
14803To select a different backend for requests to static contents on the "www" site
14804and to every request on the "img", "video", "download" and "ftp" hosts :
14805
14806 acl url_static path_beg /static /images /img /css
14807 acl url_static path_end .gif .png .jpg .css .js
14808 acl host_www hdr_beg(host) -i www
14809 acl host_static hdr_beg(host) -i img. video. download. ftp.
14810
Davor Ocelice9ed2812017-12-25 17:49:28 +010014811 # now use backend "static" for all static-only hosts, and for static URLs
Willy Tarreau74ca5042013-06-11 23:12:07 +020014812 # of host "www". Use backend "www" for the rest.
14813 use_backend static if host_static or host_www url_static
14814 use_backend www if host_www
14815
14816It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
14817expressions that are built on the fly without needing to be declared. They must
14818be enclosed between braces, with a space before and after each brace (because
14819the braces must be seen as independent words). Example :
14820
14821 The following rule :
14822
14823 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030014824 http-request deny if METH_POST missing_cl
Willy Tarreau74ca5042013-06-11 23:12:07 +020014825
14826 Can also be written that way :
14827
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030014828 http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 }
Willy Tarreau74ca5042013-06-11 23:12:07 +020014829
14830It is generally not recommended to use this construct because it's a lot easier
14831to leave errors in the configuration when written that way. However, for very
14832simple rules matching only one source IP address for instance, it can make more
14833sense to use them than to declare ACLs with random names. Another example of
14834good use is the following :
14835
14836 With named ACLs :
14837
14838 acl site_dead nbsrv(dynamic) lt 2
14839 acl site_dead nbsrv(static) lt 2
14840 monitor fail if site_dead
14841
14842 With anonymous ACLs :
14843
14844 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
14845
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030014846See section 4.2 for detailed help on the "http-request deny" and "use_backend"
14847keywords.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014848
14849
148507.3. Fetching samples
14851---------------------
14852
14853Historically, sample fetch methods were only used to retrieve data to match
14854against patterns using ACLs. With the arrival of stick-tables, a new class of
14855sample fetch methods was created, most often sharing the same syntax as their
14856ACL counterpart. These sample fetch methods are also known as "fetches". As
14857of now, ACLs and fetches have converged. All ACL fetch methods have been made
14858available as fetch methods, and ACLs may use any sample fetch method as well.
14859
14860This section details all available sample fetch methods and their output type.
14861Some sample fetch methods have deprecated aliases that are used to maintain
14862compatibility with existing configurations. They are then explicitly marked as
14863deprecated and should not be used in new setups.
14864
14865The ACL derivatives are also indicated when available, with their respective
14866matching methods. These ones all have a well defined default pattern matching
14867method, so it is never necessary (though allowed) to pass the "-m" option to
14868indicate how the sample will be matched using ACLs.
14869
14870As indicated in the sample type versus matching compatibility matrix above,
14871when using a generic sample fetch method in an ACL, the "-m" option is
14872mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
14873the same keyword exists as an ACL keyword and as a standard fetch method, the
14874ACL engine will automatically pick the ACL-only one by default.
14875
14876Some of these keywords support one or multiple mandatory arguments, and one or
14877multiple optional arguments. These arguments are strongly typed and are checked
14878when the configuration is parsed so that there is no risk of running with an
Davor Ocelice9ed2812017-12-25 17:49:28 +010014879incorrect argument (e.g. an unresolved backend name). Fetch function arguments
14880are passed between parenthesis and are delimited by commas. When an argument
Willy Tarreau74ca5042013-06-11 23:12:07 +020014881is optional, it will be indicated below between square brackets ('[ ]'). When
14882all arguments are optional, the parenthesis may be omitted.
14883
14884Thus, the syntax of a standard sample fetch method is one of the following :
14885 - name
14886 - name(arg1)
14887 - name(arg1,arg2)
14888
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014889
148907.3.1. Converters
14891-----------------
14892
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014893Sample fetch methods may be combined with transformations to be applied on top
14894of the fetched sample (also called "converters"). These combinations form what
14895is called "sample expressions" and the result is a "sample". Initially this
14896was only supported by "stick on" and "stick store-request" directives but this
Davor Ocelice9ed2812017-12-25 17:49:28 +010014897has now be extended to all places where samples may be used (ACLs, log-format,
Willy Tarreaue6b11e42013-11-26 19:02:32 +010014898unique-id-format, add-header, ...).
14899
14900These transformations are enumerated as a series of specific keywords after the
14901sample fetch method. These keywords may equally be appended immediately after
14902the fetch keyword's argument, delimited by a comma. These keywords can also
Davor Ocelice9ed2812017-12-25 17:49:28 +010014903support some arguments (e.g. a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010014904
Willy Tarreau97707872015-01-27 15:12:13 +010014905A certain category of converters are bitwise and arithmetic operators which
14906support performing basic operations on integers. Some bitwise operations are
14907supported (and, or, xor, cpl) and some arithmetic operations are supported
14908(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
14909bool) which make it possible to report a match without having to write an ACL.
14910
Willy Tarreau74ca5042013-06-11 23:12:07 +020014911The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010014912
Ben Shillitof25e8e52016-12-02 14:25:37 +00001491351d.single(<prop>[,<prop>*])
14914 Returns values for the properties requested as a string, where values are
14915 separated by the delimiter specified with "51degrees-property-separator".
14916 The device is identified using the User-Agent header passed to the
14917 converter. The function can be passed up to five property names, and if a
14918 property name can't be found, the value "NoData" is returned.
14919
14920 Example :
Davor Ocelice9ed2812017-12-25 17:49:28 +010014921 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request,
14922 # containing values for the three properties requested by using the
Ben Shillitof25e8e52016-12-02 14:25:37 +000014923 # User-Agent passed to the converter.
14924 frontend http-in
14925 bind *:8081
14926 default_backend servers
14927 http-request set-header X-51D-DeviceTypeMobileTablet \
14928 %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
14929
Willy Tarreau97707872015-01-27 15:12:13 +010014930add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014931 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014932 result as a signed integer. <value> can be a numeric value or a variable
Daniel Schneller0b547052016-03-21 20:46:57 +010014933 name. The name of the variable starts with an indication about its scope. The
14934 scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014935 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014936 "sess" : the variable is shared with the whole session
14937 "txn" : the variable is shared with the transaction (request and response)
14938 "req" : the variable is shared only during request processing
14939 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014940 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014941 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014942
Nenad Merdanovicc31499d2019-03-23 11:00:32 +010014943aes_gcm_dec(<bits>,<nonce>,<key>,<aead_tag>)
14944 Decrypts the raw byte input using the AES128-GCM, AES192-GCM or
14945 AES256-GCM algorithm, depending on the <bits> parameter. All other parameters
14946 need to be base64 encoded and the returned result is in raw byte format.
14947 If the <aead_tag> validation fails, the converter doesn't return any data.
14948 The <nonce>, <key> and <aead_tag> can either be strings or variables. This
14949 converter requires at least OpenSSL 1.0.1.
14950
14951 Example:
14952 http-response set-header X-Decrypted-Text %[var(txn.enc),\
14953 aes_gcm_dec(128,txn.nonce,Zm9vb2Zvb29mb29wZm9vbw==,txn.aead_tag)]
14954
Willy Tarreau97707872015-01-27 15:12:13 +010014955and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014956 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014957 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010014958 numeric value or a variable name. The name of the variable starts with an
14959 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014960 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014961 "sess" : the variable is shared with the whole session
14962 "txn" : the variable is shared with the transaction (request and response)
14963 "req" : the variable is shared only during request processing
14964 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014965 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014966 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014967
Holger Just1bfc24b2017-05-06 00:56:53 +020014968b64dec
14969 Converts (decodes) a base64 encoded input string to its binary
14970 representation. It performs the inverse operation of base64().
14971
Emeric Brun53d1a982014-04-30 18:21:37 +020014972base64
14973 Converts a binary input sample to a base64 string. It is used to log or
Davor Ocelice9ed2812017-12-25 17:49:28 +010014974 transfer binary content in a way that can be reliably transferred (e.g.
Emeric Brun53d1a982014-04-30 18:21:37 +020014975 an SSL ID can be copied in a header).
14976
Willy Tarreau97707872015-01-27 15:12:13 +010014977bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014978 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010014979 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010014980 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010014981 presence of a flag).
14982
Emeric Brun54c4ac82014-11-03 15:32:43 +010014983bytes(<offset>[,<length>])
14984 Extracts some bytes from an input binary sample. The result is a binary
14985 sample starting at an offset (in bytes) of the original sample and
Tim Düsterhus4896c442016-11-29 02:15:19 +010014986 optionally truncated at the given length.
Emeric Brun54c4ac82014-11-03 15:32:43 +010014987
Willy Tarreau280f42b2018-02-19 15:34:12 +010014988concat([<start>],[<var>],[<end>])
14989 Concatenates up to 3 fields after the current sample which is then turned to
14990 a string. The first one, <start>, is a constant string, that will be appended
14991 immediately after the existing sample. It may be omitted if not used. The
14992 second one, <var>, is a variable name. The variable will be looked up, its
14993 contents converted to a string, and it will be appended immediately after the
14994 <first> part. If the variable is not found, nothing is appended. It may be
14995 omitted as well. The third field, <end> is a constant string that will be
14996 appended after the variable. It may also be omitted. Together, these elements
14997 allow to concatenate variables with delimiters to an existing set of
14998 variables. This can be used to build new variables made of a succession of
Willy Tarreauef21fac2020-02-14 13:37:20 +010014999 other variables, such as colon-delimited values. If commas or closing
Daniel Corbett67a82712020-07-06 23:01:19 -040015000 parenthesis are needed as delimiters, they must be protected by quotes or
Willy Tarreauef21fac2020-02-14 13:37:20 +010015001 backslashes, themselves protected so that they are not stripped by the first
15002 level parser. See examples below.
Willy Tarreau280f42b2018-02-19 15:34:12 +010015003
15004 Example:
15005 tcp-request session set-var(sess.src) src
15006 tcp-request session set-var(sess.dn) ssl_c_s_dn
15007 tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>)
Willy Tarreauef21fac2020-02-14 13:37:20 +010015008 tcp-request session set-var(txn.ipport) "str(),concat('addr=(',sess.ip),concat(',',sess.port,')')"
Willy Tarreau280f42b2018-02-19 15:34:12 +010015009 http-request set-header x-hap-sig %[var(txn.sig)]
15010
Willy Tarreau97707872015-01-27 15:12:13 +010015011cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015012 Takes the input value of type signed integer, applies a ones-complement
15013 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010015014
Willy Tarreau80599772015-01-20 19:35:24 +010015015crc32([<avalanche>])
15016 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
15017 hash function. Optionally, it is possible to apply a full avalanche hash
15018 function to the output if the optional <avalanche> argument equals 1. This
15019 converter uses the same functions as used by the various hash-based load
15020 balancing algorithms, so it will provide exactly the same results. It is
15021 provided for compatibility with other software which want a CRC32 to be
15022 computed on some input keys, so it follows the most common implementation as
15023 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
15024 but may provide a better or at least less predictable distribution. It must
15025 not be used for security purposes as a 32-bit hash is trivial to break. See
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010015026 also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive.
15027
15028crc32c([<avalanche>])
15029 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C
15030 hash function. Optionally, it is possible to apply a full avalanche hash
15031 function to the output if the optional <avalanche> argument equals 1. This
15032 converter uses the same functions as described in RFC4960, Appendix B [8].
15033 It is provided for compatibility with other software which want a CRC32C to be
15034 computed on some input keys. It is slower than the other algorithms and it must
15035 not be used for security purposes as a 32-bit hash is trivial to break. See
15036 also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive.
Willy Tarreau80599772015-01-20 19:35:24 +010015037
Christopher Fauletea159d62020-04-01 16:21:44 +020015038cut_crlf
15039 Cuts the string representation of the input sample on the first carriage
15040 return ('\r') or newline ('\n') character found. Only the string length is
15041 updated.
15042
David Carlier29b3ca32015-09-25 14:09:21 +010015043da-csv-conv(<prop>[,<prop>*])
David Carlier4542b102015-06-01 13:54:29 +020015044 Asks the DeviceAtlas converter to identify the User Agent string passed on
15045 input, and to emit a string made of the concatenation of the properties
15046 enumerated in argument, delimited by the separator defined by the global
15047 keyword "deviceatlas-property-separator", or by default the pipe character
David Carlier840b0242016-03-16 10:09:55 +000015048 ('|'). There's a limit of 12 different properties imposed by the haproxy
David Carlier4542b102015-06-01 13:54:29 +020015049 configuration language.
15050
15051 Example:
15052 frontend www
Cyril Bonté307ee1e2015-09-28 23:16:06 +020015053 bind *:8881
15054 default_backend servers
David Carlier840b0242016-03-16 10:09:55 +000015055 http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
David Carlier4542b102015-06-01 13:54:29 +020015056
Willy Tarreau0851fd52019-12-17 10:07:25 +010015057debug([<prefix][,<destination>])
15058 This converter is used as debug tool. It takes a capture of the input sample
15059 and sends it to event sink <destination>, which may designate a ring buffer
15060 such as "buf0", as well as "stdout", or "stderr". Available sinks may be
15061 checked at run time by issuing "show events" on the CLI. When not specified,
15062 the output will be "buf0", which may be consulted via the CLI's "show events"
15063 command. An optional prefix <prefix> may be passed to help distinguish
15064 outputs from multiple expressions. It will then appear before the colon in
15065 the output message. The input sample is passed as-is on the output, so that
15066 it is safe to insert the debug converter anywhere in a chain, even with non-
15067 printable sample types.
15068
15069 Example:
15070 tcp-request connection track-sc0 src,debug(track-sc)
Thierry FOURNIER9687c772015-05-07 15:46:29 +020015071
Patrick Gansterer8e366512020-04-22 16:47:57 +020015072digest(<algorithm>)
15073 Converts a binary input sample to a message digest. The result is a binary
15074 sample. The <algorithm> must be an OpenSSL message digest name (e.g. sha256).
15075
15076 Please note that this converter is only available when haproxy has been
15077 compiled with USE_OPENSSL.
15078
Willy Tarreau97707872015-01-27 15:12:13 +010015079div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015080 Divides the input value of type signed integer by <value>, and returns the
15081 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015082 integer is returned (typically 2^63-1). <value> can be a numeric value or a
Daniel Schneller0b547052016-03-21 20:46:57 +010015083 variable name. The name of the variable starts with an indication about its
15084 scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015085 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015086 "sess" : the variable is shared with the whole session
15087 "txn" : the variable is shared with the transaction (request and response)
15088 "req" : the variable is shared only during request processing
15089 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010015090 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015091 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015092
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015093djb2([<avalanche>])
15094 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
15095 hash function. Optionally, it is possible to apply a full avalanche hash
15096 function to the output if the optional <avalanche> argument equals 1. This
15097 converter uses the same functions as used by the various hash-based load
15098 balancing algorithms, so it will provide exactly the same results. It is
15099 mostly intended for debugging, but can be used as a stick-table entry to
15100 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010015101 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c",
15102 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015103
Willy Tarreau97707872015-01-27 15:12:13 +010015104even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015105 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010015106 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
15107
Marcin Deranek9631a282018-04-16 14:30:46 +020015108field(<index>,<delimiters>[,<count>])
15109 Extracts the substring at the given index counting from the beginning
15110 (positive index) or from the end (negative index) considering given delimiters
15111 from an input string. Indexes start at 1 or -1 and delimiters are a string
15112 formatted list of chars. Optionally you can specify <count> of fields to
15113 extract (default: 1). Value of 0 indicates extraction of all remaining
15114 fields.
15115
15116 Example :
15117 str(f1_f2_f3__f5),field(5,_) # f5
15118 str(f1_f2_f3__f5),field(2,_,0) # f2_f3__f5
15119 str(f1_f2_f3__f5),field(2,_,2) # f2_f3
15120 str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_
15121 str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3
Emeric Brunf399b0d2014-11-03 17:07:03 +010015122
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015123hex
Davor Ocelice9ed2812017-12-25 17:49:28 +010015124 Converts a binary input sample to a hex string containing two hex digits per
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015125 input byte. It is used to log or transfer hex dumps of some binary input data
Davor Ocelice9ed2812017-12-25 17:49:28 +010015126 in a way that can be reliably transferred (e.g. an SSL ID can be copied in a
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015127 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010015128
Dragan Dosen3f957b22017-10-24 09:27:34 +020015129hex2i
15130 Converts a hex string containing two hex digits per input byte to an
John Roeslerfb2fce12019-07-10 15:45:51 -050015131 integer. If the input value cannot be converted, then zero is returned.
Dragan Dosen3f957b22017-10-24 09:27:34 +020015132
Christopher Faulet4ccc12f2020-04-01 09:08:32 +020015133htonl
15134 Converts the input integer value to its 32-bit binary representation in the
15135 network byte order. Because sample fetches own signed 64-bit integer, when
15136 this converter is used, the input integer value is first casted to an
15137 unsigned 32-bit integer.
15138
Patrick Gansterer8e366512020-04-22 16:47:57 +020015139hmac(<algorithm>, <key>)
15140 Converts a binary input sample to a message authentication code with the given
15141 key. The result is a binary sample. The <algorithm> must be one of the
15142 registered OpenSSL message digest names (e.g. sha256). The <key> parameter must
15143 be base64 encoded and can either be a string or a variable.
15144
15145 Please note that this converter is only available when haproxy has been
15146 compiled with USE_OPENSSL.
15147
Cyril Bonté6bcd1822019-11-05 23:13:59 +010015148http_date([<offset],[<unit>])
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015149 Converts an integer supposed to contain a date since epoch to a string
15150 representing this date in a format suitable for use in HTTP header fields. If
Damien Claisseae6f1252019-10-30 15:57:28 +000015151 an offset value is specified, then it is added to the date before the
15152 conversion is operated. This is particularly useful to emit Date header fields,
15153 Expires values in responses when combined with a positive offset, or
15154 Last-Modified values when the offset is negative.
15155 If a unit value is specified, then consider the timestamp as either
15156 "s" for seconds (default behavior), "ms" for milliseconds, or "us" for
15157 microseconds since epoch. Offset is assumed to have the same unit as
15158 input timestamp.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015159
Tim Duesterhus3943e4f2020-09-11 14:25:23 +020015160iif(<true>,<false>)
15161 Returns the <true> string if the input value is true. Returns the <false>
15162 string otherwise.
15163
15164 Example:
Tim Duesterhus870713b2020-09-11 17:13:12 +020015165 http-request set-header x-forwarded-proto %[ssl_fc,iif(https,http)]
Tim Duesterhus3943e4f2020-09-11 14:25:23 +020015166
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015167in_table(<table>)
15168 Uses the string representation of the input sample to perform a look up in
15169 the specified table. If the key is not found in the table, a boolean false
15170 is returned. Otherwise a boolean true is returned. This can be used to verify
Davor Ocelice9ed2812017-12-25 17:49:28 +010015171 the presence of a certain key in a table tracking some elements (e.g. whether
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015172 or not a source IP address or an Authorization header was already seen).
15173
Tim Duesterhus1478aa72018-01-25 16:24:51 +010015174ipmask(<mask4>, [<mask6>])
15175 Apply a mask to an IP address, and use the result for lookups and storage.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020015176 This can be used to make all hosts within a certain mask to share the same
Tim Duesterhus1478aa72018-01-25 16:24:51 +010015177 table entries and as such use the same server. The mask4 can be passed in
15178 dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can
15179 be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64).
15180 If no mask6 is given IPv6 addresses will fail to convert for backwards
15181 compatibility reasons.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020015182
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015183json([<input-code>])
Davor Ocelice9ed2812017-12-25 17:49:28 +010015184 Escapes the input string and produces an ASCII output string ready to use as a
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015185 JSON string. The converter tries to decode the input string according to the
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020015186 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015187 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
15188 of errors:
15189 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
15190 bytes, ...)
15191 - invalid range (the decoded value is within a UTF-8 prohibited range),
15192 - code overlong (the value is encoded with more bytes than necessary).
15193
15194 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
15195 character is greater than 0xffff because the JSON string escape specification
15196 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
15197 in 4 variants designated by a combination of two suffix letters : "p" for
15198 "permissive" and "s" for "silently ignore". The behaviors of the decoders
15199 are :
Davor Ocelice9ed2812017-12-25 17:49:28 +010015200 - "ascii" : never fails;
15201 - "utf8" : fails on any detected errors;
15202 - "utf8s" : never fails, but removes characters corresponding to errors;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015203 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
Davor Ocelice9ed2812017-12-25 17:49:28 +010015204 error;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015205 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
15206 characters corresponding to the other errors.
15207
15208 This converter is particularly useful for building properly escaped JSON for
Davor Ocelice9ed2812017-12-25 17:49:28 +010015209 logging to servers which consume JSON-formatted traffic logs.
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015210
15211 Example:
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015212 capture request header Host len 15
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020015213 capture request header user-agent len 150
15214 log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020015215
15216 Input request from client 127.0.0.1:
15217 GET / HTTP/1.0
15218 User-Agent: Very "Ugly" UA 1/2
15219
15220 Output log:
15221 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
15222
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015223language(<value>[,<default>])
15224 Returns the value with the highest q-factor from a list as extracted from the
15225 "accept-language" header using "req.fhdr". Values with no q-factor have a
15226 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
15227 belong to the list of semi-colon delimited <values> will be considered. The
15228 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
15229 given list and a default value is provided, it is returned. Note that language
15230 names may have a variant after a dash ('-'). If this variant is present in the
15231 list, it will be matched, but if it is not, only the base language is checked.
15232 The match is case-sensitive, and the output string is always one of those
Davor Ocelice9ed2812017-12-25 17:49:28 +010015233 provided in arguments. The ordering of arguments is meaningless, only the
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015234 ordering of the values in the request counts, as the first value among
15235 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020015236
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015237 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020015238
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015239 # this configuration switches to the backend matching a
15240 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020015241
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015242 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
15243 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
15244 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
15245 use_backend spanish if es
15246 use_backend french if fr
15247 use_backend english if en
15248 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020015249
Willy Tarreau60a2ee72017-12-15 07:13:48 +010015250length
Etienne Carriereed0d24e2017-12-13 13:41:34 +010015251 Get the length of the string. This can only be placed after a string
15252 sample fetch function or after a transformation keyword returning a string
15253 type. The result is of type integer.
15254
Willy Tarreauffcb2e42014-07-10 16:29:08 +020015255lower
15256 Convert a string sample to lower case. This can only be placed after a string
15257 sample fetch function or after a transformation keyword returning a string
15258 type. The result is of type string.
15259
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020015260ltime(<format>[,<offset>])
15261 Converts an integer supposed to contain a date since epoch to a string
15262 representing this date in local time using a format defined by the <format>
15263 string using strftime(3). The purpose is to allow any date format to be used
15264 in logs. An optional <offset> in seconds may be applied to the input date
15265 (positive or negative). See the strftime() man page for the format supported
15266 by your operating system. See also the utime converter.
15267
15268 Example :
15269
15270 # Emit two colons, one with the local time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010015271 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020015272 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
15273
Christopher Faulet51fc9d12020-04-01 17:24:41 +020015274ltrim(<chars>)
15275 Skips any characters from <chars> from the beginning of the string
15276 representation of the input sample.
15277
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015278map(<map_file>[,<default_value>])
15279map_<match_type>(<map_file>[,<default_value>])
15280map_<match_type>_<output_type>(<map_file>[,<default_value>])
15281 Search the input value from <map_file> using the <match_type> matching method,
15282 and return the associated value converted to the type <output_type>. If the
15283 input value cannot be found in the <map_file>, the converter returns the
15284 <default_value>. If the <default_value> is not set, the converter fails and
15285 acts as if no input value could be fetched. If the <match_type> is not set, it
15286 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
15287 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
15288 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015289
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015290 It is important to avoid overlapping between the keys : IP addresses and
15291 strings are stored in trees, so the first of the finest match will be used.
15292 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015293
Tim Düsterhus4896c442016-11-29 02:15:19 +010015294 The following array contains the list of all map functions available sorted by
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015295 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015296
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015297 input type | match method | output type str | output type int | output type ip
15298 -----------+--------------+-----------------+-----------------+---------------
15299 str | str | map_str | map_str_int | map_str_ip
15300 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020015301 str | beg | map_beg | map_beg_int | map_end_ip
15302 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015303 str | sub | map_sub | map_sub_int | map_sub_ip
15304 -----------+--------------+-----------------+-----------------+---------------
15305 str | dir | map_dir | map_dir_int | map_dir_ip
15306 -----------+--------------+-----------------+-----------------+---------------
15307 str | dom | map_dom | map_dom_int | map_dom_ip
15308 -----------+--------------+-----------------+-----------------+---------------
15309 str | end | map_end | map_end_int | map_end_ip
15310 -----------+--------------+-----------------+-----------------+---------------
Ruoshan Huang3c5e3742016-12-02 16:25:31 +080015311 str | reg | map_reg | map_reg_int | map_reg_ip
15312 -----------+--------------+-----------------+-----------------+---------------
15313 str | reg | map_regm | map_reg_int | map_reg_ip
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015314 -----------+--------------+-----------------+-----------------+---------------
15315 int | int | map_int | map_int_int | map_int_ip
15316 -----------+--------------+-----------------+-----------------+---------------
15317 ip | ip | map_ip | map_ip_int | map_ip_ip
15318 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015319
Thierry Fournier8feaa662016-02-10 22:55:20 +010015320 The special map called "map_regm" expect matching zone in the regular
15321 expression and modify the output replacing back reference (like "\1") by
15322 the corresponding match text.
15323
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015324 The file contains one key + value per line. Lines which start with '#' are
15325 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
15326 is then the first "word" (series of non-space/tabs characters), and the value
15327 is what follows this series of space/tab till the end of the line excluding
15328 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015329
Thierry FOURNIER060762e2014-04-23 13:29:15 +020015330 Example :
15331
15332 # this is a comment and is ignored
15333 2.22.246.0/23 United Kingdom \n
15334 <-><-----------><--><------------><---->
15335 | | | | `- trailing spaces ignored
15336 | | | `---------- value
15337 | | `-------------------- middle spaces ignored
15338 | `---------------------------- key
15339 `------------------------------------ leading spaces ignored
15340
Willy Tarreau97707872015-01-27 15:12:13 +010015341mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015342 Divides the input value of type signed integer by <value>, and returns the
15343 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015344 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010015345 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015346 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015347 "sess" : the variable is shared with the whole session
15348 "txn" : the variable is shared with the transaction (request and response)
15349 "req" : the variable is shared only during request processing
15350 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010015351 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015352 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015353
15354mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015355 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020015356 the product as an signed integer. In case of overflow, the largest possible
15357 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015358 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010015359 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015360 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015361 "sess" : the variable is shared with the whole session
15362 "txn" : the variable is shared with the transaction (request and response)
15363 "req" : the variable is shared only during request processing
15364 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010015365 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015366 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015367
Nenad Merdanovicb7e7c472017-03-12 21:56:55 +010015368nbsrv
15369 Takes an input value of type string, interprets it as a backend name and
15370 returns the number of usable servers in that backend. Can be used in places
15371 where we want to look up a backend from a dynamic name, like a result of a
15372 map lookup.
15373
Willy Tarreau97707872015-01-27 15:12:13 +010015374neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015375 Takes the input value of type signed integer, computes the opposite value,
15376 and returns the remainder as an signed integer. 0 is identity. This operator
15377 is provided for reversed subtracts : in order to subtract the input from a
15378 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010015379
15380not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015381 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010015382 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010015383 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010015384 absence of a flag).
15385
15386odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015387 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010015388 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
15389
15390or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015391 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015392 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010015393 numeric value or a variable name. The name of the variable starts with an
15394 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015395 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015396 "sess" : the variable is shared with the whole session
15397 "txn" : the variable is shared with the transaction (request and response)
15398 "req" : the variable is shared only during request processing
15399 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010015400 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015401 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015402
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010015403protobuf(<field_number>,[<field_type>])
15404 This extracts the protocol buffers message field in raw mode of an input binary
15405 sample representation of a protocol buffer message with <field_number> as field
15406 number (dotted notation) if <field_type> is not present, or as an integer sample
15407 if this field is present (see also "ungrpc" below).
15408 The list of the authorized types is the following one: "int32", "int64", "uint32",
15409 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
15410 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
15411 "float" for the wire type 5. Note that "string" is considered as a length-delimited
15412 type, so it does not require any <field_type> argument to be extracted.
15413 More information may be found here about the protocol buffers message field types:
15414 https://developers.google.com/protocol-buffers/docs/encoding
15415
Willy Tarreauc4dc3502015-01-23 20:39:28 +010015416regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010015417 Applies a regex-based substitution to the input string. It does the same
15418 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
15419 default it will replace in the input string the first occurrence of the
15420 largest part matching the regular expression <regex> with the substitution
15421 string <subst>. It is possible to replace all occurrences instead by adding
15422 the flag "g" in the third argument <flags>. It is also possible to make the
15423 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
15424 string, it is made up from the concatenation of all desired flags. Thus if
15425 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
Willy Tarreauef21fac2020-02-14 13:37:20 +010015426 The first use of this converter is to replace certain characters or sequence
15427 of characters with other ones.
15428
15429 It is highly recommended to enclose the regex part using protected quotes to
15430 improve clarity and never have a closing parenthesis from the regex mixed up
15431 with the parenthesis from the function. Just like in Bourne shell, the first
15432 level of quotes is processed when delimiting word groups on the line, a
15433 second level is usable for argument. It is recommended to use single quotes
15434 outside since these ones do not try to resolve backslashes nor dollar signs.
Willy Tarreau7eda8492015-01-20 19:47:06 +010015435
Willy Tarreaucd0d2ed2020-02-14 17:33:06 +010015436 Examples:
Willy Tarreau7eda8492015-01-20 19:47:06 +010015437
15438 # de-duplicate "/" in header "x-path".
15439 # input: x-path: /////a///b/c/xzxyz/
15440 # output: x-path: /a/b/c/xzxyz/
Willy Tarreauef21fac2020-02-14 13:37:20 +010015441 http-request set-header x-path "%[hdr(x-path),regsub('/+','/','g')]"
Willy Tarreau7eda8492015-01-20 19:47:06 +010015442
Willy Tarreaucd0d2ed2020-02-14 17:33:06 +010015443 # copy query string to x-query and drop all leading '?', ';' and '&'
15444 http-request set-header x-query "%[query,regsub([?;&]*,'')]"
15445
Jerome Magnin07e1e3c2020-02-16 19:20:19 +010015446 # capture groups and backreferences
15447 # both lines do the same.
15448 http-request redirect location %[url,'regsub("(foo|bar)([0-9]+)?","\2\1",i)]'
15449 http-request redirect location %[url,regsub(\"(foo|bar)([0-9]+)?\",\"\2\1\",i)]
15450
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020015451capture-req(<id>)
15452 Capture the string entry in the request slot <id> and returns the entry as
15453 is. If the slot doesn't exist, the capture fails silently.
15454
15455 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020015456 "http-response capture", "capture.req.hdr" and
15457 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020015458
15459capture-res(<id>)
15460 Capture the string entry in the response slot <id> and returns the entry as
15461 is. If the slot doesn't exist, the capture fails silently.
15462
15463 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020015464 "http-response capture", "capture.req.hdr" and
15465 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020015466
Christopher Faulet568415a2020-04-01 17:24:47 +020015467rtrim(<chars>)
15468 Skips any characters from <chars> from the end of the string representation
15469 of the input sample.
15470
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015471sdbm([<avalanche>])
15472 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
15473 hash function. Optionally, it is possible to apply a full avalanche hash
15474 function to the output if the optional <avalanche> argument equals 1. This
15475 converter uses the same functions as used by the various hash-based load
15476 balancing algorithms, so it will provide exactly the same results. It is
15477 mostly intended for debugging, but can be used as a stick-table entry to
15478 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010015479 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c",
15480 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015481
Tim Duesterhusf38175c2020-06-09 11:48:42 +020015482secure_memcmp(<var>)
15483 Compares the contents of <var> with the input value. Both values are treated
15484 as a binary string. Returns a boolean indicating whether both binary strings
15485 match.
15486
15487 If both binary strings have the same length then the comparison will be
15488 performed in constant time.
15489
15490 Please note that this converter is only available when haproxy has been
15491 compiled with USE_OPENSSL.
15492
15493 Example :
15494
15495 http-request set-var(txn.token) hdr(token)
15496 # Check whether the token sent by the client matches the secret token
15497 # value, without leaking the contents using a timing attack.
15498 acl token_given str(my_secret_token),secure_memcmp(txn.token)
15499
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015500set-var(<var name>)
Davor Ocelice9ed2812017-12-25 17:49:28 +010015501 Sets a variable with the input content and returns the content on the output
15502 as-is. The variable keeps the value and the associated input type. The name of
15503 the variable starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015504 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015505 "sess" : the variable is shared with the whole session
15506 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015507 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010015508 "req" : the variable is shared only during request processing,
15509 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015510 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015511 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015512
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020015513sha1
Tim Duesterhusd4376302019-06-17 12:41:44 +020015514 Converts a binary input sample to a SHA-1 digest. The result is a binary
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020015515 sample with length of 20 bytes.
15516
Tim Duesterhusd4376302019-06-17 12:41:44 +020015517sha2([<bits>])
15518 Converts a binary input sample to a digest in the SHA-2 family. The result
15519 is a binary sample with length of <bits>/8 bytes.
15520
15521 Valid values for <bits> are 224, 256, 384, 512, each corresponding to
15522 SHA-<bits>. The default value is 256.
15523
15524 Please note that this converter is only available when haproxy has been
15525 compiled with USE_OPENSSL.
15526
Nenad Merdanovic177adc92019-08-27 01:58:13 +020015527srv_queue
15528 Takes an input value of type string, either a server name or <backend>/<server>
15529 format and returns the number of queued sessions on that server. Can be used
15530 in places where we want to look up queued sessions from a dynamic name, like a
15531 cookie value (e.g. req.cook(SRVID),srv_queue) and then make a decision to break
15532 persistence or direct a request elsewhere.
15533
Tim Duesterhusca097c12018-04-27 21:18:45 +020015534strcmp(<var>)
15535 Compares the contents of <var> with the input value of type string. Returns
15536 the result as a signed integer compatible with strcmp(3): 0 if both strings
15537 are identical. A value less than 0 if the left string is lexicographically
15538 smaller than the right string or if the left string is shorter. A value greater
15539 than 0 otherwise (right string greater than left string or the right string is
15540 shorter).
15541
Tim Duesterhusf38175c2020-06-09 11:48:42 +020015542 See also the secure_memcmp converter if you need to compare two binary
15543 strings in constant time.
15544
Tim Duesterhusca097c12018-04-27 21:18:45 +020015545 Example :
15546
15547 http-request set-var(txn.host) hdr(host)
15548 # Check whether the client is attempting domain fronting.
15549 acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0
15550
15551
Willy Tarreau97707872015-01-27 15:12:13 +010015552sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015553 Subtracts <value> from the input value of type signed integer, and returns
15554 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015555 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
Daniel Schneller0b547052016-03-21 20:46:57 +010015556 or a variable name. The name of the variable starts with an indication about
15557 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015558 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015559 "sess" : the variable is shared with the whole session
15560 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015561 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010015562 "req" : the variable is shared only during request processing,
15563 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015564 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015565 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015566
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015567table_bytes_in_rate(<table>)
15568 Uses the string representation of the input sample to perform a look up in
15569 the specified table. If the key is not found in the table, integer value zero
15570 is returned. Otherwise the converter returns the average client-to-server
15571 bytes rate associated with the input sample in the designated table, measured
15572 in amount of bytes over the period configured in the table. See also the
15573 sc_bytes_in_rate sample fetch keyword.
15574
15575
15576table_bytes_out_rate(<table>)
15577 Uses the string representation of the input sample to perform a look up in
15578 the specified table. If the key is not found in the table, integer value zero
15579 is returned. Otherwise the converter returns the average server-to-client
15580 bytes rate associated with the input sample in the designated table, measured
15581 in amount of bytes over the period configured in the table. See also the
15582 sc_bytes_out_rate sample fetch keyword.
15583
15584table_conn_cnt(<table>)
15585 Uses the string representation of the input sample to perform a look up in
15586 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010015587 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015588 connections associated with the input sample in the designated table. See
15589 also the sc_conn_cnt sample fetch keyword.
15590
15591table_conn_cur(<table>)
15592 Uses the string representation of the input sample to perform a look up in
15593 the specified table. If the key is not found in the table, integer value zero
15594 is returned. Otherwise the converter returns the current amount of concurrent
15595 tracked connections associated with the input sample in the designated table.
15596 See also the sc_conn_cur sample fetch keyword.
15597
15598table_conn_rate(<table>)
15599 Uses the string representation of the input sample to perform a look up in
15600 the specified table. If the key is not found in the table, integer value zero
15601 is returned. Otherwise the converter returns the average incoming connection
15602 rate associated with the input sample in the designated table. See also the
15603 sc_conn_rate sample fetch keyword.
15604
Thierry FOURNIER236657b2015-08-19 08:25:14 +020015605table_gpt0(<table>)
15606 Uses the string representation of the input sample to perform a look up in
15607 the specified table. If the key is not found in the table, boolean value zero
15608 is returned. Otherwise the converter returns the current value of the first
15609 general purpose tag associated with the input sample in the designated table.
15610 See also the sc_get_gpt0 sample fetch keyword.
15611
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015612table_gpc0(<table>)
15613 Uses the string representation of the input sample to perform a look up in
15614 the specified table. If the key is not found in the table, integer value zero
15615 is returned. Otherwise the converter returns the current value of the first
15616 general purpose counter associated with the input sample in the designated
15617 table. See also the sc_get_gpc0 sample fetch keyword.
15618
15619table_gpc0_rate(<table>)
15620 Uses the string representation of the input sample to perform a look up in
15621 the specified table. If the key is not found in the table, integer value zero
15622 is returned. Otherwise the converter returns the frequency which the gpc0
15623 counter was incremented over the configured period in the table, associated
15624 with the input sample in the designated table. See also the sc_get_gpc0_rate
15625 sample fetch keyword.
15626
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015627table_gpc1(<table>)
15628 Uses the string representation of the input sample to perform a look up in
15629 the specified table. If the key is not found in the table, integer value zero
15630 is returned. Otherwise the converter returns the current value of the second
15631 general purpose counter associated with the input sample in the designated
15632 table. See also the sc_get_gpc1 sample fetch keyword.
15633
15634table_gpc1_rate(<table>)
15635 Uses the string representation of the input sample to perform a look up in
15636 the specified table. If the key is not found in the table, integer value zero
15637 is returned. Otherwise the converter returns the frequency which the gpc1
15638 counter was incremented over the configured period in the table, associated
15639 with the input sample in the designated table. See also the sc_get_gpc1_rate
15640 sample fetch keyword.
15641
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015642table_http_err_cnt(<table>)
15643 Uses the string representation of the input sample to perform a look up in
15644 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010015645 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015646 errors associated with the input sample in the designated table. See also the
15647 sc_http_err_cnt sample fetch keyword.
15648
15649table_http_err_rate(<table>)
15650 Uses the string representation of the input sample to perform a look up in
15651 the specified table. If the key is not found in the table, integer value zero
15652 is returned. Otherwise the average rate of HTTP errors associated with the
15653 input sample in the designated table, measured in amount of errors over the
15654 period configured in the table. See also the sc_http_err_rate sample fetch
15655 keyword.
15656
15657table_http_req_cnt(<table>)
15658 Uses the string representation of the input sample to perform a look up in
15659 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010015660 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015661 requests associated with the input sample in the designated table. See also
15662 the sc_http_req_cnt sample fetch keyword.
15663
15664table_http_req_rate(<table>)
15665 Uses the string representation of the input sample to perform a look up in
15666 the specified table. If the key is not found in the table, integer value zero
15667 is returned. Otherwise the average rate of HTTP requests associated with the
15668 input sample in the designated table, measured in amount of requests over the
15669 period configured in the table. See also the sc_http_req_rate sample fetch
15670 keyword.
15671
15672table_kbytes_in(<table>)
15673 Uses the string representation of the input sample to perform a look up in
15674 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010015675 is returned. Otherwise the converter returns the cumulative number of client-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015676 to-server data associated with the input sample in the designated table,
15677 measured in kilobytes. The test is currently performed on 32-bit integers,
15678 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
15679 keyword.
15680
15681table_kbytes_out(<table>)
15682 Uses the string representation of the input sample to perform a look up in
15683 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010015684 is returned. Otherwise the converter returns the cumulative number of server-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015685 to-client data associated with the input sample in the designated table,
15686 measured in kilobytes. The test is currently performed on 32-bit integers,
15687 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
15688 keyword.
15689
15690table_server_id(<table>)
15691 Uses the string representation of the input sample to perform a look up in
15692 the specified table. If the key is not found in the table, integer value zero
15693 is returned. Otherwise the converter returns the server ID associated with
15694 the input sample in the designated table. A server ID is associated to a
15695 sample by a "stick" rule when a connection to a server succeeds. A server ID
15696 zero means that no server is associated with this key.
15697
15698table_sess_cnt(<table>)
15699 Uses the string representation of the input sample to perform a look up in
15700 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010015701 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020015702 sessions associated with the input sample in the designated table. Note that
15703 a session here refers to an incoming connection being accepted by the
15704 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
15705 keyword.
15706
15707table_sess_rate(<table>)
15708 Uses the string representation of the input sample to perform a look up in
15709 the specified table. If the key is not found in the table, integer value zero
15710 is returned. Otherwise the converter returns the average incoming session
15711 rate associated with the input sample in the designated table. Note that a
15712 session here refers to an incoming connection being accepted by the
15713 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
15714 keyword.
15715
15716table_trackers(<table>)
15717 Uses the string representation of the input sample to perform a look up in
15718 the specified table. If the key is not found in the table, integer value zero
15719 is returned. Otherwise the converter returns the current amount of concurrent
15720 connections tracking the same key as the input sample in the designated
15721 table. It differs from table_conn_cur in that it does not rely on any stored
15722 information but on the table's reference count (the "use" value which is
15723 returned by "show table" on the CLI). This may sometimes be more suited for
15724 layer7 tracking. It can be used to tell a server how many concurrent
15725 connections there are from a given address for example. See also the
15726 sc_trackers sample fetch keyword.
15727
Willy Tarreauffcb2e42014-07-10 16:29:08 +020015728upper
15729 Convert a string sample to upper case. This can only be placed after a string
15730 sample fetch function or after a transformation keyword returning a string
15731 type. The result is of type string.
15732
Willy Tarreau62ba9ba2020-04-23 17:54:47 +020015733url_dec([<in_form>])
15734 Takes an url-encoded string provided as input and returns the decoded version
15735 as output. The input and the output are of type string. If the <in_form>
15736 argument is set to a non-zero integer value, the input string is assumed to
15737 be part of a form or query string and the '+' character will be turned into a
15738 space (' '). Otherwise this will only happen after a question mark indicating
15739 a query string ('?').
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020015740
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015741ungrpc(<field_number>,[<field_type>])
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010015742 This extracts the protocol buffers message field in raw mode of an input binary
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010015743 sample representation of a gRPC message with <field_number> as field number
15744 (dotted notation) if <field_type> is not present, or as an integer sample if this
15745 field is present.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015746 The list of the authorized types is the following one: "int32", "int64", "uint32",
15747 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
15748 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
15749 "float" for the wire type 5. Note that "string" is considered as a length-delimited
Frédéric Lécaille93d33162019-03-06 09:35:59 +010015750 type, so it does not require any <field_type> argument to be extracted.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015751 More information may be found here about the protocol buffers message field types:
15752 https://developers.google.com/protocol-buffers/docs/encoding
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010015753
15754 Example:
15755 // with such a protocol buffer .proto file content adapted from
15756 // https://github.com/grpc/grpc/blob/master/examples/protos/route_guide.proto
15757
15758 message Point {
15759 int32 latitude = 1;
15760 int32 longitude = 2;
15761 }
15762
15763 message PPoint {
15764 Point point = 59;
15765 }
15766
15767 message Rectangle {
15768 // One corner of the rectangle.
15769 PPoint lo = 48;
15770 // The other corner of the rectangle.
15771 PPoint hi = 49;
15772 }
15773
Peter Gervaidf4c9d22020-06-11 18:05:11 +020015774 let's say a body request is made of a "Rectangle" object value (two PPoint
15775 protocol buffers messages), the four protocol buffers fields could be
15776 extracted with these "ungrpc" directives:
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010015777
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015778 req.body,ungrpc(48.59.1,int32) # "latitude" of "lo" first PPoint
15779 req.body,ungrpc(48.59.2,int32) # "longitude" of "lo" first PPoint
John Roeslerfb2fce12019-07-10 15:45:51 -050015780 req.body,ungrpc(49.59.1,int32) # "latitude" of "hi" second PPoint
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015781 req.body,ungrpc(49.59.2,int32) # "longitude" of "hi" second PPoint
15782
Peter Gervaidf4c9d22020-06-11 18:05:11 +020015783 We could also extract the intermediary 48.59 field as a binary sample as follows:
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015784
Frédéric Lécaille93d33162019-03-06 09:35:59 +010015785 req.body,ungrpc(48.59)
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010015786
Peter Gervaidf4c9d22020-06-11 18:05:11 +020015787 As a gRPC message is always made of a gRPC header followed by protocol buffers
15788 messages, in the previous example the "latitude" of "lo" first PPoint
15789 could be extracted with these equivalent directives:
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010015790
15791 req.body,ungrpc(48.59),protobuf(1,int32)
15792 req.body,ungrpc(48),protobuf(59.1,int32)
15793 req.body,ungrpc(48),protobuf(59),protobuf(1,int32)
15794
Peter Gervaidf4c9d22020-06-11 18:05:11 +020015795 Note that the first convert must be "ungrpc", the remaining ones must be
15796 "protobuf" and only the last one may have or not a second argument to
15797 interpret the previous binary sample.
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010015798
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010015799
Christopher Faulet85d79c92016-11-09 16:54:56 +010015800unset-var(<var name>)
15801 Unsets a variable if the input content is defined. The name of the variable
15802 starts with an indication about its scope. The scopes allowed are:
15803 "proc" : the variable is shared with the whole process
15804 "sess" : the variable is shared with the whole session
15805 "txn" : the variable is shared with the transaction (request and
15806 response),
15807 "req" : the variable is shared only during request processing,
15808 "res" : the variable is shared only during response processing.
15809 This prefix is followed by a name. The separator is a '.'. The name may only
15810 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
15811
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020015812utime(<format>[,<offset>])
15813 Converts an integer supposed to contain a date since epoch to a string
15814 representing this date in UTC time using a format defined by the <format>
15815 string using strftime(3). The purpose is to allow any date format to be used
15816 in logs. An optional <offset> in seconds may be applied to the input date
15817 (positive or negative). See the strftime() man page for the format supported
15818 by your operating system. See also the ltime converter.
15819
15820 Example :
15821
15822 # Emit two colons, one with the UTC time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010015823 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020015824 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
15825
Marcin Deranek9631a282018-04-16 14:30:46 +020015826word(<index>,<delimiters>[,<count>])
15827 Extracts the nth word counting from the beginning (positive index) or from
15828 the end (negative index) considering given delimiters from an input string.
15829 Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
Jerome Magnin88209322020-01-28 13:33:44 +010015830 Delimiters at the beginning or end of the input string are ignored.
Marcin Deranek9631a282018-04-16 14:30:46 +020015831 Optionally you can specify <count> of words to extract (default: 1).
15832 Value of 0 indicates extraction of all remaining words.
15833
15834 Example :
15835 str(f1_f2_f3__f5),word(4,_) # f5
15836 str(f1_f2_f3__f5),word(2,_,0) # f2_f3__f5
15837 str(f1_f2_f3__f5),word(3,_,2) # f3__f5
15838 str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
15839 str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
Jerome Magnin88209322020-01-28 13:33:44 +010015840 str(/f1/f2/f3/f4),word(1,/) # f1
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010015841
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015842wt6([<avalanche>])
15843 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
15844 hash function. Optionally, it is possible to apply a full avalanche hash
15845 function to the output if the optional <avalanche> argument equals 1. This
15846 converter uses the same functions as used by the various hash-based load
15847 balancing algorithms, so it will provide exactly the same results. It is
15848 mostly intended for debugging, but can be used as a stick-table entry to
15849 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010015850 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c",
15851 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020015852
Willy Tarreau97707872015-01-27 15:12:13 +010015853xor(<value>)
15854 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020015855 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015856 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010015857 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015858 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015859 "sess" : the variable is shared with the whole session
15860 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015861 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010015862 "req" : the variable is shared only during request processing,
15863 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020015864 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015865 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010015866
Thierry FOURNIER01e09742016-12-26 11:46:11 +010015867xxh32([<seed>])
15868 Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
15869 variant of the XXHash hash function. This hash supports a seed which defaults
15870 to zero but a different value maybe passed as the <seed> argument. This hash
15871 is known to be very good and very fast so it can be used to hash URLs and/or
15872 URL parameters for use as stick-table keys to collect statistics with a low
15873 collision rate, though care must be taken as the algorithm is not considered
15874 as cryptographically secure.
15875
15876xxh64([<seed>])
15877 Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
15878 variant of the XXHash hash function. This hash supports a seed which defaults
15879 to zero but a different value maybe passed as the <seed> argument. This hash
15880 is known to be very good and very fast so it can be used to hash URLs and/or
15881 URL parameters for use as stick-table keys to collect statistics with a low
15882 collision rate, though care must be taken as the algorithm is not considered
15883 as cryptographically secure.
15884
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015885
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200158867.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020015887--------------------------------------------
15888
15889A first set of sample fetch methods applies to internal information which does
15890not even relate to any client information. These ones are sometimes used with
15891"monitor-fail" directives to report an internal status to external watchers.
15892The sample fetch methods described in this section are usable anywhere.
15893
15894always_false : boolean
15895 Always returns the boolean "false" value. It may be used with ACLs as a
15896 temporary replacement for another one when adjusting configurations.
15897
15898always_true : boolean
15899 Always returns the boolean "true" value. It may be used with ACLs as a
15900 temporary replacement for another one when adjusting configurations.
15901
15902avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010015903 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020015904 divided by the number of active servers. The current backend is used if no
15905 backend is specified. This is very similar to "queue" except that the size of
15906 the farm is considered, in order to give a more accurate measurement of the
15907 time it may take for a new connection to be processed. The main usage is with
15908 ACL to return a sorry page to new users when it becomes certain they will get
15909 a degraded service, or to pass to the backend servers in a header so that
15910 they decide to work in degraded mode or to disable some functions to speed up
15911 the processing a bit. Note that in the event there would not be any active
15912 server anymore, twice the number of queued connections would be considered as
15913 the measured value. This is a fair estimate, as we expect one server to get
15914 back soon anyway, but we still prefer to send new traffic to another backend
15915 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
15916 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010015917
Willy Tarreau74ca5042013-06-11 23:12:07 +020015918be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020015919 Applies to the number of currently established connections on the backend,
15920 possibly including the connection being evaluated. If no backend name is
15921 specified, the current one is used. But it is also possible to check another
15922 backend. It can be used to use a specific farm when the nominal one is full.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040015923 See also the "fe_conn", "queue", "be_conn_free", and "be_sess_rate" criteria.
15924
15925be_conn_free([<backend>]) : integer
15926 Returns an integer value corresponding to the number of available connections
15927 across available servers in the backend. Queue slots are not included. Backup
15928 servers are also not included, unless all other servers are down. If no
15929 backend name is specified, the current one is used. But it is also possible
15930 to check another backend. It can be used to use a specific farm when the
Patrick Hemmer155e93e2018-06-14 18:01:35 -040015931 nominal one is full. See also the "be_conn", "connslots", and "srv_conn_free"
15932 criteria.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040015933
15934 OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0
15935 (meaning unlimited), then this fetch clearly does not make sense, in which
15936 case the value returned will be -1.
Willy Tarreau6a06a402007-07-15 20:15:28 +020015937
Willy Tarreau74ca5042013-06-11 23:12:07 +020015938be_sess_rate([<backend>]) : integer
15939 Returns an integer value corresponding to the sessions creation rate on the
15940 backend, in number of new sessions per second. This is used with ACLs to
15941 switch to an alternate backend when an expensive or fragile one reaches too
Davor Ocelice9ed2812017-12-25 17:49:28 +010015942 high a session rate, or to limit abuse of service (e.g. prevent sucking of an
Willy Tarreau74ca5042013-06-11 23:12:07 +020015943 online dictionary). It can also be useful to add this element to logs using a
15944 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015945
15946 Example :
15947 # Redirect to an error page if the dictionary is requested too often
15948 backend dynamic
15949 mode http
15950 acl being_scanned be_sess_rate gt 100
15951 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010015952
Davor Ocelice9ed2812017-12-25 17:49:28 +010015953bin(<hex>) : bin
Thierry FOURNIERcc103292015-06-06 19:30:17 +020015954 Returns a binary chain. The input is the hexadecimal representation
15955 of the string.
15956
15957bool(<bool>) : bool
15958 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
15959 'false' and '0' are the same. 'true' and '1' are the same.
15960
Willy Tarreau74ca5042013-06-11 23:12:07 +020015961connslots([<backend>]) : integer
15962 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015963 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020015964 connections on all servers and the maximum queue size. This is probably only
15965 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050015966
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080015967 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020015968 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080015969 usage; see "use_backend" keyword) can be redirected to a different backend.
15970
Willy Tarreau55165fe2009-05-10 12:02:55 +020015971 'connslots' = number of available server connection slots, + number of
15972 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080015973
Willy Tarreaua36af912009-10-10 12:02:45 +020015974 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020015975 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020015976 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020015977 you want to be able to differentiate between different backends, and their
Davor Ocelice9ed2812017-12-25 17:49:28 +010015978 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020015979 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020015980 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080015981
Willy Tarreau55165fe2009-05-10 12:02:55 +020015982 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
15983 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020015984 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020015985 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080015986
Willy Tarreau70fe9442018-11-22 16:07:39 +010015987cpu_calls : integer
15988 Returns the number of calls to the task processing the stream or current
15989 request since it was allocated. This number is reset for each new request on
15990 the same connections in case of HTTP keep-alive. This value should usually be
15991 low and stable (around 2 calls for a typically simple request) but may become
15992 high if some processing (compression, caching or analysis) is performed. This
15993 is purely for performance monitoring purposes.
15994
15995cpu_ns_avg : integer
15996 Returns the average number of nanoseconds spent in each call to the task
15997 processing the stream or current request. This number is reset for each new
15998 request on the same connections in case of HTTP keep-alive. This value
15999 indicates the overall cost of processing the request or the connection for
16000 each call. There is no good nor bad value but the time spent in a call
16001 automatically causes latency for other processing (see lat_ns_avg below),
16002 and may affect other connection's apparent response time. Certain operations
16003 like compression, complex regex matching or heavy Lua operations may directly
16004 affect this value, and having it in the logs will make it easier to spot the
16005 faulty processing that needs to be fixed to recover decent performance.
16006 Note: this value is exactly cpu_ns_tot divided by cpu_calls.
16007
16008cpu_ns_tot : integer
16009 Returns the total number of nanoseconds spent in each call to the task
16010 processing the stream or current request. This number is reset for each new
16011 request on the same connections in case of HTTP keep-alive. This value
16012 indicates the overall cost of processing the request or the connection for
16013 each call. There is no good nor bad value but the time spent in a call
16014 automatically causes latency for other processing (see lat_ns_avg below),
16015 induces CPU costs on the machine, and may affect other connection's apparent
16016 response time. Certain operations like compression, complex regex matching or
16017 heavy Lua operations may directly affect this value, and having it in the
16018 logs will make it easier to spot the faulty processing that needs to be fixed
16019 to recover decent performance. The value may be artificially high due to a
16020 high cpu_calls count, for example when processing many HTTP chunks, and for
16021 this reason it is often preferred to log cpu_ns_avg instead.
16022
Cyril Bonté6bcd1822019-11-05 23:13:59 +010016023date([<offset>],[<unit>]) : integer
Willy Tarreau6236d3a2013-07-25 14:28:25 +020016024 Returns the current date as the epoch (number of seconds since 01/01/1970).
Damien Claisseae6f1252019-10-30 15:57:28 +000016025
16026 If an offset value is specified, then it is added to the current date before
16027 returning the value. This is particularly useful to compute relative dates,
16028 as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020016029 It is useful combined with the http_date converter.
16030
Damien Claisseae6f1252019-10-30 15:57:28 +000016031 <unit> is facultative, and can be set to "s" for seconds (default behavior),
16032 "ms" for milliseconds or "us" for microseconds.
16033 If unit is set, return value is an integer reflecting either seconds,
16034 milliseconds or microseconds since epoch, plus offset.
16035 It is useful when a time resolution of less than a second is needed.
16036
Willy Tarreau276fae92013-07-25 14:36:01 +020016037 Example :
16038
16039 # set an expires header to now+1 hour in every response
16040 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020016041
Damien Claisseae6f1252019-10-30 15:57:28 +000016042 # set an expires header to now+1 hour in every response, with
16043 # millisecond granularity
16044 http-response set-header Expires %[date(3600000,ms),http_date(0,ms)]
16045
Etienne Carrierea792a0a2018-01-17 13:43:24 +010016046date_us : integer
16047 Return the microseconds part of the date (the "second" part is returned by
16048 date sample). This sample is coherent with the date sample as it is comes
16049 from the same timeval structure.
16050
Willy Tarreaud716f9b2017-10-13 11:03:15 +020016051distcc_body(<token>[,<occ>]) : binary
16052 Parses a distcc message and returns the body associated to occurrence #<occ>
16053 of the token <token>. Occurrences start at 1, and when unspecified, any may
16054 match though in practice only the first one is checked for now. This can be
16055 used to extract file names or arguments in files built using distcc through
16056 haproxy. Please refer to distcc's protocol documentation for the complete
16057 list of supported tokens.
16058
16059distcc_param(<token>[,<occ>]) : integer
16060 Parses a distcc message and returns the parameter associated to occurrence
16061 #<occ> of the token <token>. Occurrences start at 1, and when unspecified,
16062 any may match though in practice only the first one is checked for now. This
16063 can be used to extract certain information such as the protocol version, the
16064 file size or the argument in files built using distcc through haproxy.
16065 Another use case consists in waiting for the start of the preprocessed file
16066 contents before connecting to the server to avoid keeping idle connections.
16067 Please refer to distcc's protocol documentation for the complete list of
16068 supported tokens.
16069
16070 Example :
16071 # wait up to 20s for the pre-processed file to be uploaded
16072 tcp-request inspect-delay 20s
16073 tcp-request content accept if { distcc_param(DOTI) -m found }
16074 # send large files to the big farm
16075 use_backend big_farm if { distcc_param(DOTI) gt 1000000 }
16076
Willy Tarreau595ec542013-06-12 21:34:28 +020016077env(<name>) : string
16078 Returns a string containing the value of environment variable <name>. As a
16079 reminder, environment variables are per-process and are sampled when the
16080 process starts. This can be useful to pass some information to a next hop
16081 server, or with ACLs to take specific action when the process is started a
16082 certain way.
16083
16084 Examples :
16085 # Pass the Via header to next hop with the local hostname in it
16086 http-request add-header Via 1.1\ %[env(HOSTNAME)]
16087
16088 # reject cookie-less requests when the STOP environment variable is set
16089 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
16090
Willy Tarreau74ca5042013-06-11 23:12:07 +020016091fe_conn([<frontend>]) : integer
16092 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010016093 possibly including the connection being evaluated. If no frontend name is
16094 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020016095 frontend. It can be used to return a sorry page before hard-blocking, or to
16096 use a specific backend to drain new requests when the farm is considered
Davor Ocelice9ed2812017-12-25 17:49:28 +010016097 full. This is mostly used with ACLs but can also be used to pass some
Willy Tarreau74ca5042013-06-11 23:12:07 +020016098 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
16099 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020016100
Nenad Merdanovicad9a7e92016-10-03 04:57:37 +020016101fe_req_rate([<frontend>]) : integer
16102 Returns an integer value corresponding to the number of HTTP requests per
16103 second sent to a frontend. This number can differ from "fe_sess_rate" in
16104 situations where client-side keep-alive is enabled.
16105
Willy Tarreau74ca5042013-06-11 23:12:07 +020016106fe_sess_rate([<frontend>]) : integer
16107 Returns an integer value corresponding to the sessions creation rate on the
16108 frontend, in number of new sessions per second. This is used with ACLs to
16109 limit the incoming session rate to an acceptable range in order to prevent
16110 abuse of service at the earliest moment, for example when combined with other
16111 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
16112 down below the limit. It can also be useful to add this element to logs using
16113 a log-format directive. See also the "rate-limit sessions" directive for use
16114 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010016115
16116 Example :
16117 # This frontend limits incoming mails to 10/s with a max of 100
16118 # concurrent connections. We accept any connection below 10/s, and
16119 # force excess clients to wait for 100 ms. Since clients are limited to
16120 # 100 max, there cannot be more than 10 incoming mails per second.
16121 frontend mail
16122 bind :25
16123 mode tcp
16124 maxconn 100
16125 acl too_fast fe_sess_rate ge 10
16126 tcp-request inspect-delay 100ms
16127 tcp-request content accept if ! too_fast
16128 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010016129
Nenad Merdanovic807a6e72017-03-12 22:00:00 +010016130hostname : string
16131 Returns the system hostname.
16132
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020016133int(<integer>) : signed integer
16134 Returns a signed integer.
16135
Thierry FOURNIERcc103292015-06-06 19:30:17 +020016136ipv4(<ipv4>) : ipv4
16137 Returns an ipv4.
16138
16139ipv6(<ipv6>) : ipv6
16140 Returns an ipv6.
16141
Willy Tarreau70fe9442018-11-22 16:07:39 +010016142lat_ns_avg : integer
16143 Returns the average number of nanoseconds spent between the moment the task
16144 handling the stream is woken up and the moment it is effectively called. This
16145 number is reset for each new request on the same connections in case of HTTP
16146 keep-alive. This value indicates the overall latency inflicted to the current
16147 request by all other requests being processed in parallel, and is a direct
16148 indicator of perceived performance due to noisy neighbours. In order to keep
16149 the value low, it is possible to reduce the scheduler's run queue depth using
16150 "tune.runqueue-depth", to reduce the number of concurrent events processed at
16151 once using "tune.maxpollevents", to decrease the stream's nice value using
Willy Tarreaue7723bd2020-06-24 11:11:02 +020016152 the "nice" option on the "bind" lines or in the frontend, to enable low
16153 latency scheduling using "tune.sched.low-latency", or to look for other heavy
16154 requests in logs (those exhibiting large values of "cpu_ns_avg"), whose
16155 processing needs to be adjusted or fixed. Compression of large buffers could
16156 be a culprit, like heavy regex or long lists of regex. Note: this value is
16157 exactly lat_ns_tot divided by cpu_calls.
Willy Tarreau70fe9442018-11-22 16:07:39 +010016158
16159lat_ns_tot : integer
16160 Returns the total number of nanoseconds spent between the moment the task
16161 handling the stream is woken up and the moment it is effectively called. This
16162 number is reset for each new request on the same connections in case of HTTP
16163 keep-alive. This value indicates the overall latency inflicted to the current
16164 request by all other requests being processed in parallel, and is a direct
16165 indicator of perceived performance due to noisy neighbours. In order to keep
16166 the value low, it is possible to reduce the scheduler's run queue depth using
16167 "tune.runqueue-depth", to reduce the number of concurrent events processed at
16168 once using "tune.maxpollevents", to decrease the stream's nice value using
Willy Tarreaue7723bd2020-06-24 11:11:02 +020016169 the "nice" option on the "bind" lines or in the frontend, to enable low
16170 latency scheduling using "tune.sched.low-latency", or to look for other heavy
16171 requests in logs (those exhibiting large values of "cpu_ns_avg"), whose
16172 processing needs to be adjusted or fixed. Compression of large buffers could
16173 be a culprit, like heavy regex or long lists of regex. Note: while it
Willy Tarreau70fe9442018-11-22 16:07:39 +010016174 may intuitively seem that the total latency adds to a transfer time, it is
16175 almost never true because while a task waits for the CPU, network buffers
16176 continue to fill up and the next call will process more at once. The value
16177 may be artificially high due to a high cpu_calls count, for example when
16178 processing many HTTP chunks, and for this reason it is often preferred to log
16179 lat_ns_avg instead, which is a more relevant performance indicator.
16180
Thierry FOURNIERcc103292015-06-06 19:30:17 +020016181meth(<method>) : method
16182 Returns a method.
16183
Willy Tarreau0f30d262014-11-24 16:02:05 +010016184nbproc : integer
16185 Returns an integer value corresponding to the number of processes that were
16186 started (it equals the global "nbproc" setting). This is useful for logging
16187 and debugging purposes.
16188
Willy Tarreau74ca5042013-06-11 23:12:07 +020016189nbsrv([<backend>]) : integer
16190 Returns an integer value corresponding to the number of usable servers of
16191 either the current backend or the named backend. This is mostly used with
16192 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010016193 switch to an alternate backend when the number of servers is too low to
16194 to handle some load. It is useful to report a failure when combined with
16195 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010016196
Patrick Hemmerfabb24f2018-08-13 14:07:57 -040016197prio_class : integer
16198 Returns the priority class of the current session for http mode or connection
16199 for tcp mode. The value will be that set by the last call to "http-request
16200 set-priority-class" or "tcp-request content set-priority-class".
16201
16202prio_offset : integer
16203 Returns the priority offset of the current session for http mode or
16204 connection for tcp mode. The value will be that set by the last call to
16205 "http-request set-priority-offset" or "tcp-request content
16206 set-priority-offset".
16207
Willy Tarreau0f30d262014-11-24 16:02:05 +010016208proc : integer
16209 Returns an integer value corresponding to the position of the process calling
16210 the function, between 1 and global.nbproc. This is useful for logging and
16211 debugging purposes.
16212
Willy Tarreau74ca5042013-06-11 23:12:07 +020016213queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010016214 Returns the total number of queued connections of the designated backend,
16215 including all the connections in server queues. If no backend name is
16216 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020016217 one. This is useful with ACLs or to pass statistics to backend servers. This
16218 can be used to take actions when queuing goes above a known level, generally
16219 indicating a surge of traffic or a massive slowdown on the servers. One
16220 possible action could be to reject new users but still accept old ones. See
16221 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
16222
Willy Tarreau84310e22014-02-14 11:59:04 +010016223rand([<range>]) : integer
16224 Returns a random integer value within a range of <range> possible values,
16225 starting at zero. If the range is not specified, it defaults to 2^32, which
16226 gives numbers between 0 and 4294967295. It can be useful to pass some values
16227 needed to take some routing decisions for example, or just for debugging
16228 purposes. This random must not be used for security purposes.
16229
Luca Schimweg8a694b82019-09-10 15:42:52 +020016230uuid([<version>]) : string
16231 Returns a UUID following the RFC4122 standard. If the version is not
16232 specified, a UUID version 4 (fully random) is returned.
16233 Currently, only version 4 is supported.
16234
Willy Tarreau74ca5042013-06-11 23:12:07 +020016235srv_conn([<backend>/]<server>) : integer
16236 Returns an integer value corresponding to the number of currently established
16237 connections on the designated server, possibly including the connection being
16238 evaluated. If <backend> is omitted, then the server is looked up in the
16239 current backend. It can be used to use a specific farm when one server is
16240 full, or to inform the server about our view of the number of active
Patrick Hemmer155e93e2018-06-14 18:01:35 -040016241 connections with it. See also the "fe_conn", "be_conn", "queue", and
16242 "srv_conn_free" fetch methods.
16243
16244srv_conn_free([<backend>/]<server>) : integer
16245 Returns an integer value corresponding to the number of available connections
16246 on the designated server, possibly including the connection being evaluated.
16247 The value does not include queue slots. If <backend> is omitted, then the
16248 server is looked up in the current backend. It can be used to use a specific
16249 farm when one server is full, or to inform the server about our view of the
16250 number of active connections with it. See also the "be_conn_free" and
16251 "srv_conn" fetch methods.
16252
16253 OTHER CAVEATS AND NOTES: If the server maxconn is 0, then this fetch clearly
16254 does not make sense, in which case the value returned will be -1.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016255
16256srv_is_up([<backend>/]<server>) : boolean
16257 Returns true when the designated server is UP, and false when it is either
16258 DOWN or in maintenance mode. If <backend> is omitted, then the server is
16259 looked up in the current backend. It is mainly used to take action based on
Davor Ocelice9ed2812017-12-25 17:49:28 +010016260 an external status reported via a health check (e.g. a geographical site's
Willy Tarreau74ca5042013-06-11 23:12:07 +020016261 availability). Another possible use which is more of a hack consists in
16262 using dummy servers as boolean variables that can be enabled or disabled from
16263 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
16264
Willy Tarreauff2b7af2017-10-13 11:46:26 +020016265srv_queue([<backend>/]<server>) : integer
16266 Returns an integer value corresponding to the number of connections currently
16267 pending in the designated server's queue. If <backend> is omitted, then the
16268 server is looked up in the current backend. It can sometimes be used together
16269 with the "use-server" directive to force to use a known faster server when it
16270 is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample
16271 fetch methods.
16272
Willy Tarreau74ca5042013-06-11 23:12:07 +020016273srv_sess_rate([<backend>/]<server>) : integer
16274 Returns an integer corresponding to the sessions creation rate on the
16275 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016276 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020016277 used with ACLs but can make sense with logs too. This is used to switch to an
16278 alternate backend when an expensive or fragile one reaches too high a session
Davor Ocelice9ed2812017-12-25 17:49:28 +010016279 rate, or to limit abuse of service (e.g. prevent latent requests from
Willy Tarreau74ca5042013-06-11 23:12:07 +020016280 overloading servers).
16281
16282 Example :
16283 # Redirect to a separate back
16284 acl srv1_full srv_sess_rate(be1/srv1) gt 50
16285 acl srv2_full srv_sess_rate(be1/srv2) gt 50
16286 use_backend be2 if srv1_full or srv2_full
16287
Christopher Faulet1bea8652020-07-10 16:03:45 +020016288srv_iweight([<backend>/]<server>): integer
16289 Returns an integer corresponding to the server's initial weight. If <backend>
16290 is omitted, then the server is looked up in the current backend. See also
16291 "srv_weight" and "srv_uweight".
16292
16293srv_uweight([<backend>/]<server>): integer
16294 Returns an integer corresponding to the user visible server's weight. If
16295 <backend> is omitted, then the server is looked up in the current
16296 backend. See also "srv_weight" and "srv_iweight".
16297
16298srv_weight([<backend>/]<server>): integer
16299 Returns an integer corresponding to the current (or effective) server's
16300 weight. If <backend> is omitted, then the server is looked up in the current
16301 backend. See also "srv_iweight" and "srv_uweight".
16302
Willy Tarreau0f30d262014-11-24 16:02:05 +010016303stopping : boolean
16304 Returns TRUE if the process calling the function is currently stopping. This
16305 can be useful for logging, or for relaxing certain checks or helping close
16306 certain connections upon graceful shutdown.
16307
Thierry FOURNIERcc103292015-06-06 19:30:17 +020016308str(<string>) : string
16309 Returns a string.
16310
Willy Tarreau74ca5042013-06-11 23:12:07 +020016311table_avl([<table>]) : integer
16312 Returns the total number of available entries in the current proxy's
16313 stick-table or in the designated stick-table. See also table_cnt.
16314
16315table_cnt([<table>]) : integer
16316 Returns the total number of entries currently in use in the current proxy's
16317 stick-table or in the designated stick-table. See also src_conn_cnt and
16318 table_avl for other entry counting methods.
16319
Christopher Faulet34adb2a2017-11-21 21:45:38 +010016320thread : integer
16321 Returns an integer value corresponding to the position of the thread calling
16322 the function, between 0 and (global.nbthread-1). This is useful for logging
16323 and debugging purposes.
16324
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016325var(<var-name>) : undefined
16326 Returns a variable with the stored type. If the variable is not set, the
Daniel Schneller0b547052016-03-21 20:46:57 +010016327 sample fetch fails. The name of the variable starts with an indication
16328 about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010016329 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010016330 "sess" : the variable is shared with the whole session
16331 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016332 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010016333 "req" : the variable is shared only during request processing,
16334 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016335 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010016336 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020016337
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200163387.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020016339----------------------------------
16340
16341The layer 4 usually describes just the transport layer which in haproxy is
16342closest to the connection, where no content is yet made available. The fetch
16343methods described here are usable as low as the "tcp-request connection" rule
16344sets unless they require some future information. Those generally include
16345TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016346the incoming connection. For retrieving a value from a sticky counters, the
16347counter number can be explicitly set as 0, 1, or 2 using the pre-defined
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020016348"sc0_", "sc1_", or "sc2_" prefix. These three pre-defined prefixes can only be
16349used if MAX_SESS_STKCTR value does not exceed 3, otherwise the counter number
16350can be specified as the first integer argument when using the "sc_" prefix.
16351Starting from "sc_0" to "sc_N" where N is (MAX_SESS_STKCTR-1). An optional
16352table may be specified with the "sc*" form, in which case the currently
16353tracked key will be looked up into this alternate table instead of the table
16354currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016355
Jérôme Magnin35e53a62019-01-16 14:38:37 +010016356bc_http_major : integer
Jérôme Magnin86577422018-12-07 09:03:11 +010016357 Returns the backend connection's HTTP major version encoding, which may be 1
16358 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
16359 encoding and not the version present in the request header.
16360
Willy Tarreau74ca5042013-06-11 23:12:07 +020016361be_id : integer
16362 Returns an integer containing the current backend's id. It can be used in
Christopher Fauletd1b44642020-04-30 09:51:15 +020016363 frontends with responses to check which backend processed the request. It can
16364 also be used in a tcp-check or an http-check ruleset.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016365
Marcin Deranekd2471c22016-12-12 14:08:05 +010016366be_name : string
16367 Returns a string containing the current backend's name. It can be used in
Christopher Fauletd1b44642020-04-30 09:51:15 +020016368 frontends with responses to check which backend processed the request. It can
16369 also be used in a tcp-check or an http-check ruleset.
Marcin Deranekd2471c22016-12-12 14:08:05 +010016370
Willy Tarreau74ca5042013-06-11 23:12:07 +020016371dst : ip
16372 This is the destination IPv4 address of the connection on the client side,
16373 which is the address the client connected to. It can be useful when running
16374 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
16375 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
Willy Tarreau64ded3d2019-01-23 10:02:15 +010016376 RFC 4291. When the incoming connection passed through address translation or
16377 redirection involving connection tracking, the original destination address
16378 before the redirection will be reported. On Linux systems, the source and
16379 destination may seldom appear reversed if the nf_conntrack_tcp_loose sysctl
16380 is set, because a late response may reopen a timed out connection and switch
16381 what is believed to be the source and the destination.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016382
16383dst_conn : integer
16384 Returns an integer value corresponding to the number of currently established
16385 connections on the same socket including the one being evaluated. It is
16386 normally used with ACLs but can as well be used to pass the information to
16387 servers in an HTTP header or in logs. It can be used to either return a sorry
16388 page before hard-blocking, or to use a specific backend to drain new requests
16389 when the socket is considered saturated. This offers the ability to assign
16390 different limits to different listening ports or addresses. See also the
16391 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016392
Willy Tarreau16e01562016-08-09 16:46:18 +020016393dst_is_local : boolean
16394 Returns true if the destination address of the incoming connection is local
16395 to the system, or false if the address doesn't exist on the system, meaning
16396 that it was intercepted in transparent mode. It can be useful to apply
16397 certain rules by default to forwarded traffic and other rules to the traffic
Davor Ocelice9ed2812017-12-25 17:49:28 +010016398 targeting the real address of the machine. For example the stats page could
Willy Tarreau16e01562016-08-09 16:46:18 +020016399 be delivered only on this address, or SSH access could be locally redirected.
16400 Please note that the check involves a few system calls, so it's better to do
16401 it only once per connection.
16402
Willy Tarreau74ca5042013-06-11 23:12:07 +020016403dst_port : integer
16404 Returns an integer value corresponding to the destination TCP port of the
16405 connection on the client side, which is the port the client connected to.
16406 This might be used when running in transparent mode, when assigning dynamic
16407 ports to some clients for a whole application session, to stick all users to
16408 a same server, or to pass the destination port information to a server using
16409 an HTTP header.
16410
Willy Tarreau60ca10a2017-08-18 15:26:54 +020016411fc_http_major : integer
16412 Reports the front connection's HTTP major version encoding, which may be 1
16413 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
16414 encoding and not on the version present in the request header.
16415
Geoff Simmons7185b782019-08-27 18:31:16 +020016416fc_pp_authority : string
16417 Returns the authority TLV sent by the client in the PROXY protocol header,
16418 if any.
16419
Tim Duesterhusd1b15b62020-03-13 12:34:23 +010016420fc_pp_unique_id : string
16421 Returns the unique ID TLV sent by the client in the PROXY protocol header,
16422 if any.
16423
Emeric Brun4f603012017-01-05 15:11:44 +010016424fc_rcvd_proxy : boolean
16425 Returns true if the client initiated the connection with a PROXY protocol
16426 header.
16427
Thierry Fournier / OZON.IO6310bef2016-07-24 20:16:50 +020016428fc_rtt(<unit>) : integer
16429 Returns the Round Trip Time (RTT) measured by the kernel for the client
16430 connection. <unit> is facultative, by default the unit is milliseconds. <unit>
16431 can be set to "ms" for milliseconds or "us" for microseconds. If the server
16432 connection is not established, if the connection is not TCP or if the
16433 operating system does not support TCP_INFO, for example Linux kernels before
16434 2.4, the sample fetch fails.
16435
16436fc_rttvar(<unit>) : integer
16437 Returns the Round Trip Time (RTT) variance measured by the kernel for the
16438 client connection. <unit> is facultative, by default the unit is milliseconds.
16439 <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the
16440 server connection is not established, if the connection is not TCP or if the
16441 operating system does not support TCP_INFO, for example Linux kernels before
16442 2.4, the sample fetch fails.
16443
Christopher Fauletba0c53e2019-10-17 14:40:48 +020016444fc_unacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070016445 Returns the unacked counter measured by the kernel for the client connection.
16446 If the server connection is not established, if the connection is not TCP or
16447 if the operating system does not support TCP_INFO, for example Linux kernels
16448 before 2.4, the sample fetch fails.
16449
Christopher Fauletba0c53e2019-10-17 14:40:48 +020016450fc_sacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070016451 Returns the sacked counter measured by the kernel for the client connection.
16452 If the server connection is not established, if the connection is not TCP or
16453 if the operating system does not support TCP_INFO, for example Linux kernels
16454 before 2.4, the sample fetch fails.
16455
Christopher Fauletba0c53e2019-10-17 14:40:48 +020016456fc_retrans : integer
Joe Williams30fcd392016-08-10 07:06:44 -070016457 Returns the retransmits counter measured by the kernel for the client
16458 connection. If the server connection is not established, if the connection is
16459 not TCP or if the operating system does not support TCP_INFO, for example
16460 Linux kernels before 2.4, the sample fetch fails.
16461
Christopher Fauletba0c53e2019-10-17 14:40:48 +020016462fc_fackets : integer
Joe Williams30fcd392016-08-10 07:06:44 -070016463 Returns the fack counter measured by the kernel for the client
16464 connection. If the server connection is not established, if the connection is
16465 not TCP or if the operating system does not support TCP_INFO, for example
16466 Linux kernels before 2.4, the sample fetch fails.
16467
Christopher Fauletba0c53e2019-10-17 14:40:48 +020016468fc_lost : integer
Joe Williams30fcd392016-08-10 07:06:44 -070016469 Returns the lost counter measured by the kernel for the client
16470 connection. If the server connection is not established, if the connection is
16471 not TCP or if the operating system does not support TCP_INFO, for example
16472 Linux kernels before 2.4, the sample fetch fails.
16473
Christopher Fauletba0c53e2019-10-17 14:40:48 +020016474fc_reordering : integer
Joe Williams30fcd392016-08-10 07:06:44 -070016475 Returns the reordering counter measured by the kernel for the client
16476 connection. If the server connection is not established, if the connection is
16477 not TCP or if the operating system does not support TCP_INFO, for example
16478 Linux kernels before 2.4, the sample fetch fails.
16479
Marcin Deranek9a66dfb2018-04-13 14:37:50 +020016480fe_defbe : string
16481 Returns a string containing the frontend's default backend name. It can be
16482 used in frontends to check which backend will handle requests by default.
16483
Willy Tarreau74ca5042013-06-11 23:12:07 +020016484fe_id : integer
16485 Returns an integer containing the current frontend's id. It can be used in
Marcin Deranek6e413ed2016-12-13 12:40:01 +010016486 backends to check from which frontend it was called, or to stick all users
Willy Tarreau74ca5042013-06-11 23:12:07 +020016487 coming via a same frontend to the same server.
16488
Marcin Deranekd2471c22016-12-12 14:08:05 +010016489fe_name : string
16490 Returns a string containing the current frontend's name. It can be used in
16491 backends to check from which frontend it was called, or to stick all users
16492 coming via a same frontend to the same server.
16493
Cyril Bonté62ba8702014-04-22 23:52:25 +020016494sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016495sc0_bytes_in_rate([<table>]) : integer
16496sc1_bytes_in_rate([<table>]) : integer
16497sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016498 Returns the average client-to-server bytes rate from the currently tracked
16499 counters, measured in amount of bytes over the period configured in the
16500 table. See also src_bytes_in_rate.
16501
Cyril Bonté62ba8702014-04-22 23:52:25 +020016502sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016503sc0_bytes_out_rate([<table>]) : integer
16504sc1_bytes_out_rate([<table>]) : integer
16505sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016506 Returns the average server-to-client bytes rate from the currently tracked
16507 counters, measured in amount of bytes over the period configured in the
16508 table. See also src_bytes_out_rate.
16509
Cyril Bonté62ba8702014-04-22 23:52:25 +020016510sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016511sc0_clr_gpc0([<table>]) : integer
16512sc1_clr_gpc0([<table>]) : integer
16513sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020016514 Clears the first General Purpose Counter associated to the currently tracked
16515 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010016516 stored value is zero, so first invocation will always return zero. This is
16517 typically used as a second ACL in an expression in order to mark a connection
16518 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020016519
Jarno Huuskonen676f6222017-03-30 09:19:45 +030016520 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020016521 # block if 5 consecutive requests continue to come faster than 10 sess
16522 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020016523 acl abuse sc0_http_req_rate gt 10
16524 acl kill sc0_inc_gpc0 gt 5
16525 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020016526 tcp-request connection accept if !abuse save
16527 tcp-request connection reject if abuse kill
16528
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016529sc_clr_gpc1(<ctr>[,<table>]) : integer
16530sc0_clr_gpc1([<table>]) : integer
16531sc1_clr_gpc1([<table>]) : integer
16532sc2_clr_gpc1([<table>]) : integer
16533 Clears the second General Purpose Counter associated to the currently tracked
16534 counters, and returns its previous value. Before the first invocation, the
16535 stored value is zero, so first invocation will always return zero. This is
16536 typically used as a second ACL in an expression in order to mark a connection
16537 when a first ACL was verified.
16538
Cyril Bonté62ba8702014-04-22 23:52:25 +020016539sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016540sc0_conn_cnt([<table>]) : integer
16541sc1_conn_cnt([<table>]) : integer
16542sc2_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016543 Returns the cumulative number of incoming connections from currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020016544 counters. See also src_conn_cnt.
16545
Cyril Bonté62ba8702014-04-22 23:52:25 +020016546sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016547sc0_conn_cur([<table>]) : integer
16548sc1_conn_cur([<table>]) : integer
16549sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016550 Returns the current amount of concurrent connections tracking the same
16551 tracked counters. This number is automatically incremented when tracking
16552 begins and decremented when tracking stops. See also src_conn_cur.
16553
Cyril Bonté62ba8702014-04-22 23:52:25 +020016554sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016555sc0_conn_rate([<table>]) : integer
16556sc1_conn_rate([<table>]) : integer
16557sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016558 Returns the average connection rate from the currently tracked counters,
16559 measured in amount of connections over the period configured in the table.
16560 See also src_conn_rate.
16561
Cyril Bonté62ba8702014-04-22 23:52:25 +020016562sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016563sc0_get_gpc0([<table>]) : integer
16564sc1_get_gpc0([<table>]) : integer
16565sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016566 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016567 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020016568
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016569sc_get_gpc1(<ctr>[,<table>]) : integer
16570sc0_get_gpc1([<table>]) : integer
16571sc1_get_gpc1([<table>]) : integer
16572sc2_get_gpc1([<table>]) : integer
16573 Returns the value of the second General Purpose Counter associated to the
16574 currently tracked counters. See also src_get_gpc1 and sc/sc0/sc1/sc2_inc_gpc1.
16575
Thierry FOURNIER236657b2015-08-19 08:25:14 +020016576sc_get_gpt0(<ctr>[,<table>]) : integer
16577sc0_get_gpt0([<table>]) : integer
16578sc1_get_gpt0([<table>]) : integer
16579sc2_get_gpt0([<table>]) : integer
16580 Returns the value of the first General Purpose Tag associated to the
16581 currently tracked counters. See also src_get_gpt0.
16582
Cyril Bonté62ba8702014-04-22 23:52:25 +020016583sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016584sc0_gpc0_rate([<table>]) : integer
16585sc1_gpc0_rate([<table>]) : integer
16586sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020016587 Returns the average increment rate of the first General Purpose Counter
16588 associated to the currently tracked counters. It reports the frequency
16589 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016590 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
16591 that the "gpc0_rate" counter must be stored in the stick-table for a value to
16592 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020016593
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016594sc_gpc1_rate(<ctr>[,<table>]) : integer
16595sc0_gpc1_rate([<table>]) : integer
16596sc1_gpc1_rate([<table>]) : integer
16597sc2_gpc1_rate([<table>]) : integer
16598 Returns the average increment rate of the second General Purpose Counter
16599 associated to the currently tracked counters. It reports the frequency
16600 which the gpc1 counter was incremented over the configured period. See also
16601 src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
16602 that the "gpc1_rate" counter must be stored in the stick-table for a value to
16603 be returned, as "gpc1" only holds the event count.
16604
Cyril Bonté62ba8702014-04-22 23:52:25 +020016605sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016606sc0_http_err_cnt([<table>]) : integer
16607sc1_http_err_cnt([<table>]) : integer
16608sc2_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016609 Returns the cumulative number of HTTP errors from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020016610 counters. This includes the both request errors and 4xx error responses.
16611 See also src_http_err_cnt.
16612
Cyril Bonté62ba8702014-04-22 23:52:25 +020016613sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016614sc0_http_err_rate([<table>]) : integer
16615sc1_http_err_rate([<table>]) : integer
16616sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016617 Returns the average rate of HTTP errors from the currently tracked counters,
16618 measured in amount of errors over the period configured in the table. This
16619 includes the both request errors and 4xx error responses. See also
16620 src_http_err_rate.
16621
Cyril Bonté62ba8702014-04-22 23:52:25 +020016622sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016623sc0_http_req_cnt([<table>]) : integer
16624sc1_http_req_cnt([<table>]) : integer
16625sc2_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016626 Returns the cumulative number of HTTP requests from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020016627 counters. This includes every started request, valid or not. See also
16628 src_http_req_cnt.
16629
Cyril Bonté62ba8702014-04-22 23:52:25 +020016630sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016631sc0_http_req_rate([<table>]) : integer
16632sc1_http_req_rate([<table>]) : integer
16633sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016634 Returns the average rate of HTTP requests from the currently tracked
16635 counters, measured in amount of requests over the period configured in
16636 the table. This includes every started request, valid or not. See also
16637 src_http_req_rate.
16638
Cyril Bonté62ba8702014-04-22 23:52:25 +020016639sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016640sc0_inc_gpc0([<table>]) : integer
16641sc1_inc_gpc0([<table>]) : integer
16642sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016643 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010016644 tracked counters, and returns its new value. Before the first invocation,
16645 the stored value is zero, so first invocation will increase it to 1 and will
16646 return 1. This is typically used as a second ACL in an expression in order
16647 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020016648
Jarno Huuskonen676f6222017-03-30 09:19:45 +030016649 Example:
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020016650 acl abuse sc0_http_req_rate gt 10
16651 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020016652 tcp-request connection reject if abuse kill
16653
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016654sc_inc_gpc1(<ctr>[,<table>]) : integer
16655sc0_inc_gpc1([<table>]) : integer
16656sc1_inc_gpc1([<table>]) : integer
16657sc2_inc_gpc1([<table>]) : integer
16658 Increments the second General Purpose Counter associated to the currently
16659 tracked counters, and returns its new value. Before the first invocation,
16660 the stored value is zero, so first invocation will increase it to 1 and will
16661 return 1. This is typically used as a second ACL in an expression in order
16662 to mark a connection when a first ACL was verified.
16663
Cyril Bonté62ba8702014-04-22 23:52:25 +020016664sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016665sc0_kbytes_in([<table>]) : integer
16666sc1_kbytes_in([<table>]) : integer
16667sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020016668 Returns the total amount of client-to-server data from the currently tracked
16669 counters, measured in kilobytes. The test is currently performed on 32-bit
16670 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020016671
Cyril Bonté62ba8702014-04-22 23:52:25 +020016672sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016673sc0_kbytes_out([<table>]) : integer
16674sc1_kbytes_out([<table>]) : integer
16675sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020016676 Returns the total amount of server-to-client data from the currently tracked
16677 counters, measured in kilobytes. The test is currently performed on 32-bit
16678 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020016679
Cyril Bonté62ba8702014-04-22 23:52:25 +020016680sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016681sc0_sess_cnt([<table>]) : integer
16682sc1_sess_cnt([<table>]) : integer
16683sc2_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016684 Returns the cumulative number of incoming connections that were transformed
Willy Tarreaue9656522010-08-17 15:40:09 +020016685 into sessions, which means that they were accepted by a "tcp-request
16686 connection" rule, from the currently tracked counters. A backend may count
16687 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016688 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020016689 with the client. See also src_sess_cnt.
16690
Cyril Bonté62ba8702014-04-22 23:52:25 +020016691sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016692sc0_sess_rate([<table>]) : integer
16693sc1_sess_rate([<table>]) : integer
16694sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020016695 Returns the average session rate from the currently tracked counters,
16696 measured in amount of sessions over the period configured in the table. A
16697 session is a connection that got past the early "tcp-request connection"
16698 rules. A backend may count more sessions than connections because each
16699 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040016700 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020016701
Cyril Bonté62ba8702014-04-22 23:52:25 +020016702sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020016703sc0_tracked([<table>]) : boolean
16704sc1_tracked([<table>]) : boolean
16705sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020016706 Returns true if the designated session counter is currently being tracked by
16707 the current session. This can be useful when deciding whether or not we want
16708 to set some values in a header passed to the server.
16709
Cyril Bonté62ba8702014-04-22 23:52:25 +020016710sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020016711sc0_trackers([<table>]) : integer
16712sc1_trackers([<table>]) : integer
16713sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010016714 Returns the current amount of concurrent connections tracking the same
16715 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020016716 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010016717 that it does not rely on any stored information but on the table's reference
16718 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020016719 may sometimes be more suited for layer7 tracking. It can be used to tell a
16720 server how many concurrent connections there are from a given address for
16721 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010016722
Willy Tarreau74ca5042013-06-11 23:12:07 +020016723so_id : integer
16724 Returns an integer containing the current listening socket's id. It is useful
16725 in frontends involving many "bind" lines, or to stick all users coming via a
16726 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016727
Jerome Magnineb421b22020-03-27 22:08:40 +010016728so_name : string
16729 Returns a string containing the current listening socket's name, as defined
16730 with name on a "bind" line. It can serve the same purposes as so_id but with
16731 strings instead of integers.
16732
Willy Tarreau74ca5042013-06-11 23:12:07 +020016733src : ip
Davor Ocelice9ed2812017-12-25 17:49:28 +010016734 This is the source IPv4 address of the client of the session. It is of type
Willy Tarreau74ca5042013-06-11 23:12:07 +020016735 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
16736 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
16737 TCP-level source address which is used, and not the address of a client
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010016738 behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind
16739 directive is used, it can be the address of a client behind another
16740 PROXY-protocol compatible component for all rule sets except
Willy Tarreau64ded3d2019-01-23 10:02:15 +010016741 "tcp-request connection" which sees the real address. When the incoming
16742 connection passed through address translation or redirection involving
16743 connection tracking, the original destination address before the redirection
16744 will be reported. On Linux systems, the source and destination may seldom
16745 appear reversed if the nf_conntrack_tcp_loose sysctl is set, because a late
16746 response may reopen a timed out connection and switch what is believed to be
16747 the source and the destination.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016748
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010016749 Example:
16750 # add an HTTP header in requests with the originating address' country
16751 http-request set-header X-Country %[src,map_ip(geoip.lst)]
16752
Willy Tarreau74ca5042013-06-11 23:12:07 +020016753src_bytes_in_rate([<table>]) : integer
16754 Returns the average bytes rate from the incoming connection's source address
16755 in the current proxy's stick-table or in the designated stick-table, measured
16756 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016757 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016758
Willy Tarreau74ca5042013-06-11 23:12:07 +020016759src_bytes_out_rate([<table>]) : integer
16760 Returns the average bytes rate to the incoming connection's source address in
16761 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020016762 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016763 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016764
Willy Tarreau74ca5042013-06-11 23:12:07 +020016765src_clr_gpc0([<table>]) : integer
16766 Clears the first General Purpose Counter associated to the incoming
16767 connection's source address in the current proxy's stick-table or in the
16768 designated stick-table, and returns its previous value. If the address is not
16769 found, an entry is created and 0 is returned. This is typically used as a
16770 second ACL in an expression in order to mark a connection when a first ACL
16771 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020016772
Jarno Huuskonen676f6222017-03-30 09:19:45 +030016773 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020016774 # block if 5 consecutive requests continue to come faster than 10 sess
16775 # per second, and reset the counter as soon as the traffic slows down.
16776 acl abuse src_http_req_rate gt 10
16777 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010016778 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020016779 tcp-request connection accept if !abuse save
16780 tcp-request connection reject if abuse kill
16781
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016782src_clr_gpc1([<table>]) : integer
16783 Clears the second General Purpose Counter associated to the incoming
16784 connection's source address in the current proxy's stick-table or in the
16785 designated stick-table, and returns its previous value. If the address is not
16786 found, an entry is created and 0 is returned. This is typically used as a
16787 second ACL in an expression in order to mark a connection when a first ACL
16788 was verified.
16789
Willy Tarreau74ca5042013-06-11 23:12:07 +020016790src_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016791 Returns the cumulative number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020016792 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020016793 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016794 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016795
Willy Tarreau74ca5042013-06-11 23:12:07 +020016796src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020016797 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020016798 current incoming connection's source address in the current proxy's
16799 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016800 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016801
Willy Tarreau74ca5042013-06-11 23:12:07 +020016802src_conn_rate([<table>]) : integer
16803 Returns the average connection rate from the incoming connection's source
16804 address in the current proxy's stick-table or in the designated stick-table,
16805 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016806 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016807
Willy Tarreau74ca5042013-06-11 23:12:07 +020016808src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020016809 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020016810 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020016811 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016812 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016813
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016814src_get_gpc1([<table>]) : integer
16815 Returns the value of the second General Purpose Counter associated to the
16816 incoming connection's source address in the current proxy's stick-table or in
16817 the designated stick-table. If the address is not found, zero is returned.
16818 See also sc/sc0/sc1/sc2_get_gpc1 and src_inc_gpc1.
16819
Thierry FOURNIER236657b2015-08-19 08:25:14 +020016820src_get_gpt0([<table>]) : integer
16821 Returns the value of the first General Purpose Tag associated to the
16822 incoming connection's source address in the current proxy's stick-table or in
16823 the designated stick-table. If the address is not found, zero is returned.
16824 See also sc/sc0/sc1/sc2_get_gpt0.
16825
Willy Tarreau74ca5042013-06-11 23:12:07 +020016826src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020016827 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020016828 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020016829 stick-table or in the designated stick-table. It reports the frequency
16830 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016831 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
16832 that the "gpc0_rate" counter must be stored in the stick-table for a value to
16833 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020016834
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016835src_gpc1_rate([<table>]) : integer
16836 Returns the average increment rate of the second General Purpose Counter
16837 associated to the incoming connection's source address in the current proxy's
16838 stick-table or in the designated stick-table. It reports the frequency
16839 which the gpc1 counter was incremented over the configured period. See also
16840 sc/sc0/sc1/sc2_gpc1_rate, src_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
16841 that the "gpc1_rate" counter must be stored in the stick-table for a value to
16842 be returned, as "gpc1" only holds the event count.
16843
Willy Tarreau74ca5042013-06-11 23:12:07 +020016844src_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016845 Returns the cumulative number of HTTP errors from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020016846 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020016847 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016848 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020016849 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016850
Willy Tarreau74ca5042013-06-11 23:12:07 +020016851src_http_err_rate([<table>]) : integer
16852 Returns the average rate of HTTP errors from the incoming connection's source
16853 address in the current proxy's stick-table or in the designated stick-table,
16854 measured in amount of errors over the period configured in the table. This
16855 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016856 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016857
Willy Tarreau74ca5042013-06-11 23:12:07 +020016858src_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016859 Returns the cumulative number of HTTP requests from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020016860 source address in the current proxy's stick-table or in the designated stick-
16861 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016862 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016863
Willy Tarreau74ca5042013-06-11 23:12:07 +020016864src_http_req_rate([<table>]) : integer
16865 Returns the average rate of HTTP requests from the incoming connection's
16866 source address in the current proxy's stick-table or in the designated stick-
16867 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020016868 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016869 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016870
Willy Tarreau74ca5042013-06-11 23:12:07 +020016871src_inc_gpc0([<table>]) : integer
16872 Increments the first General Purpose Counter associated to the incoming
16873 connection's source address in the current proxy's stick-table or in the
16874 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020016875 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016876 This is typically used as a second ACL in an expression in order to mark a
16877 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020016878
Jarno Huuskonen676f6222017-03-30 09:19:45 +030016879 Example:
Willy Tarreauc9705a12010-07-27 20:05:50 +020016880 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010016881 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020016882 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020016883
Frédéric Lécaille6778b272018-01-29 15:22:53 +010016884src_inc_gpc1([<table>]) : integer
16885 Increments the second General Purpose Counter associated to the incoming
16886 connection's source address in the current proxy's stick-table or in the
16887 designated stick-table, and returns its new value. If the address is not
16888 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc1.
16889 This is typically used as a second ACL in an expression in order to mark a
16890 connection when a first ACL was verified.
16891
Willy Tarreau16e01562016-08-09 16:46:18 +020016892src_is_local : boolean
16893 Returns true if the source address of the incoming connection is local to the
16894 system, or false if the address doesn't exist on the system, meaning that it
16895 comes from a remote machine. Note that UNIX addresses are considered local.
16896 It can be useful to apply certain access restrictions based on where the
Davor Ocelice9ed2812017-12-25 17:49:28 +010016897 client comes from (e.g. require auth or https for remote machines). Please
Willy Tarreau16e01562016-08-09 16:46:18 +020016898 note that the check involves a few system calls, so it's better to do it only
16899 once per connection.
16900
Willy Tarreau74ca5042013-06-11 23:12:07 +020016901src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020016902 Returns the total amount of data received from the incoming connection's
16903 source address in the current proxy's stick-table or in the designated
16904 stick-table, measured in kilobytes. If the address is not found, zero is
16905 returned. The test is currently performed on 32-bit integers, which limits
16906 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016907
Willy Tarreau74ca5042013-06-11 23:12:07 +020016908src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020016909 Returns the total amount of data sent to the incoming connection's source
16910 address in the current proxy's stick-table or in the designated stick-table,
16911 measured in kilobytes. If the address is not found, zero is returned. The
16912 test is currently performed on 32-bit integers, which limits values to 4
16913 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020016914
Willy Tarreau74ca5042013-06-11 23:12:07 +020016915src_port : integer
16916 Returns an integer value corresponding to the TCP source port of the
16917 connection on the client side, which is the port the client connected from.
16918 Usage of this function is very limited as modern protocols do not care much
16919 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010016920
Willy Tarreau74ca5042013-06-11 23:12:07 +020016921src_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010016922 Returns the cumulative number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020016923 connection's source IPv4 address in the current proxy's stick-table or in the
16924 designated stick-table, that were transformed into sessions, which means that
16925 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016926 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016927
Willy Tarreau74ca5042013-06-11 23:12:07 +020016928src_sess_rate([<table>]) : integer
16929 Returns the average session rate from the incoming connection's source
16930 address in the current proxy's stick-table or in the designated stick-table,
16931 measured in amount of sessions over the period configured in the table. A
16932 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020016933 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020016934
Willy Tarreau74ca5042013-06-11 23:12:07 +020016935src_updt_conn_cnt([<table>]) : integer
16936 Creates or updates the entry associated to the incoming connection's source
16937 address in the current proxy's stick-table or in the designated stick-table.
16938 This table must be configured to store the "conn_cnt" data type, otherwise
16939 the match will be ignored. The current count is incremented by one, and the
16940 expiration timer refreshed. The updated count is returned, so this match
16941 can't return zero. This was used to reject service abusers based on their
16942 source address. Note: it is recommended to use the more complete "track-sc*"
16943 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020016944
16945 Example :
16946 # This frontend limits incoming SSH connections to 3 per 10 second for
16947 # each source address, and rejects excess connections until a 10 second
16948 # silence is observed. At most 20 addresses are tracked.
16949 listen ssh
16950 bind :22
16951 mode tcp
16952 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020016953 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020016954 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020016955 server local 127.0.0.1:22
16956
Willy Tarreau74ca5042013-06-11 23:12:07 +020016957srv_id : integer
16958 Returns an integer containing the server's id when processing the response.
16959 While it's almost only used with ACLs, it may be used for logging or
Christopher Fauletd1b44642020-04-30 09:51:15 +020016960 debugging. It can also be used in a tcp-check or an http-check ruleset.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020016961
vkill1dfd1652019-10-30 16:58:14 +080016962srv_name : string
16963 Returns a string containing the server's name when processing the response.
16964 While it's almost only used with ACLs, it may be used for logging or
Christopher Fauletd1b44642020-04-30 09:51:15 +020016965 debugging. It can also be used in a tcp-check or an http-check ruleset.
vkill1dfd1652019-10-30 16:58:14 +080016966
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200169677.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020016968----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020016969
Willy Tarreau74ca5042013-06-11 23:12:07 +020016970The layer 5 usually describes just the session layer which in haproxy is
16971closest to the session once all the connection handshakes are finished, but
16972when no content is yet made available. The fetch methods described here are
16973usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016974future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020016975
Ben Shillitof25e8e52016-12-02 14:25:37 +00001697651d.all(<prop>[,<prop>*]) : string
16977 Returns values for the properties requested as a string, where values are
16978 separated by the delimiter specified with "51degrees-property-separator".
16979 The device is identified using all the important HTTP headers from the
16980 request. The function can be passed up to five property names, and if a
16981 property name can't be found, the value "NoData" is returned.
16982
16983 Example :
16984 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
16985 # containing the three properties requested using all relevant headers from
16986 # the request.
16987 frontend http-in
16988 bind *:8081
16989 default_backend servers
16990 http-request set-header X-51D-DeviceTypeMobileTablet \
16991 %[51d.all(DeviceType,IsMobile,IsTablet)]
16992
Emeric Brun645ae792014-04-30 14:21:06 +020016993ssl_bc : boolean
16994 Returns true when the back connection was made via an SSL/TLS transport
16995 layer and is locally deciphered. This means the outgoing connection was made
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020016996 other a server with the "ssl" option. It can be used in a tcp-check or an
16997 http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020016998
16999ssl_bc_alg_keysize : integer
17000 Returns the symmetric cipher key size supported in bits when the outgoing
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017001 connection was made over an SSL/TLS transport layer. It can be used in a
17002 tcp-check or an http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020017003
Olivier Houchard6b77f492018-11-22 18:18:29 +010017004ssl_bc_alpn : string
17005 This extracts the Application Layer Protocol Negotiation field from an
17006 outgoing connection made via a TLS transport layer.
Michael Prokop4438c602019-05-24 10:25:45 +020017007 The result is a string containing the protocol name negotiated with the
Olivier Houchard6b77f492018-11-22 18:18:29 +010017008 server. The SSL library must have been built with support for TLS
17009 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
17010 not advertised unless the "alpn" keyword on the "server" line specifies a
17011 protocol list. Also, nothing forces the server to pick a protocol from this
17012 list, any other one may be requested. The TLS ALPN extension is meant to
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017013 replace the TLS NPN extension. See also "ssl_bc_npn". It can be used in a
17014 tcp-check or an http-check ruleset.
Olivier Houchard6b77f492018-11-22 18:18:29 +010017015
Emeric Brun645ae792014-04-30 14:21:06 +020017016ssl_bc_cipher : string
17017 Returns the name of the used cipher when the outgoing connection was made
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017018 over an SSL/TLS transport layer. It can be used in a tcp-check or an
17019 http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020017020
Patrick Hemmer65674662019-06-04 08:13:03 -040017021ssl_bc_client_random : binary
17022 Returns the client random of the back connection when the incoming connection
17023 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
17024 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017025 It can be used in a tcp-check or an http-check ruleset.
Patrick Hemmer65674662019-06-04 08:13:03 -040017026
Emeric Brun74f7ffa2018-02-19 16:14:12 +010017027ssl_bc_is_resumed : boolean
17028 Returns true when the back connection was made over an SSL/TLS transport
17029 layer and the newly created SSL session was resumed using a cached
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017030 session or a TLS ticket. It can be used in a tcp-check or an http-check
17031 ruleset.
Emeric Brun74f7ffa2018-02-19 16:14:12 +010017032
Olivier Houchard6b77f492018-11-22 18:18:29 +010017033ssl_bc_npn : string
17034 This extracts the Next Protocol Negotiation field from an outgoing connection
17035 made via a TLS transport layer. The result is a string containing the
Michael Prokop4438c602019-05-24 10:25:45 +020017036 protocol name negotiated with the server . The SSL library must have been
Olivier Houchard6b77f492018-11-22 18:18:29 +010017037 built with support for TLS extensions enabled (check haproxy -vv). Note that
17038 the TLS NPN extension is not advertised unless the "npn" keyword on the
17039 "server" line specifies a protocol list. Also, nothing forces the server to
17040 pick a protocol from this list, any other one may be used. Please note that
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017041 the TLS NPN extension was replaced with ALPN. It can be used in a tcp-check
17042 or an http-check ruleset.
Olivier Houchard6b77f492018-11-22 18:18:29 +010017043
Emeric Brun645ae792014-04-30 14:21:06 +020017044ssl_bc_protocol : string
17045 Returns the name of the used protocol when the outgoing connection was made
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017046 over an SSL/TLS transport layer. It can be used in a tcp-check or an
17047 http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020017048
Emeric Brunb73a9b02014-04-30 18:49:19 +020017049ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020017050 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020017051 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017052 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64". It
17053 can be used in a tcp-check or an http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020017054
Patrick Hemmer65674662019-06-04 08:13:03 -040017055ssl_bc_server_random : binary
17056 Returns the server random of the back connection when the incoming connection
17057 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
17058 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017059 It can be used in a tcp-check or an http-check ruleset.
Patrick Hemmer65674662019-06-04 08:13:03 -040017060
Emeric Brun645ae792014-04-30 14:21:06 +020017061ssl_bc_session_id : binary
17062 Returns the SSL ID of the back connection when the outgoing connection was
17063 made over an SSL/TLS transport layer. It is useful to log if we want to know
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017064 if session was reused or not. It can be used in a tcp-check or an http-check
17065 ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020017066
Patrick Hemmere0275472018-04-28 19:15:51 -040017067ssl_bc_session_key : binary
17068 Returns the SSL session master key of the back connection when the outgoing
17069 connection was made over an SSL/TLS transport layer. It is useful to decrypt
17070 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017071 BoringSSL. It can be used in a tcp-check or an http-check ruleset.
Patrick Hemmere0275472018-04-28 19:15:51 -040017072
Emeric Brun645ae792014-04-30 14:21:06 +020017073ssl_bc_use_keysize : integer
17074 Returns the symmetric cipher key size used in bits when the outgoing
Christopher Fauletd92ea7f2020-04-30 10:03:55 +020017075 connection was made over an SSL/TLS transport layer. It can be used in a
17076 tcp-check or an http-check ruleset.
Emeric Brun645ae792014-04-30 14:21:06 +020017077
Willy Tarreau74ca5042013-06-11 23:12:07 +020017078ssl_c_ca_err : integer
17079 When the incoming connection was made over an SSL/TLS transport layer,
17080 returns the ID of the first error detected during verification of the client
17081 certificate at depth > 0, or 0 if no error was encountered during this
17082 verification process. Please refer to your SSL library's documentation to
17083 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020017084
Willy Tarreau74ca5042013-06-11 23:12:07 +020017085ssl_c_ca_err_depth : integer
17086 When the incoming connection was made over an SSL/TLS transport layer,
17087 returns the depth in the CA chain of the first error detected during the
17088 verification of the client certificate. If no error is encountered, 0 is
17089 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010017090
Emeric Brun43e79582014-10-29 19:03:26 +010017091ssl_c_der : binary
17092 Returns the DER formatted certificate presented by the client when the
17093 incoming connection was made over an SSL/TLS transport layer. When used for
17094 an ACL, the value(s) to match against can be passed in hexadecimal form.
17095
William Dauchya598b502020-08-06 18:11:38 +020017096ssl_c_der_chain : binary
17097 Returns the DER formatted chain certificate presented by the client when the
17098 incoming connection was made over an SSL/TLS transport layer. When used for
17099 an ACL, the value(s) to match against can be passed in hexadecimal form. One
17100 can parse the result with any lib accepting ASN.1 DER data. It currentlly
17101 does not support resumed sessions.
17102
Willy Tarreau74ca5042013-06-11 23:12:07 +020017103ssl_c_err : integer
17104 When the incoming connection was made over an SSL/TLS transport layer,
17105 returns the ID of the first error detected during verification at depth 0, or
17106 0 if no error was encountered during this verification process. Please refer
17107 to your SSL library's documentation to find the exhaustive list of error
17108 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020017109
Elliot Otchet71f82972020-01-15 08:12:14 -050017110ssl_c_i_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020017111 When the incoming connection was made over an SSL/TLS transport layer,
17112 returns the full distinguished name of the issuer of the certificate
17113 presented by the client when no <entry> is specified, or the value of the
17114 first given entry found from the beginning of the DN. If a positive/negative
17115 occurrence number is specified as the optional second argument, it returns
17116 the value of the nth given entry value from the beginning/end of the DN.
17117 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
17118 "ssl_c_i_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050017119 The <format> parameter allows you to receive the DN suitable for
17120 consumption by different protocols. Currently supported is rfc2253 for
17121 LDAP v3.
17122 If you'd like to modify the format only you can specify an empty string
17123 and zero for the first two parameters. Example: ssl_c_i_dn(,0,rfc2253)
Willy Tarreau62644772008-07-16 18:36:06 +020017124
Willy Tarreau74ca5042013-06-11 23:12:07 +020017125ssl_c_key_alg : string
17126 Returns the name of the algorithm used to generate the key of the certificate
17127 presented by the client when the incoming connection was made over an SSL/TLS
17128 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020017129
Willy Tarreau74ca5042013-06-11 23:12:07 +020017130ssl_c_notafter : string
17131 Returns the end date presented by the client as a formatted string
17132 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
17133 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020017134
Willy Tarreau74ca5042013-06-11 23:12:07 +020017135ssl_c_notbefore : string
17136 Returns the start date presented by the client as a formatted string
17137 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
17138 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010017139
Elliot Otchet71f82972020-01-15 08:12:14 -050017140ssl_c_s_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020017141 When the incoming connection was made over an SSL/TLS transport layer,
17142 returns the full distinguished name of the subject of the certificate
17143 presented by the client when no <entry> is specified, or the value of the
17144 first given entry found from the beginning of the DN. If a positive/negative
17145 occurrence number is specified as the optional second argument, it returns
17146 the value of the nth given entry value from the beginning/end of the DN.
17147 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
17148 "ssl_c_s_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050017149 The <format> parameter allows you to receive the DN suitable for
17150 consumption by different protocols. Currently supported is rfc2253 for
17151 LDAP v3.
17152 If you'd like to modify the format only you can specify an empty string
17153 and zero for the first two parameters. Example: ssl_c_s_dn(,0,rfc2253)
Willy Tarreaub6672b52011-12-12 17:23:41 +010017154
Willy Tarreau74ca5042013-06-11 23:12:07 +020017155ssl_c_serial : binary
17156 Returns the serial of the certificate presented by the client when the
17157 incoming connection was made over an SSL/TLS transport layer. When used for
17158 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020017159
Willy Tarreau74ca5042013-06-11 23:12:07 +020017160ssl_c_sha1 : binary
17161 Returns the SHA-1 fingerprint of the certificate presented by the client when
17162 the incoming connection was made over an SSL/TLS transport layer. This can be
17163 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020017164 Note that the output is binary, so if you want to pass that signature to the
17165 server, you need to encode it in hex or base64, such as in the example below:
17166
Jarno Huuskonen676f6222017-03-30 09:19:45 +030017167 Example:
Willy Tarreau2d0caa32014-07-02 19:01:22 +020017168 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020017169
Willy Tarreau74ca5042013-06-11 23:12:07 +020017170ssl_c_sig_alg : string
17171 Returns the name of the algorithm used to sign the certificate presented by
17172 the client when the incoming connection was made over an SSL/TLS transport
17173 layer.
Emeric Brun87855892012-10-17 17:39:35 +020017174
Willy Tarreau74ca5042013-06-11 23:12:07 +020017175ssl_c_used : boolean
17176 Returns true if current SSL session uses a client certificate even if current
17177 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020017178
Willy Tarreau74ca5042013-06-11 23:12:07 +020017179ssl_c_verify : integer
17180 Returns the verify result error ID when the incoming connection was made over
17181 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
17182 refer to your SSL library's documentation for an exhaustive list of error
17183 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020017184
Willy Tarreau74ca5042013-06-11 23:12:07 +020017185ssl_c_version : integer
17186 Returns the version of the certificate presented by the client when the
17187 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020017188
Emeric Brun43e79582014-10-29 19:03:26 +010017189ssl_f_der : binary
17190 Returns the DER formatted certificate presented by the frontend when the
17191 incoming connection was made over an SSL/TLS transport layer. When used for
17192 an ACL, the value(s) to match against can be passed in hexadecimal form.
17193
Elliot Otchet71f82972020-01-15 08:12:14 -050017194ssl_f_i_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020017195 When the incoming connection was made over an SSL/TLS transport layer,
17196 returns the full distinguished name of the issuer of the certificate
17197 presented by the frontend when no <entry> is specified, or the value of the
17198 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020017199 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020017200 the value of the nth given entry value from the beginning/end of the DN.
17201 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
17202 "ssl_f_i_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050017203 The <format> parameter allows you to receive the DN suitable for
17204 consumption by different protocols. Currently supported is rfc2253 for
17205 LDAP v3.
17206 If you'd like to modify the format only you can specify an empty string
17207 and zero for the first two parameters. Example: ssl_f_i_dn(,0,rfc2253)
Emeric Brun87855892012-10-17 17:39:35 +020017208
Willy Tarreau74ca5042013-06-11 23:12:07 +020017209ssl_f_key_alg : string
17210 Returns the name of the algorithm used to generate the key of the certificate
17211 presented by the frontend when the incoming connection was made over an
17212 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020017213
Willy Tarreau74ca5042013-06-11 23:12:07 +020017214ssl_f_notafter : string
17215 Returns the end date presented by the frontend as a formatted string
17216 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
17217 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020017218
Willy Tarreau74ca5042013-06-11 23:12:07 +020017219ssl_f_notbefore : string
17220 Returns the start date presented by the frontend as a formatted string
17221 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
17222 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020017223
Elliot Otchet71f82972020-01-15 08:12:14 -050017224ssl_f_s_dn([<entry>[,<occ>[,<format>]]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020017225 When the incoming connection was made over an SSL/TLS transport layer,
17226 returns the full distinguished name of the subject of the certificate
17227 presented by the frontend when no <entry> is specified, or the value of the
17228 first given entry found from the beginning of the DN. If a positive/negative
17229 occurrence number is specified as the optional second argument, it returns
17230 the value of the nth given entry value from the beginning/end of the DN.
17231 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
17232 "ssl_f_s_dn(CN)" retrieves the common name.
Elliot Otchet71f82972020-01-15 08:12:14 -050017233 The <format> parameter allows you to receive the DN suitable for
17234 consumption by different protocols. Currently supported is rfc2253 for
17235 LDAP v3.
17236 If you'd like to modify the format only you can specify an empty string
17237 and zero for the first two parameters. Example: ssl_f_s_dn(,0,rfc2253)
Emeric Brunce5ad802012-10-22 14:11:22 +020017238
Willy Tarreau74ca5042013-06-11 23:12:07 +020017239ssl_f_serial : binary
17240 Returns the serial of the certificate presented by the frontend when the
17241 incoming connection was made over an SSL/TLS transport layer. When used for
17242 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020017243
Emeric Brun55f4fa82014-04-30 17:11:25 +020017244ssl_f_sha1 : binary
17245 Returns the SHA-1 fingerprint of the certificate presented by the frontend
17246 when the incoming connection was made over an SSL/TLS transport layer. This
17247 can be used to know which certificate was chosen using SNI.
17248
Willy Tarreau74ca5042013-06-11 23:12:07 +020017249ssl_f_sig_alg : string
17250 Returns the name of the algorithm used to sign the certificate presented by
17251 the frontend when the incoming connection was made over an SSL/TLS transport
17252 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020017253
Willy Tarreau74ca5042013-06-11 23:12:07 +020017254ssl_f_version : integer
17255 Returns the version of the certificate presented by the frontend when the
17256 incoming connection was made over an SSL/TLS transport layer.
17257
17258ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020017259 Returns true when the front connection was made via an SSL/TLS transport
17260 layer and is locally deciphered. This means it has matched a socket declared
17261 with a "bind" line having the "ssl" option.
17262
Willy Tarreau74ca5042013-06-11 23:12:07 +020017263 Example :
17264 # This passes "X-Proto: https" to servers when client connects over SSL
17265 listen http-https
17266 bind :80
17267 bind :443 ssl crt /etc/haproxy.pem
17268 http-request add-header X-Proto https if { ssl_fc }
17269
17270ssl_fc_alg_keysize : integer
17271 Returns the symmetric cipher key size supported in bits when the incoming
17272 connection was made over an SSL/TLS transport layer.
17273
17274ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017275 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020017276 incoming connection made via a TLS transport layer and locally deciphered by
17277 haproxy. The result is a string containing the protocol name advertised by
17278 the client. The SSL library must have been built with support for TLS
17279 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
17280 not advertised unless the "alpn" keyword on the "bind" line specifies a
17281 protocol list. Also, nothing forces the client to pick a protocol from this
17282 list, any other one may be requested. The TLS ALPN extension is meant to
17283 replace the TLS NPN extension. See also "ssl_fc_npn".
17284
Willy Tarreau74ca5042013-06-11 23:12:07 +020017285ssl_fc_cipher : string
17286 Returns the name of the used cipher when the incoming connection was made
17287 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020017288
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010017289ssl_fc_cipherlist_bin : binary
17290 Returns the binary form of the client hello cipher list. The maximum returned
17291 value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010017292 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010017293
17294ssl_fc_cipherlist_hex : string
17295 Returns the binary form of the client hello cipher list encoded as
17296 hexadecimal. The maximum returned value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010017297 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010017298
17299ssl_fc_cipherlist_str : string
17300 Returns the decoded text form of the client hello cipher list. The maximum
17301 number of ciphers returned is according with the value of
17302 "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only
Davor Ocelice9ed2812017-12-25 17:49:28 +010017303 available with OpenSSL >= 1.0.2. If the function is not enabled, this
Emmanuel Hocdetddcde192017-09-01 17:32:08 +020017304 sample-fetch returns the hash like "ssl_fc_cipherlist_xxh".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010017305
17306ssl_fc_cipherlist_xxh : integer
17307 Returns a xxh64 of the cipher list. This hash can be return only is the value
17308 "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010017309 take in account all the data of the cipher list.
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010017310
Patrick Hemmer65674662019-06-04 08:13:03 -040017311ssl_fc_client_random : binary
17312 Returns the client random of the front connection when the incoming connection
17313 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
17314 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
17315
William Lallemand7d42ef52020-07-06 11:41:30 +020017316ssl_fc_client_early_traffic_secret : string
17317 Return the CLIENT_EARLY_TRAFFIC_SECRET as an hexadecimal string for the
17318 front connection when the incoming connection was made over a TLS 1.3
17319 transport layer.
17320 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17321 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17322 activated with "tune.ssl.keylog on" in the global section. See also
17323 "tune.ssl.keylog"
17324
17325ssl_fc_client_handshake_traffic_secret : string
17326 Return the CLIENT_HANDSHAKE_TRAFFIC_SECRET as an hexadecimal string for the
17327 front connection when the incoming connection was made over a TLS 1.3
17328 transport layer.
17329 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17330 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17331 activated with "tune.ssl.keylog on" in the global section. See also
17332 "tune.ssl.keylog"
17333
17334ssl_fc_client_traffic_secret_0 : string
17335 Return the CLIENT_TRAFFIC_SECRET_0 as an hexadecimal string for the
17336 front connection when the incoming connection was made over a TLS 1.3
17337 transport layer.
17338 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17339 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17340 activated with "tune.ssl.keylog on" in the global section. See also
17341 "tune.ssl.keylog"
17342
17343ssl_fc_exporter_secret : string
17344 Return the EXPORTER_SECRET as an hexadecimal string for the
17345 front connection when the incoming connection was made over a TLS 1.3
17346 transport layer.
17347 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17348 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17349 activated with "tune.ssl.keylog on" in the global section. See also
17350 "tune.ssl.keylog"
17351
17352ssl_fc_early_exporter_secret : string
17353 Return the EARLY_EXPORTER_SECRET as an hexadecimal string for the
17354 front connection when the incoming connection was made over an TLS 1.3
17355 transport layer.
17356 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17357 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17358 activated with "tune.ssl.keylog on" in the global section. See also
17359 "tune.ssl.keylog"
17360
Willy Tarreau74ca5042013-06-11 23:12:07 +020017361ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020017362 Returns true if a client certificate is present in an incoming connection over
17363 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010017364 Note: on SSL session resumption with Session ID or TLS ticket, client
17365 certificate is not present in the current connection but may be retrieved
17366 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
17367 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020017368
Olivier Houchardccaa7de2017-10-02 11:51:03 +020017369ssl_fc_has_early : boolean
17370 Returns true if early data were sent, and the handshake didn't happen yet. As
17371 it has security implications, it is useful to be able to refuse those, or
17372 wait until the handshake happened.
17373
Willy Tarreau74ca5042013-06-11 23:12:07 +020017374ssl_fc_has_sni : boolean
17375 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020017376 in an incoming connection was made over an SSL/TLS transport layer. Returns
17377 true when the incoming connection presents a TLS SNI field. This requires
John Roeslerfb2fce12019-07-10 15:45:51 -050017378 that the SSL library is built with support for TLS extensions enabled (check
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020017379 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020017380
Nenad Merdanovic1516fe32016-05-17 03:31:21 +020017381ssl_fc_is_resumed : boolean
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020017382 Returns true if the SSL/TLS session has been resumed through the use of
Jérôme Magnin4a326cb2018-01-15 14:01:17 +010017383 SSL session cache or TLS tickets on an incoming connection over an SSL/TLS
17384 transport layer.
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020017385
Willy Tarreau74ca5042013-06-11 23:12:07 +020017386ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017387 This extracts the Next Protocol Negotiation field from an incoming connection
Willy Tarreau74ca5042013-06-11 23:12:07 +020017388 made via a TLS transport layer and locally deciphered by haproxy. The result
17389 is a string containing the protocol name advertised by the client. The SSL
17390 library must have been built with support for TLS extensions enabled (check
17391 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
17392 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
17393 forces the client to pick a protocol from this list, any other one may be
17394 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020017395
Willy Tarreau74ca5042013-06-11 23:12:07 +020017396ssl_fc_protocol : string
17397 Returns the name of the used protocol when the incoming connection was made
17398 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020017399
Emeric Brunb73a9b02014-04-30 18:49:19 +020017400ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040017401 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020017402 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
17403 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040017404
William Lallemand7d42ef52020-07-06 11:41:30 +020017405ssl_fc_server_handshake_traffic_secret : string
17406 Return the SERVER_HANDSHAKE_TRAFFIC_SECRET as an hexadecimal string for the
17407 front connection when the incoming connection was made over a TLS 1.3
17408 transport layer.
17409 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17410 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17411 activated with "tune.ssl.keylog on" in the global section. See also
17412 "tune.ssl.keylog"
17413
17414ssl_fc_server_traffic_secret_0 : string
17415 Return the SERVER_TRAFFIC_SECRET_0 as an hexadecimal string for the
17416 front connection when the incoming connection was made over an TLS 1.3
17417 transport layer.
17418 Require OpenSSL >= 1.1.1. This is one of the keys dumped by the OpenSSL
17419 keylog callback to generate the SSLKEYLOGFILE. The SSL Key logging must be
17420 activated with "tune.ssl.keylog on" in the global section. See also
17421 "tune.ssl.keylog"
17422
Patrick Hemmer65674662019-06-04 08:13:03 -040017423ssl_fc_server_random : binary
17424 Returns the server random of the front connection when the incoming connection
17425 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
17426 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
17427
Willy Tarreau74ca5042013-06-11 23:12:07 +020017428ssl_fc_session_id : binary
17429 Returns the SSL ID of the front connection when the incoming connection was
17430 made over an SSL/TLS transport layer. It is useful to stick a given client to
17431 a server. It is important to note that some browsers refresh their session ID
17432 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020017433
Patrick Hemmere0275472018-04-28 19:15:51 -040017434ssl_fc_session_key : binary
17435 Returns the SSL session master key of the front connection when the incoming
17436 connection was made over an SSL/TLS transport layer. It is useful to decrypt
17437 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
17438 BoringSSL.
17439
17440
Willy Tarreau74ca5042013-06-11 23:12:07 +020017441ssl_fc_sni : string
17442 This extracts the Server Name Indication TLS extension (SNI) field from an
17443 incoming connection made via an SSL/TLS transport layer and locally
17444 deciphered by haproxy. The result (when present) typically is a string
17445 matching the HTTPS host name (253 chars or less). The SSL library must have
17446 been built with support for TLS extensions enabled (check haproxy -vv).
17447
17448 This fetch is different from "req_ssl_sni" above in that it applies to the
17449 connection being deciphered by haproxy and not to SSL contents being blindly
17450 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
John Roeslerfb2fce12019-07-10 15:45:51 -050017451 requires that the SSL library is built with support for TLS extensions
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020017452 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020017453
Willy Tarreau74ca5042013-06-11 23:12:07 +020017454 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020017455 ssl_fc_sni_end : suffix match
17456 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020017457
Willy Tarreau74ca5042013-06-11 23:12:07 +020017458ssl_fc_use_keysize : integer
17459 Returns the symmetric cipher key size used in bits when the incoming
17460 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020017461
William Lallemandbfa3e812020-06-25 20:07:18 +020017462ssl_s_der : binary
17463 Returns the DER formatted certificate presented by the server when the
17464 outgoing connection was made over an SSL/TLS transport layer. When used for
17465 an ACL, the value(s) to match against can be passed in hexadecimal form.
17466
William Dauchya598b502020-08-06 18:11:38 +020017467ssl_s_chain_der : binary
17468 Returns the DER formatted chain certificate presented by the server when the
17469 outgoing connection was made over an SSL/TLS transport layer. When used for
17470 an ACL, the value(s) to match against can be passed in hexadecimal form. One
17471 can parse the result with any lib accepting ASN.1 DER data. It currentlly
17472 does not support resumed sessions.
17473
William Lallemandbfa3e812020-06-25 20:07:18 +020017474ssl_s_key_alg : string
17475 Returns the name of the algorithm used to generate the key of the certificate
17476 presented by the server when the outgoing connection was made over an
17477 SSL/TLS transport layer.
17478
17479ssl_s_notafter : string
17480 Returns the end date presented by the server as a formatted string
17481 YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS
17482 transport layer.
17483
17484ssl_s_notbefore : string
17485 Returns the start date presented by the server as a formatted string
17486 YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS
17487 transport layer.
17488
17489ssl_s_i_dn([<entry>[,<occ>[,<format>]]]) : string
17490 When the outgoing connection was made over an SSL/TLS transport layer,
17491 returns the full distinguished name of the issuer of the certificate
17492 presented by the server when no <entry> is specified, or the value of the
17493 first given entry found from the beginning of the DN. If a positive/negative
17494 occurrence number is specified as the optional second argument, it returns
17495 the value of the nth given entry value from the beginning/end of the DN.
William Lallemand8f600c82020-06-26 09:55:06 +020017496 For instance, "ssl_s_i_dn(OU,2)" the second organization unit, and
17497 "ssl_s_i_dn(CN)" retrieves the common name.
William Lallemandbfa3e812020-06-25 20:07:18 +020017498 The <format> parameter allows you to receive the DN suitable for
17499 consumption by different protocols. Currently supported is rfc2253 for
17500 LDAP v3.
17501 If you'd like to modify the format only you can specify an empty string
17502 and zero for the first two parameters. Example: ssl_s_i_dn(,0,rfc2253)
17503
17504ssl_s_s_dn([<entry>[,<occ>[,<format>]]]) : string
17505 When the outgoing connection was made over an SSL/TLS transport layer,
17506 returns the full distinguished name of the subject of the certificate
17507 presented by the server when no <entry> is specified, or the value of the
17508 first given entry found from the beginning of the DN. If a positive/negative
17509 occurrence number is specified as the optional second argument, it returns
17510 the value of the nth given entry value from the beginning/end of the DN.
William Lallemand8f600c82020-06-26 09:55:06 +020017511 For instance, "ssl_s_s_dn(OU,2)" the second organization unit, and
17512 "ssl_s_s_dn(CN)" retrieves the common name.
William Lallemandbfa3e812020-06-25 20:07:18 +020017513 The <format> parameter allows you to receive the DN suitable for
17514 consumption by different protocols. Currently supported is rfc2253 for
17515 LDAP v3.
17516 If you'd like to modify the format only you can specify an empty string
17517 and zero for the first two parameters. Example: ssl_s_s_dn(,0,rfc2253)
17518
17519ssl_s_serial : binary
17520 Returns the serial of the certificate presented by the server when the
17521 outgoing connection was made over an SSL/TLS transport layer. When used for
17522 an ACL, the value(s) to match against can be passed in hexadecimal form.
17523
17524ssl_s_sha1 : binary
17525 Returns the SHA-1 fingerprint of the certificate presented by the server
17526 when the outgoing connection was made over an SSL/TLS transport layer. This
17527 can be used to know which certificate was chosen using SNI.
17528
17529ssl_s_sig_alg : string
17530 Returns the name of the algorithm used to sign the certificate presented by
17531 the server when the outgoing connection was made over an SSL/TLS transport
17532 layer.
17533
17534ssl_s_version : integer
17535 Returns the version of the certificate presented by the server when the
17536 outgoing connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020017537
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200175387.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020017539------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020017540
Willy Tarreau74ca5042013-06-11 23:12:07 +020017541Fetching samples from buffer contents is a bit different from the previous
17542sample fetches above because the sampled data are ephemeral. These data can
17543only be used when they're available and will be lost when they're forwarded.
17544For this reason, samples fetched from buffer contents during a request cannot
17545be used in a response for example. Even while the data are being fetched, they
17546can change. Sometimes it is necessary to set some delays or combine multiple
17547sample fetch methods to ensure that the expected data are complete and usable,
17548for example through TCP request content inspection. Please see the "tcp-request
17549content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020017550
Willy Tarreau74ca5042013-06-11 23:12:07 +020017551payload(<offset>,<length>) : binary (deprecated)
Davor Ocelice9ed2812017-12-25 17:49:28 +010017552 This is an alias for "req.payload" when used in the context of a request (e.g.
Willy Tarreau74ca5042013-06-11 23:12:07 +020017553 "stick on", "stick match"), and for "res.payload" when used in the context of
17554 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010017555
Willy Tarreau74ca5042013-06-11 23:12:07 +020017556payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
17557 This is an alias for "req.payload_lv" when used in the context of a request
Davor Ocelice9ed2812017-12-25 17:49:28 +010017558 (e.g. "stick on", "stick match"), and for "res.payload_lv" when used in the
Willy Tarreau74ca5042013-06-11 23:12:07 +020017559 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010017560
Thierry FOURNIERd7d88812017-04-19 15:15:14 +020017561req.hdrs : string
17562 Returns the current request headers as string including the last empty line
17563 separating headers from the request body. The last empty line can be used to
17564 detect a truncated header block. This sample fetch is useful for some SPOE
17565 headers analyzers and for advanced logging.
17566
Thierry FOURNIER5617dce2017-04-09 05:38:19 +020017567req.hdrs_bin : binary
17568 Returns the current request headers contained in preparsed binary form. This
17569 is useful for offloading some processing with SPOE. Each string is described
17570 by a length followed by the number of bytes indicated in the length. The
17571 length is represented using the variable integer encoding detailed in the
17572 SPOE documentation. The end of the list is marked by a couple of empty header
17573 names and values (length of 0 for both).
17574
17575 *(<str:header-name><str:header-value>)<empty string><empty string>
17576
17577 int: refer to the SPOE documentation for the encoding
17578 str: <int:length><bytes>
17579
Willy Tarreau74ca5042013-06-11 23:12:07 +020017580req.len : integer
17581req_len : integer (deprecated)
17582 Returns an integer value corresponding to the number of bytes present in the
17583 request buffer. This is mostly used in ACL. It is important to understand
17584 that this test does not return false as long as the buffer is changing. This
17585 means that a check with equality to zero will almost always immediately match
17586 at the beginning of the session, while a test for more data will wait for
17587 that data to come in and return false only when haproxy is certain that no
17588 more data will come in. This test was designed to be used with TCP request
17589 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017590
Willy Tarreau74ca5042013-06-11 23:12:07 +020017591req.payload(<offset>,<length>) : binary
17592 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020017593 in the request buffer. As a special case, if the <length> argument is zero,
17594 the the whole buffer from <offset> to the end is extracted. This can be used
17595 with ACLs in order to check for the presence of some content in a buffer at
17596 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017597
Willy Tarreau74ca5042013-06-11 23:12:07 +020017598 ACL alternatives :
17599 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017600
Willy Tarreau74ca5042013-06-11 23:12:07 +020017601req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
17602 This extracts a binary block whose size is specified at <offset1> for <length>
17603 bytes, and which starts at <offset2> if specified or just after the length in
17604 the request buffer. The <offset2> parameter also supports relative offsets if
17605 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017606
Willy Tarreau74ca5042013-06-11 23:12:07 +020017607 ACL alternatives :
17608 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017609
Willy Tarreau74ca5042013-06-11 23:12:07 +020017610 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017611
Willy Tarreau74ca5042013-06-11 23:12:07 +020017612req.proto_http : boolean
17613req_proto_http : boolean (deprecated)
17614 Returns true when data in the request buffer look like HTTP and correctly
17615 parses as such. It is the same parser as the common HTTP request parser which
17616 is used so there should be no surprises. The test does not match until the
17617 request is complete, failed or timed out. This test may be used to report the
17618 protocol in TCP logs, but the biggest use is to block TCP request analysis
17619 until a complete HTTP request is present in the buffer, for example to track
17620 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017621
Willy Tarreau74ca5042013-06-11 23:12:07 +020017622 Example:
17623 # track request counts per "base" (concatenation of Host+URL)
17624 tcp-request inspect-delay 10s
17625 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020017626 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020017627
Willy Tarreau74ca5042013-06-11 23:12:07 +020017628req.rdp_cookie([<name>]) : string
17629rdp_cookie([<name>]) : string (deprecated)
17630 When the request buffer looks like the RDP protocol, extracts the RDP cookie
17631 <name>, or any cookie if unspecified. The parser only checks for the first
17632 cookie, as illustrated in the RDP protocol specification. The cookie name is
17633 case insensitive. Generally the "MSTS" cookie name will be used, as it can
17634 contain the user name of the client connecting to the server if properly
17635 configured on the client. The "MSTSHASH" cookie is often used as well for
17636 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017637
Willy Tarreau74ca5042013-06-11 23:12:07 +020017638 This differs from "balance rdp-cookie" in that any balancing algorithm may be
17639 used and thus the distribution of clients to backend servers is not linked to
17640 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
17641 such as "balance roundrobin" or "balance leastconn" will lead to a more even
17642 distribution of clients to backend servers than the hash used by "balance
17643 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017644
Willy Tarreau74ca5042013-06-11 23:12:07 +020017645 ACL derivatives :
17646 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017647
Willy Tarreau74ca5042013-06-11 23:12:07 +020017648 Example :
17649 listen tse-farm
17650 bind 0.0.0.0:3389
17651 # wait up to 5s for an RDP cookie in the request
17652 tcp-request inspect-delay 5s
17653 tcp-request content accept if RDP_COOKIE
17654 # apply RDP cookie persistence
17655 persist rdp-cookie
17656 # Persist based on the mstshash cookie
17657 # This is only useful makes sense if
17658 # balance rdp-cookie is not used
17659 stick-table type string size 204800
17660 stick on req.rdp_cookie(mstshash)
17661 server srv1 1.1.1.1:3389
17662 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017663
Willy Tarreau74ca5042013-06-11 23:12:07 +020017664 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
17665 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017666
Willy Tarreau74ca5042013-06-11 23:12:07 +020017667req.rdp_cookie_cnt([name]) : integer
17668rdp_cookie_cnt([name]) : integer (deprecated)
17669 Tries to parse the request buffer as RDP protocol, then returns an integer
17670 corresponding to the number of RDP cookies found. If an optional cookie name
17671 is passed, only cookies matching this name are considered. This is mostly
17672 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017673
Willy Tarreau74ca5042013-06-11 23:12:07 +020017674 ACL derivatives :
17675 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017676
Alex Zorin4afdd132018-12-30 13:56:28 +110017677req.ssl_alpn : string
17678 Returns a string containing the values of the Application-Layer Protocol
17679 Negotiation (ALPN) TLS extension (RFC7301), sent by the client within the SSL
17680 ClientHello message. Note that this only applies to raw contents found in the
17681 request buffer and not to the contents deciphered via an SSL data layer, so
17682 this will not work with "bind" lines having the "ssl" option. This is useful
17683 in ACL to make a routing decision based upon the ALPN preferences of a TLS
Jarno Huuskonene504f812019-01-03 07:56:49 +020017684 client, like in the example below. See also "ssl_fc_alpn".
Alex Zorin4afdd132018-12-30 13:56:28 +110017685
17686 Examples :
17687 # Wait for a client hello for at most 5 seconds
17688 tcp-request inspect-delay 5s
17689 tcp-request content accept if { req_ssl_hello_type 1 }
Jarno Huuskonene504f812019-01-03 07:56:49 +020017690 use_backend bk_acme if { req.ssl_alpn acme-tls/1 }
Alex Zorin4afdd132018-12-30 13:56:28 +110017691 default_backend bk_default
17692
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020017693req.ssl_ec_ext : boolean
17694 Returns a boolean identifying if client sent the Supported Elliptic Curves
17695 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
Cyril Bonté307ee1e2015-09-28 23:16:06 +020017696 message. This can be used to present ECC compatible clients with EC
17697 certificate and to use RSA for all others, on the same IP address. Note that
17698 this only applies to raw contents found in the request buffer and not to
17699 contents deciphered via an SSL data layer, so this will not work with "bind"
17700 lines having the "ssl" option.
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020017701
Willy Tarreau74ca5042013-06-11 23:12:07 +020017702req.ssl_hello_type : integer
17703req_ssl_hello_type : integer (deprecated)
17704 Returns an integer value containing the type of the SSL hello message found
17705 in the request buffer if the buffer contains data that parse as a complete
17706 SSL (v3 or superior) client hello message. Note that this only applies to raw
17707 contents found in the request buffer and not to contents deciphered via an
17708 SSL data layer, so this will not work with "bind" lines having the "ssl"
17709 option. This is mostly used in ACL to detect presence of an SSL hello message
17710 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017711
Willy Tarreau74ca5042013-06-11 23:12:07 +020017712req.ssl_sni : string
17713req_ssl_sni : string (deprecated)
17714 Returns a string containing the value of the Server Name TLS extension sent
17715 by a client in a TLS stream passing through the request buffer if the buffer
17716 contains data that parse as a complete SSL (v3 or superior) client hello
17717 message. Note that this only applies to raw contents found in the request
17718 buffer and not to contents deciphered via an SSL data layer, so this will not
Lukas Tribusa267b5d2020-07-19 00:25:06 +020017719 work with "bind" lines having the "ssl" option. This will only work for actual
17720 implicit TLS based protocols like HTTPS (443), IMAPS (993), SMTPS (465),
17721 however it will not work for explicit TLS based protocols, like SMTP (25/587)
17722 or IMAP (143). SNI normally contains the name of the host the client tries to
17723 connect to (for recent browsers). SNI is useful for allowing or denying access
17724 to certain hosts when SSL/TLS is used by the client. This test was designed to
17725 be used with TCP request content inspection. If content switching is needed,
17726 it is recommended to first wait for a complete client hello (type 1), like in
17727 the example below. See also "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017728
Willy Tarreau74ca5042013-06-11 23:12:07 +020017729 ACL derivatives :
17730 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017731
Willy Tarreau74ca5042013-06-11 23:12:07 +020017732 Examples :
17733 # Wait for a client hello for at most 5 seconds
17734 tcp-request inspect-delay 5s
17735 tcp-request content accept if { req_ssl_hello_type 1 }
17736 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
17737 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020017738
Pradeep Jindalbb2acf52015-09-29 10:12:57 +053017739req.ssl_st_ext : integer
17740 Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077)
17741 Returns 1 if the client sent SessionTicket TLS Extension
17742 Returns 2 if the client also sent non-zero length TLS SessionTicket
17743 Note that this only applies to raw contents found in the request buffer and
17744 not to contents deciphered via an SSL data layer, so this will not work with
17745 "bind" lines having the "ssl" option. This can for example be used to detect
17746 whether the client sent a SessionTicket or not and stick it accordingly, if
17747 no SessionTicket then stick on SessionID or don't stick as there's no server
17748 side state is there when SessionTickets are in use.
17749
Willy Tarreau74ca5042013-06-11 23:12:07 +020017750req.ssl_ver : integer
17751req_ssl_ver : integer (deprecated)
17752 Returns an integer value containing the version of the SSL/TLS protocol of a
17753 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
17754 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
17755 composed of the major version multiplied by 65536, added to the minor
17756 version. Note that this only applies to raw contents found in the request
17757 buffer and not to contents deciphered via an SSL data layer, so this will not
17758 work with "bind" lines having the "ssl" option. The ACL version of the test
Davor Ocelice9ed2812017-12-25 17:49:28 +010017759 matches against a decimal notation in the form MAJOR.MINOR (e.g. 3.1). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020017760 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017761
Willy Tarreau74ca5042013-06-11 23:12:07 +020017762 ACL derivatives :
17763 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010017764
Willy Tarreau47e8eba2013-09-11 23:28:46 +020017765res.len : integer
17766 Returns an integer value corresponding to the number of bytes present in the
17767 response buffer. This is mostly used in ACL. It is important to understand
17768 that this test does not return false as long as the buffer is changing. This
17769 means that a check with equality to zero will almost always immediately match
17770 at the beginning of the session, while a test for more data will wait for
17771 that data to come in and return false only when haproxy is certain that no
17772 more data will come in. This test was designed to be used with TCP response
Christopher Faulete596d182020-05-05 17:46:34 +020017773 content inspection. But it may also be used in tcp-check based expect rules.
Willy Tarreau47e8eba2013-09-11 23:28:46 +020017774
Willy Tarreau74ca5042013-06-11 23:12:07 +020017775res.payload(<offset>,<length>) : binary
17776 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020017777 in the response buffer. As a special case, if the <length> argument is zero,
Christopher Faulete596d182020-05-05 17:46:34 +020017778 the whole buffer from <offset> to the end is extracted. This can be used
Willy Tarreau00f00842013-08-02 11:07:32 +020017779 with ACLs in order to check for the presence of some content in a buffer at
Christopher Faulete596d182020-05-05 17:46:34 +020017780 any location. It may also be used in tcp-check based expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017781
Willy Tarreau74ca5042013-06-11 23:12:07 +020017782res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
17783 This extracts a binary block whose size is specified at <offset1> for <length>
17784 bytes, and which starts at <offset2> if specified or just after the length in
17785 the response buffer. The <offset2> parameter also supports relative offsets
Christopher Faulete596d182020-05-05 17:46:34 +020017786 if prepended with a '+' or '-' sign. It may also be used in tcp-check based
17787 expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017788
Willy Tarreau74ca5042013-06-11 23:12:07 +020017789 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017790
Willy Tarreau971f7b62015-09-29 14:06:59 +020017791res.ssl_hello_type : integer
17792rep_ssl_hello_type : integer (deprecated)
17793 Returns an integer value containing the type of the SSL hello message found
17794 in the response buffer if the buffer contains data that parses as a complete
17795 SSL (v3 or superior) hello message. Note that this only applies to raw
17796 contents found in the response buffer and not to contents deciphered via an
17797 SSL data layer, so this will not work with "server" lines having the "ssl"
17798 option. This is mostly used in ACL to detect presence of an SSL hello message
17799 that is supposed to contain an SSL session ID usable for stickiness.
17800
Willy Tarreau74ca5042013-06-11 23:12:07 +020017801wait_end : boolean
17802 This fetch either returns true when the inspection period is over, or does
17803 not fetch. It is only used in ACLs, in conjunction with content analysis to
Davor Ocelice9ed2812017-12-25 17:49:28 +010017804 avoid returning a wrong verdict early. It may also be used to delay some
Willy Tarreau74ca5042013-06-11 23:12:07 +020017805 actions, such as a delayed reject for some special addresses. Since it either
17806 stops the rules evaluation or immediately returns true, it is recommended to
Davor Ocelice9ed2812017-12-25 17:49:28 +010017807 use this acl as the last one in a rule. Please note that the default ACL
Willy Tarreau74ca5042013-06-11 23:12:07 +020017808 "WAIT_END" is always usable without prior declaration. This test was designed
17809 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017810
Willy Tarreau74ca5042013-06-11 23:12:07 +020017811 Examples :
17812 # delay every incoming request by 2 seconds
17813 tcp-request inspect-delay 2s
17814 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010017815
Willy Tarreau74ca5042013-06-11 23:12:07 +020017816 # don't immediately tell bad guys they are rejected
17817 tcp-request inspect-delay 10s
17818 acl goodguys src 10.0.0.0/24
17819 acl badguys src 10.0.1.0/24
17820 tcp-request content accept if goodguys
17821 tcp-request content reject if badguys WAIT_END
17822 tcp-request content reject
17823
17824
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200178257.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020017826--------------------------------------
17827
17828It is possible to fetch samples from HTTP contents, requests and responses.
17829This application layer is also called layer 7. It is only possible to fetch the
17830data in this section when a full HTTP request or response has been parsed from
17831its respective request or response buffer. This is always the case with all
17832HTTP specific rules and for sections running with "mode http". When using TCP
17833content inspection, it may be necessary to support an inspection delay in order
17834to let the request or response come in first. These fetches may require a bit
17835more CPU resources than the layer 4 ones, but not much since the request and
17836response are indexed.
17837
17838base : string
17839 This returns the concatenation of the first Host header and the path part of
17840 the request, which starts at the first slash and ends before the question
17841 mark. It can be useful in virtual hosted environments to detect URL abuses as
17842 well as to improve shared caches efficiency. Using this with a limited size
17843 stick table also allows one to collect statistics about most commonly
17844 requested objects by host/path. With ACLs it can allow simple content
17845 switching rules involving the host and the path at the same time, such as
17846 "www.example.com/favicon.ico". See also "path" and "uri".
17847
17848 ACL derivatives :
17849 base : exact string match
17850 base_beg : prefix match
17851 base_dir : subdir match
17852 base_dom : domain match
17853 base_end : suffix match
17854 base_len : length match
17855 base_reg : regex match
17856 base_sub : substring match
17857
17858base32 : integer
17859 This returns a 32-bit hash of the value returned by the "base" fetch method
17860 above. This is useful to track per-URL activity on high traffic sites without
17861 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020017862 memory. The output type is an unsigned integer. The hash function used is
17863 SDBM with full avalanche on the output. Technically, base32 is exactly equal
17864 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020017865
17866base32+src : binary
17867 This returns the concatenation of the base32 fetch above and the src fetch
17868 below. The resulting type is of type binary, with a size of 8 or 20 bytes
17869 depending on the source address family. This can be used to track per-IP,
17870 per-URL counters.
17871
William Lallemand65ad6e12014-01-31 15:08:02 +010017872capture.req.hdr(<idx>) : string
17873 This extracts the content of the header captured by the "capture request
17874 header", idx is the position of the capture keyword in the configuration.
17875 The first entry is an index of 0. See also: "capture request header".
17876
17877capture.req.method : string
17878 This extracts the METHOD of an HTTP request. It can be used in both request
17879 and response. Unlike "method", it can be used in both request and response
17880 because it's allocated.
17881
17882capture.req.uri : string
17883 This extracts the request's URI, which starts at the first slash and ends
17884 before the first space in the request (without the host part). Unlike "path"
17885 and "url", it can be used in both request and response because it's
17886 allocated.
17887
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020017888capture.req.ver : string
17889 This extracts the request's HTTP version and returns either "HTTP/1.0" or
17890 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
17891 logs because it relies on a persistent flag.
17892
William Lallemand65ad6e12014-01-31 15:08:02 +010017893capture.res.hdr(<idx>) : string
17894 This extracts the content of the header captured by the "capture response
17895 header", idx is the position of the capture keyword in the configuration.
17896 The first entry is an index of 0.
17897 See also: "capture response header"
17898
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020017899capture.res.ver : string
17900 This extracts the response's HTTP version and returns either "HTTP/1.0" or
17901 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
17902 persistent flag.
17903
Willy Tarreaua5910cc2015-05-02 00:46:08 +020017904req.body : binary
Christopher Fauletaf4dc4c2020-05-05 17:33:25 +020017905 This returns the HTTP request's available body as a block of data. It is
17906 recommended to use "option http-buffer-request" to be sure to wait, as much
17907 as possible, for the request's body.
Willy Tarreaua5910cc2015-05-02 00:46:08 +020017908
Thierry FOURNIER9826c772015-05-20 15:50:54 +020017909req.body_param([<name>) : string
17910 This fetch assumes that the body of the POST request is url-encoded. The user
17911 can check if the "content-type" contains the value
17912 "application/x-www-form-urlencoded". This extracts the first occurrence of the
17913 parameter <name> in the body, which ends before '&'. The parameter name is
17914 case-sensitive. If no name is given, any parameter will match, and the first
17915 one will be returned. The result is a string corresponding to the value of the
17916 parameter <name> as presented in the request body (no URL decoding is
17917 performed). Note that the ACL version of this fetch iterates over multiple
17918 parameters and will iteratively report all parameters values if no name is
17919 given.
17920
Willy Tarreaua5910cc2015-05-02 00:46:08 +020017921req.body_len : integer
17922 This returns the length of the HTTP request's available body in bytes. It may
17923 be lower than the advertised length if the body is larger than the buffer. It
Christopher Fauletaf4dc4c2020-05-05 17:33:25 +020017924 is recommended to use "option http-buffer-request" to be sure to wait, as
17925 much as possible, for the request's body.
Willy Tarreaua5910cc2015-05-02 00:46:08 +020017926
17927req.body_size : integer
17928 This returns the advertised length of the HTTP request's body in bytes. It
Christopher Fauletaf4dc4c2020-05-05 17:33:25 +020017929 will represent the advertised Content-Length header, or the size of the
17930 available data in case of chunked encoding.
Willy Tarreaua5910cc2015-05-02 00:46:08 +020017931
Willy Tarreau74ca5042013-06-11 23:12:07 +020017932req.cook([<name>]) : string
17933cook([<name>]) : string (deprecated)
17934 This extracts the last occurrence of the cookie name <name> on a "Cookie"
17935 header line from the request, and returns its value as string. If no name is
17936 specified, the first cookie value is returned. When used with ACLs, all
17937 matching cookies are evaluated. Spaces around the name and the value are
17938 ignored as requested by the Cookie header specification (RFC6265). The cookie
17939 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
17940 well return an empty value if it is present. Use the "found" match to detect
17941 presence. Use the res.cook() variant for response cookies sent by the server.
17942
17943 ACL derivatives :
17944 cook([<name>]) : exact string match
17945 cook_beg([<name>]) : prefix match
17946 cook_dir([<name>]) : subdir match
17947 cook_dom([<name>]) : domain match
17948 cook_end([<name>]) : suffix match
17949 cook_len([<name>]) : length match
17950 cook_reg([<name>]) : regex match
17951 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010017952
Willy Tarreau74ca5042013-06-11 23:12:07 +020017953req.cook_cnt([<name>]) : integer
17954cook_cnt([<name>]) : integer (deprecated)
17955 Returns an integer value representing the number of occurrences of the cookie
17956 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017957
Willy Tarreau74ca5042013-06-11 23:12:07 +020017958req.cook_val([<name>]) : integer
17959cook_val([<name>]) : integer (deprecated)
17960 This extracts the last occurrence of the cookie name <name> on a "Cookie"
17961 header line from the request, and converts its value to an integer which is
17962 returned. If no name is specified, the first cookie value is returned. When
17963 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020017964
Willy Tarreau74ca5042013-06-11 23:12:07 +020017965cookie([<name>]) : string (deprecated)
17966 This extracts the last occurrence of the cookie name <name> on a "Cookie"
17967 header line from the request, or a "Set-Cookie" header from the response, and
17968 returns its value as a string. A typical use is to get multiple clients
17969 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020017970 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020017971 multi-peer synchronization and state keeping across restarts. If no name is
17972 specified, the first cookie value is returned. This fetch should not be used
17973 anymore and should be replaced by req.cook() or res.cook() instead as it
17974 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017975
Willy Tarreau74ca5042013-06-11 23:12:07 +020017976hdr([<name>[,<occ>]]) : string
17977 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
17978 used on responses. Please refer to these respective fetches for more details.
17979 In case of doubt about the fetch direction, please use the explicit ones.
17980 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017981 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017982
Willy Tarreau74ca5042013-06-11 23:12:07 +020017983req.fhdr(<name>[,<occ>]) : string
17984 This extracts the last occurrence of header <name> in an HTTP request. When
17985 used from an ACL, all occurrences are iterated over until a match is found.
17986 Optionally, a specific occurrence might be specified as a position number.
17987 Positive values indicate a position from the first occurrence, with 1 being
17988 the first one. Negative values indicate positions relative to the last one,
17989 with -1 being the last one. It differs from req.hdr() in that any commas
17990 present in the value are returned and are not used as delimiters. This is
17991 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017992
Willy Tarreau74ca5042013-06-11 23:12:07 +020017993req.fhdr_cnt([<name>]) : integer
17994 Returns an integer value representing the number of occurrences of request
17995 header field name <name>, or the total number of header fields if <name> is
17996 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
17997 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010017998
Willy Tarreau74ca5042013-06-11 23:12:07 +020017999req.hdr([<name>[,<occ>]]) : string
18000 This extracts the last occurrence of header <name> in an HTTP request. When
18001 used from an ACL, all occurrences are iterated over until a match is found.
18002 Optionally, a specific occurrence might be specified as a position number.
18003 Positive values indicate a position from the first occurrence, with 1 being
18004 the first one. Negative values indicate positions relative to the last one,
18005 with -1 being the last one. A typical use is with the X-Forwarded-For header
18006 once converted to IP, associated with an IP stick-table. The function
18007 considers any comma as a delimiter for distinct values. If full-line headers
Lukas Tribus23953682017-04-28 13:24:30 +000018008 are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
Willy Tarreau74ca5042013-06-11 23:12:07 +020018009 how certain headers are supposed to be parsed. Also, some of them are case
Davor Ocelice9ed2812017-12-25 17:49:28 +010018010 insensitive (e.g. Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010018011
Willy Tarreau74ca5042013-06-11 23:12:07 +020018012 ACL derivatives :
18013 hdr([<name>[,<occ>]]) : exact string match
18014 hdr_beg([<name>[,<occ>]]) : prefix match
18015 hdr_dir([<name>[,<occ>]]) : subdir match
18016 hdr_dom([<name>[,<occ>]]) : domain match
18017 hdr_end([<name>[,<occ>]]) : suffix match
18018 hdr_len([<name>[,<occ>]]) : length match
18019 hdr_reg([<name>[,<occ>]]) : regex match
18020 hdr_sub([<name>[,<occ>]]) : substring match
18021
18022req.hdr_cnt([<name>]) : integer
18023hdr_cnt([<header>]) : integer (deprecated)
18024 Returns an integer value representing the number of occurrences of request
18025 header field name <name>, or the total number of header field values if
18026 <name> is not specified. It is important to remember that one header line may
18027 count as several headers if it has several values. The function considers any
18028 comma as a delimiter for distinct values. If full-line headers are desired
18029 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
18030 detect presence, absence or abuse of a specific header, as well as to block
18031 request smuggling attacks by rejecting requests which contain more than one
18032 of certain headers. See "req.hdr" for more information on header matching.
18033
18034req.hdr_ip([<name>[,<occ>]]) : ip
18035hdr_ip([<name>[,<occ>]]) : ip (deprecated)
18036 This extracts the last occurrence of header <name> in an HTTP request,
18037 converts it to an IPv4 or IPv6 address and returns this address. When used
18038 with ACLs, all occurrences are checked, and if <name> is omitted, every value
18039 of every header is checked. Optionally, a specific occurrence might be
18040 specified as a position number. Positive values indicate a position from the
Davor Ocelice9ed2812017-12-25 17:49:28 +010018041 first occurrence, with 1 being the first one. Negative values indicate
Willy Tarreau74ca5042013-06-11 23:12:07 +020018042 positions relative to the last one, with -1 being the last one. A typical use
18043 is with the X-Forwarded-For and X-Client-IP headers.
18044
18045req.hdr_val([<name>[,<occ>]]) : integer
18046hdr_val([<name>[,<occ>]]) : integer (deprecated)
18047 This extracts the last occurrence of header <name> in an HTTP request, and
18048 converts it to an integer value. When used with ACLs, all occurrences are
18049 checked, and if <name> is omitted, every value of every header is checked.
18050 Optionally, a specific occurrence might be specified as a position number.
18051 Positive values indicate a position from the first occurrence, with 1 being
18052 the first one. Negative values indicate positions relative to the last one,
18053 with -1 being the last one. A typical use is with the X-Forwarded-For header.
18054
Frédéric Lécailleec891192019-02-26 15:02:35 +010018055
18056
Willy Tarreau74ca5042013-06-11 23:12:07 +020018057http_auth(<userlist>) : boolean
18058 Returns a boolean indicating whether the authentication data received from
18059 the client match a username & password stored in the specified userlist. This
18060 fetch function is not really useful outside of ACLs. Currently only http
18061 basic auth is supported.
18062
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010018063http_auth_group(<userlist>) : string
18064 Returns a string corresponding to the user name found in the authentication
18065 data received from the client if both the user name and password are valid
18066 according to the specified userlist. The main purpose is to use it in ACLs
18067 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020018068 This fetch function is not really useful outside of ACLs. Currently only http
18069 basic auth is supported.
18070
18071 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010018072 http_auth_group(<userlist>) : group ...
18073 Returns true when the user extracted from the request and whose password is
18074 valid according to the specified userlist belongs to at least one of the
18075 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020018076
Christopher Fauleta4063562019-08-02 11:51:37 +020018077http_auth_pass : string
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010018078 Returns the user's password found in the authentication data received from
18079 the client, as supplied in the Authorization header. Not checks are
18080 performed by this sample fetch. Only Basic authentication is supported.
Christopher Fauleta4063562019-08-02 11:51:37 +020018081
18082http_auth_type : string
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010018083 Returns the authentication method found in the authentication data received from
18084 the client, as supplied in the Authorization header. Not checks are
18085 performed by this sample fetch. Only Basic authentication is supported.
Christopher Fauleta4063562019-08-02 11:51:37 +020018086
18087http_auth_user : string
Willy Tarreauc9c6cdb2020-03-05 16:03:58 +010018088 Returns the user name found in the authentication data received from the
18089 client, as supplied in the Authorization header. Not checks are performed by
18090 this sample fetch. Only Basic authentication is supported.
Christopher Fauleta4063562019-08-02 11:51:37 +020018091
Willy Tarreau74ca5042013-06-11 23:12:07 +020018092http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020018093 Returns true when the request being processed is the first one of the
18094 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020018095 from some requests when a request is not the first one, or to help grouping
18096 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020018097
Willy Tarreau74ca5042013-06-11 23:12:07 +020018098method : integer + string
18099 Returns an integer value corresponding to the method in the HTTP request. For
18100 example, "GET" equals 1 (check sources to establish the matching). Value 9
18101 means "other method" and may be converted to a string extracted from the
18102 stream. This should not be used directly as a sample, this is only meant to
18103 be used from ACLs, which transparently convert methods from patterns to these
18104 integer + string values. Some predefined ACL already check for most common
18105 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018106
Willy Tarreau74ca5042013-06-11 23:12:07 +020018107 ACL derivatives :
18108 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020018109
Willy Tarreau74ca5042013-06-11 23:12:07 +020018110 Example :
18111 # only accept GET and HEAD requests
18112 acl valid_method method GET HEAD
18113 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020018114
Willy Tarreau74ca5042013-06-11 23:12:07 +020018115path : string
18116 This extracts the request's URL path, which starts at the first slash and
18117 ends before the question mark (without the host part). A typical use is with
18118 prefetch-capable caches, and with portals which need to aggregate multiple
18119 information from databases and keep them in caches. Note that with outgoing
18120 caches, it would be wiser to use "url" instead. With ACLs, it's typically
Davor Ocelice9ed2812017-12-25 17:49:28 +010018121 used to match exact file names (e.g. "/login.php"), or directory parts using
Willy Tarreau74ca5042013-06-11 23:12:07 +020018122 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018123
Willy Tarreau74ca5042013-06-11 23:12:07 +020018124 ACL derivatives :
18125 path : exact string match
18126 path_beg : prefix match
18127 path_dir : subdir match
18128 path_dom : domain match
18129 path_end : suffix match
18130 path_len : length match
18131 path_reg : regex match
18132 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020018133
Christopher Faulete720c322020-09-02 17:25:18 +020018134pathq : string
18135 This extracts the request's URL path with the query-string, which starts at
18136 the first slash. This sample fetch is pretty handy to always retrieve a
18137 relative URI, excluding the scheme and the authority part, if any. Indeed,
18138 while it is the common representation for an HTTP/1.1 request target, in
18139 HTTP/2, an absolute URI is often used. This sample fetch will return the same
18140 result in both cases.
18141
Willy Tarreau49ad95c2015-01-19 15:06:26 +010018142query : string
18143 This extracts the request's query string, which starts after the first
18144 question mark. If no question mark is present, this fetch returns nothing. If
18145 a question mark is present but nothing follows, it returns an empty string.
18146 This means it's possible to easily know whether a query string is present
Tim Düsterhus4896c442016-11-29 02:15:19 +010018147 using the "found" matching method. This fetch is the complement of "path"
Willy Tarreau49ad95c2015-01-19 15:06:26 +010018148 which stops before the question mark.
18149
Willy Tarreaueb27ec72015-02-20 13:55:29 +010018150req.hdr_names([<delim>]) : string
18151 This builds a string made from the concatenation of all header names as they
18152 appear in the request when the rule is evaluated. The default delimiter is
18153 the comma (',') but it may be overridden as an optional argument <delim>. In
18154 this case, only the first character of <delim> is considered.
18155
Willy Tarreau74ca5042013-06-11 23:12:07 +020018156req.ver : string
18157req_ver : string (deprecated)
18158 Returns the version string from the HTTP request, for example "1.1". This can
18159 be useful for logs, but is mostly there for ACL. Some predefined ACL already
18160 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010018161
Willy Tarreau74ca5042013-06-11 23:12:07 +020018162 ACL derivatives :
18163 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020018164
Christopher Faulete596d182020-05-05 17:46:34 +020018165res.body : binary
18166 This returns the HTTP response's available body as a block of data. Unlike
18167 the request side, there is no directive to wait for the response's body. This
18168 sample fetch is really useful (and usable) in the health-check context. It
18169 may be used in tcp-check based expect rules.
18170
18171res.body_len : integer
18172 This returns the length of the HTTP response available body in bytes. Unlike
18173 the request side, there is no directive to wait for the response's body. This
18174 sample fetch is really useful (and usable) in the health-check context. It
18175 may be used in tcp-check based expect rules.
18176
18177res.body_size : integer
18178 This returns the advertised length of the HTTP response body in bytes. It
18179 will represent the advertised Content-Length header, or the size of the
18180 available data in case of chunked encoding. Unlike the request side, there is
18181 no directive to wait for the response body. This sample fetch is really
18182 useful (and usable) in the health-check context. It may be used in tcp-check
18183 based expect rules.
18184
Willy Tarreau74ca5042013-06-11 23:12:07 +020018185res.comp : boolean
18186 Returns the boolean "true" value if the response has been compressed by
18187 HAProxy, otherwise returns boolean "false". This may be used to add
18188 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018189
Willy Tarreau74ca5042013-06-11 23:12:07 +020018190res.comp_algo : string
18191 Returns a string containing the name of the algorithm used if the response
18192 was compressed by HAProxy, for example : "deflate". This may be used to add
18193 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010018194
Willy Tarreau74ca5042013-06-11 23:12:07 +020018195res.cook([<name>]) : string
18196scook([<name>]) : string (deprecated)
18197 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
18198 header line from the response, and returns its value as string. If no name is
Christopher Faulete596d182020-05-05 17:46:34 +020018199 specified, the first cookie value is returned. It may be used in tcp-check
18200 based expect rules.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020018201
Willy Tarreau74ca5042013-06-11 23:12:07 +020018202 ACL derivatives :
18203 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020018204
Willy Tarreau74ca5042013-06-11 23:12:07 +020018205res.cook_cnt([<name>]) : integer
18206scook_cnt([<name>]) : integer (deprecated)
18207 Returns an integer value representing the number of occurrences of the cookie
18208 <name> in the response, or all cookies if <name> is not specified. This is
Christopher Faulete596d182020-05-05 17:46:34 +020018209 mostly useful when combined with ACLs to detect suspicious responses. It may
18210 be used in tcp-check based expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010018211
Willy Tarreau74ca5042013-06-11 23:12:07 +020018212res.cook_val([<name>]) : integer
18213scook_val([<name>]) : integer (deprecated)
18214 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
18215 header line from the response, and converts its value to an integer which is
Christopher Faulete596d182020-05-05 17:46:34 +020018216 returned. If no name is specified, the first cookie value is returned. It may
18217 be used in tcp-check based expect rules.
Willy Tarreaud63335a2010-02-26 12:56:52 +010018218
Willy Tarreau74ca5042013-06-11 23:12:07 +020018219res.fhdr([<name>[,<occ>]]) : string
18220 This extracts the last occurrence of header <name> in an HTTP response, or of
18221 the last header if no <name> is specified. Optionally, a specific occurrence
18222 might be specified as a position number. Positive values indicate a position
18223 from the first occurrence, with 1 being the first one. Negative values
18224 indicate positions relative to the last one, with -1 being the last one. It
18225 differs from res.hdr() in that any commas present in the value are returned
18226 and are not used as delimiters. If this is not desired, the res.hdr() fetch
18227 should be used instead. This is sometimes useful with headers such as Date or
Christopher Faulete596d182020-05-05 17:46:34 +020018228 Expires. It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018229
Willy Tarreau74ca5042013-06-11 23:12:07 +020018230res.fhdr_cnt([<name>]) : integer
18231 Returns an integer value representing the number of occurrences of response
18232 header field name <name>, or the total number of header fields if <name> is
18233 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
18234 the number of full line headers and does not stop on commas. If this is not
Christopher Faulete596d182020-05-05 17:46:34 +020018235 desired, the res.hdr_cnt() fetch should be used instead. It may be used in
18236 tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018237
Willy Tarreau74ca5042013-06-11 23:12:07 +020018238res.hdr([<name>[,<occ>]]) : string
18239shdr([<name>[,<occ>]]) : string (deprecated)
18240 This extracts the last occurrence of header <name> in an HTTP response, or of
18241 the last header if no <name> is specified. Optionally, a specific occurrence
18242 might be specified as a position number. Positive values indicate a position
18243 from the first occurrence, with 1 being the first one. Negative values
18244 indicate positions relative to the last one, with -1 being the last one. This
18245 can be useful to learn some data into a stick-table. The function considers
18246 any comma as a delimiter for distinct values. If this is not desired, the
Christopher Faulete596d182020-05-05 17:46:34 +020018247 res.fhdr() fetch should be used instead. It may be used in tcp-check based
18248 expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018249
Willy Tarreau74ca5042013-06-11 23:12:07 +020018250 ACL derivatives :
18251 shdr([<name>[,<occ>]]) : exact string match
18252 shdr_beg([<name>[,<occ>]]) : prefix match
18253 shdr_dir([<name>[,<occ>]]) : subdir match
18254 shdr_dom([<name>[,<occ>]]) : domain match
18255 shdr_end([<name>[,<occ>]]) : suffix match
18256 shdr_len([<name>[,<occ>]]) : length match
18257 shdr_reg([<name>[,<occ>]]) : regex match
18258 shdr_sub([<name>[,<occ>]]) : substring match
18259
18260res.hdr_cnt([<name>]) : integer
18261shdr_cnt([<name>]) : integer (deprecated)
18262 Returns an integer value representing the number of occurrences of response
18263 header field name <name>, or the total number of header fields if <name> is
18264 not specified. The function considers any comma as a delimiter for distinct
18265 values. If this is not desired, the res.fhdr_cnt() fetch should be used
Christopher Faulete596d182020-05-05 17:46:34 +020018266 instead. It may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018267
Willy Tarreau74ca5042013-06-11 23:12:07 +020018268res.hdr_ip([<name>[,<occ>]]) : ip
18269shdr_ip([<name>[,<occ>]]) : ip (deprecated)
18270 This extracts the last occurrence of header <name> in an HTTP response,
18271 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
18272 specific occurrence might be specified as a position number. Positive values
18273 indicate a position from the first occurrence, with 1 being the first one.
18274 Negative values indicate positions relative to the last one, with -1 being
Christopher Faulete596d182020-05-05 17:46:34 +020018275 the last one. This can be useful to learn some data into a stick table. It
18276 may be used in tcp-check based expect rules.
Willy Tarreau6a06a402007-07-15 20:15:28 +020018277
Willy Tarreaueb27ec72015-02-20 13:55:29 +010018278res.hdr_names([<delim>]) : string
18279 This builds a string made from the concatenation of all header names as they
18280 appear in the response when the rule is evaluated. The default delimiter is
18281 the comma (',') but it may be overridden as an optional argument <delim>. In
Christopher Faulete596d182020-05-05 17:46:34 +020018282 this case, only the first character of <delim> is considered. It may be used
18283 in tcp-check based expect rules.
Willy Tarreaueb27ec72015-02-20 13:55:29 +010018284
Willy Tarreau74ca5042013-06-11 23:12:07 +020018285res.hdr_val([<name>[,<occ>]]) : integer
18286shdr_val([<name>[,<occ>]]) : integer (deprecated)
18287 This extracts the last occurrence of header <name> in an HTTP response, and
18288 converts it to an integer value. Optionally, a specific occurrence might be
18289 specified as a position number. Positive values indicate a position from the
18290 first occurrence, with 1 being the first one. Negative values indicate
18291 positions relative to the last one, with -1 being the last one. This can be
Christopher Faulete596d182020-05-05 17:46:34 +020018292 useful to learn some data into a stick table. It may be used in tcp-check
18293 based expect rules.
18294
18295res.hdrs : string
18296 Returns the current response headers as string including the last empty line
18297 separating headers from the request body. The last empty line can be used to
18298 detect a truncated header block. This sample fetch is useful for some SPOE
18299 headers analyzers and for advanced logging. It may also be used in tcp-check
18300 based expect rules.
18301
18302res.hdrs_bin : binary
18303 Returns the current response headers contained in preparsed binary form. This
18304 is useful for offloading some processing with SPOE. It may be used in
18305 tcp-check based expect rules. Each string is described by a length followed
18306 by the number of bytes indicated in the length. The length is represented
18307 using the variable integer encoding detailed in the SPOE documentation. The
18308 end of the list is marked by a couple of empty header names and values
18309 (length of 0 for both).
18310
18311 *(<str:header-name><str:header-value>)<empty string><empty string>
18312
18313 int: refer to the SPOE documentation for the encoding
18314 str: <int:length><bytes>
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010018315
Willy Tarreau74ca5042013-06-11 23:12:07 +020018316res.ver : string
18317resp_ver : string (deprecated)
18318 Returns the version string from the HTTP response, for example "1.1". This
Christopher Faulete596d182020-05-05 17:46:34 +020018319 can be useful for logs, but is mostly there for ACL. It may be used in
18320 tcp-check based expect rules.
Willy Tarreau0e698542011-09-16 08:32:32 +020018321
Willy Tarreau74ca5042013-06-11 23:12:07 +020018322 ACL derivatives :
18323 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010018324
Willy Tarreau74ca5042013-06-11 23:12:07 +020018325set-cookie([<name>]) : string (deprecated)
18326 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
18327 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020018328 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020018329 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010018330
Willy Tarreau74ca5042013-06-11 23:12:07 +020018331 This fetch function is deprecated and has been superseded by the "res.cook"
18332 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010018333
Willy Tarreau74ca5042013-06-11 23:12:07 +020018334status : integer
18335 Returns an integer containing the HTTP status code in the HTTP response, for
18336 example, 302. It is mostly used within ACLs and integer ranges, for example,
Christopher Faulete596d182020-05-05 17:46:34 +020018337 to remove any Location header if the response is not a 3xx. It may be used in
18338 tcp-check based expect rules.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018339
Thierry Fournier0e00dca2016-04-07 15:47:40 +020018340unique-id : string
18341 Returns the unique-id attached to the request. The directive
18342 "unique-id-format" must be set. If it is not set, the unique-id sample fetch
18343 fails. Note that the unique-id is usually used with HTTP requests, however this
18344 sample fetch can be used with other protocols. Obviously, if it is used with
18345 other protocols than HTTP, the unique-id-format directive must not contain
18346 HTTP parts. See: unique-id-format and unique-id-header
18347
Willy Tarreau74ca5042013-06-11 23:12:07 +020018348url : string
18349 This extracts the request's URL as presented in the request. A typical use is
18350 with prefetch-capable caches, and with portals which need to aggregate
18351 multiple information from databases and keep them in caches. With ACLs, using
18352 "path" is preferred over using "url", because clients may send a full URL as
18353 is normally done with proxies. The only real use is to match "*" which does
18354 not match in "path", and for which there is already a predefined ACL. See
18355 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018356
Willy Tarreau74ca5042013-06-11 23:12:07 +020018357 ACL derivatives :
18358 url : exact string match
18359 url_beg : prefix match
18360 url_dir : subdir match
18361 url_dom : domain match
18362 url_end : suffix match
18363 url_len : length match
18364 url_reg : regex match
18365 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018366
Willy Tarreau74ca5042013-06-11 23:12:07 +020018367url_ip : ip
18368 This extracts the IP address from the request's URL when the host part is
18369 presented as an IP address. Its use is very limited. For instance, a
18370 monitoring system might use this field as an alternative for the source IP in
18371 order to test what path a given source address would follow, or to force an
18372 entry in a table for a given source address. With ACLs it can be used to
18373 restrict access to certain systems through a proxy, for example when combined
18374 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018375
Willy Tarreau74ca5042013-06-11 23:12:07 +020018376url_port : integer
18377 This extracts the port part from the request's URL. Note that if the port is
18378 not specified in the request, port 80 is assumed. With ACLs it can be used to
18379 restrict access to certain systems through a proxy, for example when combined
18380 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018381
Willy Tarreau1ede1da2015-05-07 16:06:18 +020018382urlp([<name>[,<delim>]]) : string
18383url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020018384 This extracts the first occurrence of the parameter <name> in the query
18385 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020018386 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
18387 any parameter will match, and the first one will be returned. The result is
18388 a string corresponding to the value of the parameter <name> as presented in
18389 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020018390 stickiness based on a client ID, to extract an application cookie passed as a
18391 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020018392 this fetch iterates over multiple parameters and will iteratively report all
18393 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018394
Willy Tarreau74ca5042013-06-11 23:12:07 +020018395 ACL derivatives :
18396 urlp(<name>[,<delim>]) : exact string match
18397 urlp_beg(<name>[,<delim>]) : prefix match
18398 urlp_dir(<name>[,<delim>]) : subdir match
18399 urlp_dom(<name>[,<delim>]) : domain match
18400 urlp_end(<name>[,<delim>]) : suffix match
18401 urlp_len(<name>[,<delim>]) : length match
18402 urlp_reg(<name>[,<delim>]) : regex match
18403 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018404
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018405
Willy Tarreau74ca5042013-06-11 23:12:07 +020018406 Example :
18407 # match http://example.com/foo?PHPSESSIONID=some_id
18408 stick on urlp(PHPSESSIONID)
18409 # match http://example.com/foo;JSESSIONID=some_id
18410 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020018411
Jarno Huuskonen676f6222017-03-30 09:19:45 +030018412urlp_val([<name>[,<delim>]]) : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020018413 See "urlp" above. This one extracts the URL parameter <name> in the request
18414 and converts it to an integer value. This can be used for session stickiness
18415 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020018416
Dragan Dosen0070cd52016-06-16 12:19:49 +020018417url32 : integer
18418 This returns a 32-bit hash of the value obtained by concatenating the first
18419 Host header and the whole URL including parameters (not only the path part of
18420 the request, as in the "base32" fetch above). This is useful to track per-URL
18421 activity. A shorter hash is stored, saving a lot of memory. The output type
18422 is an unsigned integer.
18423
18424url32+src : binary
18425 This returns the concatenation of the "url32" fetch and the "src" fetch. The
18426 resulting type is of type binary, with a size of 8 or 20 bytes depending on
18427 the source address family. This can be used to track per-IP, per-URL counters.
18428
Christopher Faulet16032ab2020-04-30 11:30:00 +020018429
Christopher Faulete596d182020-05-05 17:46:34 +0200184307.3.7. Fetching samples for developers
Christopher Fauletd47941d2020-01-08 14:40:19 +010018431---------------------------------------
18432
18433This set of sample fetch methods is reserved to developers and must never be
18434used on a production environment, except on developer demand, for debugging
18435purposes. Moreover, no special care will be taken on backwards compatibility.
18436There is no warranty the following sample fetches will never change, be renamed
18437or simply removed. So be really careful if you should use one of them. To avoid
18438any ambiguity, these sample fetches are placed in the dedicated scope "internal",
18439for instance "internal.strm.is_htx".
18440
18441internal.htx.data : integer
18442 Returns the size in bytes used by data in the HTX message associated to a
18443 channel. The channel is chosen depending on the sample direction.
18444
18445internal.htx.free : integer
18446 Returns the free space (size - used) in bytes in the HTX message associated
18447 to a channel. The channel is chosen depending on the sample direction.
18448
18449internal.htx.free_data : integer
18450 Returns the free space for the data in bytes in the HTX message associated to
18451 a channel. The channel is chosen depending on the sample direction.
18452
18453internal.htx.has_eom : boolean
18454 Returns true if the HTX message associated to a channel contains an
18455 end-of-message block (EOM). Otherwise, it returns false. The channel is
18456 chosen depending on the sample direction.
18457
18458internal.htx.nbblks : integer
18459 Returns the number of blocks present in the HTX message associated to a
18460 channel. The channel is chosen depending on the sample direction.
18461
18462internal.htx.size : integer
18463 Returns the total size in bytes of the HTX message associated to a
18464 channel. The channel is chosen depending on the sample direction.
18465
18466internal.htx.used : integer
18467 Returns the total size used in bytes (data + metadata) in the HTX message
18468 associated to a channel. The channel is chosen depending on the sample
18469 direction.
18470
18471internal.htx_blk.size(<idx>) : integer
18472 Returns the size of the block at the position <idx> in the HTX message
18473 associated to a channel or 0 if it does not exist. The channel is chosen
18474 depending on the sample direction. <idx> may be any positive integer or one
18475 of the special value :
18476 * head : The oldest inserted block
18477 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050018478 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010018479
18480internal.htx_blk.type(<idx>) : string
18481 Returns the type of the block at the position <idx> in the HTX message
18482 associated to a channel or "HTX_BLK_UNUSED" if it does not exist. The channel
18483 is chosen depending on the sample direction. <idx> may be any positive
18484 integer or one of the special value :
18485 * head : The oldest inserted block
18486 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050018487 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010018488
18489internal.htx_blk.data(<idx>) : binary
18490 Returns the value of the DATA block at the position <idx> in the HTX message
18491 associated to a channel or an empty string if it does not exist or if it is
18492 not a DATA block. The channel is chosen depending on the sample direction.
18493 <idx> may be any positive integer or one of the special value :
18494
18495 * head : The oldest inserted block
18496 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050018497 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010018498
18499internal.htx_blk.hdrname(<idx>) : string
18500 Returns the header name of the HEADER block at the position <idx> in the HTX
18501 message associated to a channel or an empty string if it does not exist or if
18502 it is not an HEADER block. The channel is chosen depending on the sample
18503 direction. <idx> may be any positive integer or one of the special value :
18504
18505 * head : The oldest inserted block
18506 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050018507 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010018508
18509internal.htx_blk.hdrval(<idx>) : string
18510 Returns the header value of the HEADER block at the position <idx> in the HTX
18511 message associated to a channel or an empty string if it does not exist or if
18512 it is not an HEADER block. The channel is chosen depending on the sample
18513 direction. <idx> may be any positive integer or one of the special value :
18514
18515 * head : The oldest inserted block
18516 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050018517 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010018518
18519internal.htx_blk.start_line(<idx>) : string
18520 Returns the value of the REQ_SL or RES_SL block at the position <idx> in the
18521 HTX message associated to a channel or an empty string if it does not exist
18522 or if it is not a SL block. The channel is chosen depending on the sample
18523 direction. <idx> may be any positive integer or one of the special value :
18524
18525 * head : The oldest inserted block
18526 * tail : The newest inserted block
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050018527 * first : The first block where to (re)start the analysis
Christopher Fauletd47941d2020-01-08 14:40:19 +010018528
18529internal.strm.is_htx : boolean
18530 Returns true if the current stream is an HTX stream. It means the data in the
18531 channels buffers are stored using the internal HTX representation. Otherwise,
18532 it returns false.
18533
18534
Willy Tarreau74ca5042013-06-11 23:12:07 +0200185357.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018536---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010018537
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018538Some predefined ACLs are hard-coded so that they do not have to be declared in
18539every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020018540order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010018541
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018542ACL name Equivalent to Usage
18543---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018544FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020018545HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018546HTTP_1.0 req_ver 1.0 match HTTP version 1.0
18547HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010018548HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
18549HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
18550HTTP_URL_SLASH url_beg / match URL beginning with "/"
18551HTTP_URL_STAR url * match URL equal to "*"
18552LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018553METH_CONNECT method CONNECT match HTTP CONNECT method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020018554METH_DELETE method DELETE match HTTP DELETE method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018555METH_GET method GET HEAD match HTTP GET or HEAD method
18556METH_HEAD method HEAD match HTTP HEAD method
18557METH_OPTIONS method OPTIONS match HTTP OPTIONS method
18558METH_POST method POST match HTTP POST method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020018559METH_PUT method PUT match HTTP PUT method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018560METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020018561RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018562REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010018563TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018564WAIT_END wait_end wait for end of content analysis
18565---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010018566
Willy Tarreaub937b7e2010-01-12 15:27:54 +010018567
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200185688. Logging
18569----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010018570
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018571One of HAProxy's strong points certainly lies is its precise logs. It probably
18572provides the finest level of information available for such a product, which is
18573very important for troubleshooting complex environments. Standard information
18574provided in logs include client ports, TCP/HTTP state timers, precise session
18575state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010018576to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018577headers.
18578
18579In order to improve administrators reactivity, it offers a great transparency
18580about encountered problems, both internal and external, and it is possible to
18581send logs to different sources at the same time with different level filters :
18582
18583 - global process-level logs (system errors, start/stop, etc..)
18584 - per-instance system and internal errors (lack of resource, bugs, ...)
18585 - per-instance external troubles (servers up/down, max connections)
18586 - per-instance activity (client connections), either at the establishment or
18587 at the termination.
Davor Ocelice9ed2812017-12-25 17:49:28 +010018588 - per-request control of log-level, e.g.
Jim Freeman9e8714b2015-05-26 09:16:34 -060018589 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018590
18591The ability to distribute different levels of logs to different log servers
18592allow several production teams to interact and to fix their problems as soon
18593as possible. For example, the system team might monitor system-wide errors,
18594while the application team might be monitoring the up/down for their servers in
18595real time, and the security team might analyze the activity logs with one hour
18596delay.
18597
18598
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200185998.1. Log levels
18600---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018601
Simon Hormandf791f52011-05-29 15:01:10 +090018602TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018603source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090018604HTTP request, HTTP return code, number of bytes transmitted, conditions
18605in which the session ended, and even exchanged cookies values. For example
18606track a particular user's problems. All messages may be sent to up to two
18607syslog servers. Check the "log" keyword in section 4.2 for more information
18608about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018609
18610
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200186118.2. Log formats
18612----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018613
William Lallemand48940402012-01-30 16:47:22 +010018614HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090018615and will be detailed in the following sections. A few of them may vary
18616slightly with the configuration, due to indicators specific to certain
18617options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018618
18619 - the default format, which is very basic and very rarely used. It only
18620 provides very basic information about the incoming connection at the moment
18621 it is accepted : source IP:port, destination IP:port, and frontend-name.
18622 This mode will eventually disappear so it will not be described to great
18623 extents.
18624
18625 - the TCP format, which is more advanced. This format is enabled when "option
18626 tcplog" is set on the frontend. HAProxy will then usually wait for the
18627 connection to terminate before logging. This format provides much richer
18628 information, such as timers, connection counts, queue size, etc... This
18629 format is recommended for pure TCP proxies.
18630
18631 - the HTTP format, which is the most advanced for HTTP proxying. This format
18632 is enabled when "option httplog" is set on the frontend. It provides the
18633 same information as the TCP format with some HTTP-specific fields such as
18634 the request, the status code, and captures of headers and cookies. This
18635 format is recommended for HTTP proxies.
18636
Emeric Brun3a058f32009-06-30 18:26:00 +020018637 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
18638 fields arranged in the same order as the CLF format. In this mode, all
18639 timers, captures, flags, etc... appear one per field after the end of the
18640 common fields, in the same order they appear in the standard HTTP format.
18641
William Lallemand48940402012-01-30 16:47:22 +010018642 - the custom log format, allows you to make your own log line.
18643
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018644Next sections will go deeper into details for each of these formats. Format
18645specification will be performed on a "field" basis. Unless stated otherwise, a
18646field is a portion of text delimited by any number of spaces. Since syslog
18647servers are susceptible of inserting fields at the beginning of a line, it is
18648always assumed that the first field is the one containing the process name and
18649identifier.
18650
18651Note : Since log lines may be quite long, the log examples in sections below
18652 might be broken into multiple lines. The example log lines will be
18653 prefixed with 3 closing angle brackets ('>>>') and each time a log is
18654 broken into multiple lines, each non-final line will end with a
18655 backslash ('\') and the next line will start indented by two characters.
18656
18657
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200186588.2.1. Default log format
18659-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018660
18661This format is used when no specific option is set. The log is emitted as soon
18662as the connection is accepted. One should note that this currently is the only
18663format which logs the request's destination IP and ports.
18664
18665 Example :
18666 listen www
18667 mode http
18668 log global
18669 server srv1 127.0.0.1:8000
18670
18671 >>> Feb 6 12:12:09 localhost \
18672 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
18673 (www/HTTP)
18674
18675 Field Format Extract from the example above
18676 1 process_name '[' pid ']:' haproxy[14385]:
18677 2 'Connect from' Connect from
18678 3 source_ip ':' source_port 10.0.1.2:33312
18679 4 'to' to
18680 5 destination_ip ':' destination_port 10.0.3.31:8012
18681 6 '(' frontend_name '/' mode ')' (www/HTTP)
18682
18683Detailed fields description :
18684 - "source_ip" is the IP address of the client which initiated the connection.
18685 - "source_port" is the TCP port of the client which initiated the connection.
18686 - "destination_ip" is the IP address the client connected to.
18687 - "destination_port" is the TCP port the client connected to.
18688 - "frontend_name" is the name of the frontend (or listener) which received
18689 and processed the connection.
18690 - "mode is the mode the frontend is operating (TCP or HTTP).
18691
Willy Tarreauceb24bc2010-11-09 12:46:41 +010018692In case of a UNIX socket, the source and destination addresses are marked as
18693"unix:" and the ports reflect the internal ID of the socket which accepted the
18694connection (the same ID as reported in the stats).
18695
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018696It is advised not to use this deprecated format for newer installations as it
18697will eventually disappear.
18698
18699
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200187008.2.2. TCP log format
18701---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018702
18703The TCP format is used when "option tcplog" is specified in the frontend, and
18704is the recommended format for pure TCP proxies. It provides a lot of precious
18705information for troubleshooting. Since this format includes timers and byte
18706counts, the log is normally emitted at the end of the session. It can be
18707emitted earlier if "option logasap" is specified, which makes sense in most
18708environments with long sessions such as remote terminals. Sessions which match
18709the "monitor" rules are never logged. It is also possible not to emit logs for
18710sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020018711specifying "option dontlognull" in the frontend. Successful connections will
18712not be logged if "option dontlog-normal" is specified in the frontend. A few
18713fields may slightly vary depending on some configuration options, those are
18714marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018715
18716 Example :
18717 frontend fnt
18718 mode tcp
18719 option tcplog
18720 log global
18721 default_backend bck
18722
18723 backend bck
18724 server srv1 127.0.0.1:8000
18725
18726 >>> Feb 6 12:12:56 localhost \
18727 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
18728 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
18729
18730 Field Format Extract from the example above
18731 1 process_name '[' pid ']:' haproxy[14387]:
18732 2 client_ip ':' client_port 10.0.1.2:33313
18733 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
18734 4 frontend_name fnt
18735 5 backend_name '/' server_name bck/srv1
18736 6 Tw '/' Tc '/' Tt* 0/0/5007
18737 7 bytes_read* 212
18738 8 termination_state --
18739 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
18740 10 srv_queue '/' backend_queue 0/0
18741
18742Detailed fields description :
18743 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010018744 connection to haproxy. If the connection was accepted on a UNIX socket
18745 instead, the IP address would be replaced with the word "unix". Note that
18746 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010018747 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010018748 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010018749 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018750
18751 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010018752 If the connection was accepted on a UNIX socket instead, the port would be
18753 replaced with the ID of the accepting socket, which is also reported in the
18754 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018755
18756 - "accept_date" is the exact date when the connection was received by haproxy
18757 (which might be very slightly different from the date observed on the
18758 network if there was some queuing in the system's backlog). This is usually
Willy Tarreau590a0512018-09-05 11:56:48 +020018759 the same date which may appear in any upstream firewall's log. When used in
18760 HTTP mode, the accept_date field will be reset to the first moment the
18761 connection is ready to receive a new request (end of previous response for
18762 HTTP/1, immediately after previous request for HTTP/2).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018763
18764 - "frontend_name" is the name of the frontend (or listener) which received
18765 and processed the connection.
18766
18767 - "backend_name" is the name of the backend (or listener) which was selected
18768 to manage the connection to the server. This will be the same as the
18769 frontend if no switching rule has been applied, which is common for TCP
18770 applications.
18771
18772 - "server_name" is the name of the last server to which the connection was
18773 sent, which might differ from the first one if there were connection errors
18774 and a redispatch occurred. Note that this server belongs to the backend
18775 which processed the request. If the connection was aborted before reaching
18776 a server, "<NOSRV>" is indicated instead of a server name.
18777
18778 - "Tw" is the total time in milliseconds spent waiting in the various queues.
18779 It can be "-1" if the connection was aborted before reaching the queue.
18780 See "Timers" below for more details.
18781
18782 - "Tc" is the total time in milliseconds spent waiting for the connection to
18783 establish to the final server, including retries. It can be "-1" if the
18784 connection was aborted before a connection could be established. See
18785 "Timers" below for more details.
18786
18787 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030018788 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018789 "option logasap" was specified, then the time counting stops at the moment
18790 the log is emitted. In this case, a '+' sign is prepended before the value,
18791 indicating that the final one will be larger. See "Timers" below for more
18792 details.
18793
18794 - "bytes_read" is the total number of bytes transmitted from the server to
18795 the client when the log is emitted. If "option logasap" is specified, the
18796 this value will be prefixed with a '+' sign indicating that the final one
18797 may be larger. Please note that this value is a 64-bit counter, so log
18798 analysis tools must be able to handle it without overflowing.
18799
18800 - "termination_state" is the condition the session was in when the session
18801 ended. This indicates the session state, which side caused the end of
18802 session to happen, and for what reason (timeout, error, ...). The normal
18803 flags should be "--", indicating the session was closed by either end with
18804 no data remaining in buffers. See below "Session state at disconnection"
18805 for more details.
18806
18807 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040018808 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018809 limits have been reached. For instance, if actconn is close to 512 when
18810 multiple connection errors occur, chances are high that the system limits
18811 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018812 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018813
18814 - "feconn" is the total number of concurrent connections on the frontend when
18815 the session was logged. It is useful to estimate the amount of resource
18816 required to sustain high loads, and to detect when the frontend's "maxconn"
18817 has been reached. Most often when this value increases by huge jumps, it is
18818 because there is congestion on the backend servers, but sometimes it can be
18819 caused by a denial of service attack.
18820
18821 - "beconn" is the total number of concurrent connections handled by the
18822 backend when the session was logged. It includes the total number of
18823 concurrent connections active on servers as well as the number of
18824 connections pending in queues. It is useful to estimate the amount of
18825 additional servers needed to support high loads for a given application.
18826 Most often when this value increases by huge jumps, it is because there is
18827 congestion on the backend servers, but sometimes it can be caused by a
18828 denial of service attack.
18829
18830 - "srv_conn" is the total number of concurrent connections still active on
18831 the server when the session was logged. It can never exceed the server's
18832 configured "maxconn" parameter. If this value is very often close or equal
18833 to the server's "maxconn", it means that traffic regulation is involved a
18834 lot, meaning that either the server's maxconn value is too low, or that
18835 there aren't enough servers to process the load with an optimal response
18836 time. When only one of the server's "srv_conn" is high, it usually means
18837 that this server has some trouble causing the connections to take longer to
18838 be processed than on other servers.
18839
18840 - "retries" is the number of connection retries experienced by this session
18841 when trying to connect to the server. It must normally be zero, unless a
18842 server is being stopped at the same moment the connection was attempted.
18843 Frequent retries generally indicate either a network problem between
18844 haproxy and the server, or a misconfigured system backlog on the server
18845 preventing new connections from being queued. This field may optionally be
18846 prefixed with a '+' sign, indicating that the session has experienced a
18847 redispatch after the maximal retry count has been reached on the initial
18848 server. In this case, the server name appearing in the log is the one the
18849 connection was redispatched to, and not the first one, though both may
18850 sometimes be the same in case of hashing for instance. So as a general rule
18851 of thumb, when a '+' is present in front of the retry count, this count
18852 should not be attributed to the logged server.
18853
18854 - "srv_queue" is the total number of requests which were processed before
18855 this one in the server queue. It is zero when the request has not gone
18856 through the server queue. It makes it possible to estimate the approximate
18857 server's response time by dividing the time spent in queue by the number of
18858 requests in the queue. It is worth noting that if a session experiences a
18859 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010018860 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018861 backend queue unless a redispatch occurs.
18862
18863 - "backend_queue" is the total number of requests which were processed before
18864 this one in the backend's global queue. It is zero when the request has not
18865 gone through the global queue. It makes it possible to estimate the average
18866 queue length, which easily translates into a number of missing servers when
18867 divided by a server's "maxconn" parameter. It is worth noting that if a
18868 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010018869 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018870 through both the server queue and the backend queue unless a redispatch
18871 occurs.
18872
18873
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200188748.2.3. HTTP log format
18875----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018876
18877The HTTP format is the most complete and the best suited for HTTP proxies. It
18878is enabled by when "option httplog" is specified in the frontend. It provides
18879the same level of information as the TCP format with additional features which
18880are specific to the HTTP protocol. Just like the TCP format, the log is usually
18881emitted at the end of the session, unless "option logasap" is specified, which
18882generally only makes sense for download sites. A session which matches the
18883"monitor" rules will never logged. It is also possible not to log sessions for
18884which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020018885frontend. Successful connections will not be logged if "option dontlog-normal"
18886is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018887
18888Most fields are shared with the TCP log, some being different. A few fields may
18889slightly vary depending on some configuration options. Those ones are marked
18890with a star ('*') after the field name below.
18891
18892 Example :
18893 frontend http-in
18894 mode http
18895 option httplog
18896 log global
18897 default_backend bck
18898
18899 backend static
18900 server srv1 127.0.0.1:8000
18901
18902 >>> Feb 6 12:14:14 localhost \
18903 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
18904 static/srv1 10/0/30/69/109 200 2750 - - ---- 1/1/1/1/0 0/0 {1wt.eu} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010018905 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018906
18907 Field Format Extract from the example above
18908 1 process_name '[' pid ']:' haproxy[14389]:
18909 2 client_ip ':' client_port 10.0.1.2:33317
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020018910 3 '[' request_date ']' [06/Feb/2009:12:14:14.655]
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018911 4 frontend_name http-in
18912 5 backend_name '/' server_name static/srv1
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020018913 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018914 7 status_code 200
18915 8 bytes_read* 2750
18916 9 captured_request_cookie -
18917 10 captured_response_cookie -
18918 11 termination_state ----
18919 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
18920 13 srv_queue '/' backend_queue 0/0
18921 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
18922 15 '{' captured_response_headers* '}' {}
18923 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010018924
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018925Detailed fields description :
18926 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010018927 connection to haproxy. If the connection was accepted on a UNIX socket
18928 instead, the IP address would be replaced with the word "unix". Note that
18929 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010018930 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010018931 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010018932 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018933
18934 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010018935 If the connection was accepted on a UNIX socket instead, the port would be
18936 replaced with the ID of the accepting socket, which is also reported in the
18937 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018938
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020018939 - "request_date" is the exact date when the first byte of the HTTP request
18940 was received by haproxy (log field %tr).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018941
18942 - "frontend_name" is the name of the frontend (or listener) which received
18943 and processed the connection.
18944
18945 - "backend_name" is the name of the backend (or listener) which was selected
18946 to manage the connection to the server. This will be the same as the
18947 frontend if no switching rule has been applied.
18948
18949 - "server_name" is the name of the last server to which the connection was
18950 sent, which might differ from the first one if there were connection errors
18951 and a redispatch occurred. Note that this server belongs to the backend
18952 which processed the request. If the request was aborted before reaching a
18953 server, "<NOSRV>" is indicated instead of a server name. If the request was
18954 intercepted by the stats subsystem, "<STATS>" is indicated instead.
18955
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020018956 - "TR" is the total time in milliseconds spent waiting for a full HTTP
18957 request from the client (not counting body) after the first byte was
18958 received. It can be "-1" if the connection was aborted before a complete
John Roeslerfb2fce12019-07-10 15:45:51 -050018959 request could be received or a bad request was received. It should
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020018960 always be very small because a request generally fits in one single packet.
18961 Large times here generally indicate network issues between the client and
Willy Tarreau590a0512018-09-05 11:56:48 +020018962 haproxy or requests being typed by hand. See section 8.4 "Timing Events"
18963 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018964
18965 - "Tw" is the total time in milliseconds spent waiting in the various queues.
18966 It can be "-1" if the connection was aborted before reaching the queue.
Willy Tarreau590a0512018-09-05 11:56:48 +020018967 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018968
18969 - "Tc" is the total time in milliseconds spent waiting for the connection to
18970 establish to the final server, including retries. It can be "-1" if the
Willy Tarreau590a0512018-09-05 11:56:48 +020018971 request was aborted before a connection could be established. See section
18972 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018973
18974 - "Tr" is the total time in milliseconds spent waiting for the server to send
18975 a full HTTP response, not counting data. It can be "-1" if the request was
18976 aborted before a complete response could be received. It generally matches
18977 the server's processing time for the request, though it may be altered by
18978 the amount of data sent by the client to the server. Large times here on
Willy Tarreau590a0512018-09-05 11:56:48 +020018979 "GET" requests generally indicate an overloaded server. See section 8.4
18980 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018981
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020018982 - "Ta" is the time the request remained active in haproxy, which is the total
18983 time in milliseconds elapsed between the first byte of the request was
18984 received and the last byte of response was sent. It covers all possible
18985 processing except the handshake (see Th) and idle time (see Ti). There is
18986 one exception, if "option logasap" was specified, then the time counting
18987 stops at the moment the log is emitted. In this case, a '+' sign is
18988 prepended before the value, indicating that the final one will be larger.
Willy Tarreau590a0512018-09-05 11:56:48 +020018989 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018990
18991 - "status_code" is the HTTP status code returned to the client. This status
18992 is generally set by the server, but it might also be set by haproxy when
18993 the server cannot be reached or when its response is blocked by haproxy.
18994
18995 - "bytes_read" is the total number of bytes transmitted to the client when
18996 the log is emitted. This does include HTTP headers. If "option logasap" is
John Roeslerfb2fce12019-07-10 15:45:51 -050018997 specified, this value will be prefixed with a '+' sign indicating that
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018998 the final one may be larger. Please note that this value is a 64-bit
18999 counter, so log analysis tools must be able to handle it without
19000 overflowing.
19001
19002 - "captured_request_cookie" is an optional "name=value" entry indicating that
19003 the client had this cookie in the request. The cookie name and its maximum
19004 length are defined by the "capture cookie" statement in the frontend
19005 configuration. The field is a single dash ('-') when the option is not
19006 set. Only one cookie may be captured, it is generally used to track session
19007 ID exchanges between a client and a server to detect session crossing
19008 between clients due to application bugs. For more details, please consult
19009 the section "Capturing HTTP headers and cookies" below.
19010
19011 - "captured_response_cookie" is an optional "name=value" entry indicating
19012 that the server has returned a cookie with its response. The cookie name
19013 and its maximum length are defined by the "capture cookie" statement in the
19014 frontend configuration. The field is a single dash ('-') when the option is
19015 not set. Only one cookie may be captured, it is generally used to track
19016 session ID exchanges between a client and a server to detect session
19017 crossing between clients due to application bugs. For more details, please
19018 consult the section "Capturing HTTP headers and cookies" below.
19019
19020 - "termination_state" is the condition the session was in when the session
19021 ended. This indicates the session state, which side caused the end of
19022 session to happen, for what reason (timeout, error, ...), just like in TCP
19023 logs, and information about persistence operations on cookies in the last
19024 two characters. The normal flags should begin with "--", indicating the
19025 session was closed by either end with no data remaining in buffers. See
19026 below "Session state at disconnection" for more details.
19027
19028 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040019029 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019030 limits have been reached. For instance, if actconn is close to 512 or 1024
19031 when multiple connection errors occur, chances are high that the system
19032 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019033 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019034 system.
19035
19036 - "feconn" is the total number of concurrent connections on the frontend when
19037 the session was logged. It is useful to estimate the amount of resource
19038 required to sustain high loads, and to detect when the frontend's "maxconn"
19039 has been reached. Most often when this value increases by huge jumps, it is
19040 because there is congestion on the backend servers, but sometimes it can be
19041 caused by a denial of service attack.
19042
19043 - "beconn" is the total number of concurrent connections handled by the
19044 backend when the session was logged. It includes the total number of
19045 concurrent connections active on servers as well as the number of
19046 connections pending in queues. It is useful to estimate the amount of
19047 additional servers needed to support high loads for a given application.
19048 Most often when this value increases by huge jumps, it is because there is
19049 congestion on the backend servers, but sometimes it can be caused by a
19050 denial of service attack.
19051
19052 - "srv_conn" is the total number of concurrent connections still active on
19053 the server when the session was logged. It can never exceed the server's
19054 configured "maxconn" parameter. If this value is very often close or equal
19055 to the server's "maxconn", it means that traffic regulation is involved a
19056 lot, meaning that either the server's maxconn value is too low, or that
19057 there aren't enough servers to process the load with an optimal response
19058 time. When only one of the server's "srv_conn" is high, it usually means
19059 that this server has some trouble causing the requests to take longer to be
19060 processed than on other servers.
19061
19062 - "retries" is the number of connection retries experienced by this session
19063 when trying to connect to the server. It must normally be zero, unless a
19064 server is being stopped at the same moment the connection was attempted.
19065 Frequent retries generally indicate either a network problem between
19066 haproxy and the server, or a misconfigured system backlog on the server
19067 preventing new connections from being queued. This field may optionally be
19068 prefixed with a '+' sign, indicating that the session has experienced a
19069 redispatch after the maximal retry count has been reached on the initial
19070 server. In this case, the server name appearing in the log is the one the
19071 connection was redispatched to, and not the first one, though both may
19072 sometimes be the same in case of hashing for instance. So as a general rule
19073 of thumb, when a '+' is present in front of the retry count, this count
19074 should not be attributed to the logged server.
19075
19076 - "srv_queue" is the total number of requests which were processed before
19077 this one in the server queue. It is zero when the request has not gone
19078 through the server queue. It makes it possible to estimate the approximate
19079 server's response time by dividing the time spent in queue by the number of
19080 requests in the queue. It is worth noting that if a session experiences a
19081 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010019082 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019083 backend queue unless a redispatch occurs.
19084
19085 - "backend_queue" is the total number of requests which were processed before
19086 this one in the backend's global queue. It is zero when the request has not
19087 gone through the global queue. It makes it possible to estimate the average
19088 queue length, which easily translates into a number of missing servers when
19089 divided by a server's "maxconn" parameter. It is worth noting that if a
19090 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010019091 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019092 through both the server queue and the backend queue unless a redispatch
19093 occurs.
19094
19095 - "captured_request_headers" is a list of headers captured in the request due
19096 to the presence of the "capture request header" statement in the frontend.
19097 Multiple headers can be captured, they will be delimited by a vertical bar
19098 ('|'). When no capture is enabled, the braces do not appear, causing a
19099 shift of remaining fields. It is important to note that this field may
19100 contain spaces, and that using it requires a smarter log parser than when
19101 it's not used. Please consult the section "Capturing HTTP headers and
19102 cookies" below for more details.
19103
19104 - "captured_response_headers" is a list of headers captured in the response
19105 due to the presence of the "capture response header" statement in the
19106 frontend. Multiple headers can be captured, they will be delimited by a
19107 vertical bar ('|'). When no capture is enabled, the braces do not appear,
19108 causing a shift of remaining fields. It is important to note that this
19109 field may contain spaces, and that using it requires a smarter log parser
19110 than when it's not used. Please consult the section "Capturing HTTP headers
19111 and cookies" below for more details.
19112
19113 - "http_request" is the complete HTTP request line, including the method,
19114 request and HTTP version string. Non-printable characters are encoded (see
19115 below the section "Non-printable characters"). This is always the last
19116 field, and it is always delimited by quotes and is the only one which can
19117 contain quotes. If new fields are added to the log format, they will be
19118 added before this field. This field might be truncated if the request is
19119 huge and does not fit in the standard syslog buffer (1024 characters). This
19120 is the reason why this field must always remain the last one.
19121
19122
Cyril Bontédc4d9032012-04-08 21:57:39 +0200191238.2.4. Custom log format
19124------------------------
William Lallemand48940402012-01-30 16:47:22 +010019125
Willy Tarreau2beef582012-12-20 17:22:52 +010019126The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010019127mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010019128
Davor Ocelice9ed2812017-12-25 17:49:28 +010019129HAProxy understands some log format variables. % precedes log format variables.
William Lallemand48940402012-01-30 16:47:22 +010019130Variables can take arguments using braces ('{}'), and multiple arguments are
19131separated by commas within the braces. Flags may be added or removed by
19132prefixing them with a '+' or '-' sign.
19133
19134Special variable "%o" may be used to propagate its flags to all other
19135variables on the same format string. This is particularly handy with quoted
Dragan Dosen835b9212016-02-12 13:23:03 +010019136("Q") and escaped ("E") string formats.
William Lallemand48940402012-01-30 16:47:22 +010019137
Willy Tarreauc8368452012-12-21 00:09:23 +010019138If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020019139as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010019140less common information such as the client's SSL certificate's DN, or to log
19141the key that would be used to store an entry into a stick table.
19142
Dragan Dosen1e3b16f2020-06-23 18:16:44 +020019143Note: spaces must be escaped. In configuration directives "log-format",
19144"log-format-sd" and "unique-id-format", spaces are considered as
19145delimiters and are merged. In order to emit a verbatim '%', it must be
19146preceded by another '%' resulting in '%%'.
William Lallemand48940402012-01-30 16:47:22 +010019147
Dragan Dosen835b9212016-02-12 13:23:03 +010019148Note: when using the RFC5424 syslog message format, the characters '"',
19149'\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see
19150https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In
19151such cases, the use of the flag "E" should be considered.
19152
William Lallemand48940402012-01-30 16:47:22 +010019153Flags are :
19154 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040019155 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
Dragan Dosen835b9212016-02-12 13:23:03 +010019156 * E: escape characters '"', '\' and ']' in a string with '\' as prefix
19157 (intended purpose is for the RFC5424 structured-data log formats)
William Lallemand48940402012-01-30 16:47:22 +010019158
19159 Example:
19160
19161 log-format %T\ %t\ Some\ Text
19162 log-format %{+Q}o\ %t\ %s\ %{-Q}r
19163
Dragan Dosen835b9212016-02-12 13:23:03 +010019164 log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]
19165
William Lallemand48940402012-01-30 16:47:22 +010019166At the moment, the default HTTP format is defined this way :
19167
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019168 log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \
19169 %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"
William Lallemand48940402012-01-30 16:47:22 +010019170
William Lallemandbddd4fd2012-02-27 11:23:10 +010019171the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010019172
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019173 log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \
19174 %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \
19175 %bc %sc %rc %sq %bq %CC %CS %hrl %hsl"
William Lallemand48940402012-01-30 16:47:22 +010019176
William Lallemandbddd4fd2012-02-27 11:23:10 +010019177and the default TCP format is defined this way :
19178
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019179 log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \
19180 %ac/%fc/%bc/%sc/%rc %sq/%bq"
William Lallemandbddd4fd2012-02-27 11:23:10 +010019181
William Lallemand48940402012-01-30 16:47:22 +010019182Please refer to the table below for currently defined variables :
19183
William Lallemandbddd4fd2012-02-27 11:23:10 +010019184 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020019185 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019186 +---+------+-----------------------------------------------+-------------+
19187 | | %o | special variable, apply flags on all next var | |
19188 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010019189 | | %B | bytes_read (from server to client) | numeric |
19190 | H | %CC | captured_request_cookie | string |
19191 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020019192 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000019193 | H | %HM | HTTP method (ex: POST) | string |
19194 | H | %HP | HTTP request URI without query string (path) | string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000019195 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000019196 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
19197 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010019198 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020019199 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020019200 | | %T | gmt_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019201 | | %Ta | Active time of the request (from TR to end) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019202 | | %Tc | Tc | numeric |
Willy Tarreau27b639d2016-05-17 17:55:27 +020019203 | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080019204 | | %Tl | local_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019205 | | %Th | connection handshake time (SSL, PROXY proto) | numeric |
19206 | H | %Ti | idle time before the HTTP request | numeric |
19207 | H | %Tq | Th + Ti + TR | numeric |
19208 | H | %TR | time to receive the full request from 1st byte| numeric |
19209 | H | %Tr | Tr (response time) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020019210 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019211 | | %Tt | Tt | numeric |
Damien Claisse57c8eb92020-04-28 12:09:19 +000019212 | | %Tu | Tu | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019213 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010019214 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019215 | | %ac | actconn | numeric |
19216 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010019217 | | %bc | beconn (backend concurrent connections) | numeric |
19218 | | %bi | backend_source_ip (connecting address) | IP |
19219 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019220 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010019221 | | %ci | client_ip (accepted address) | IP |
19222 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019223 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010019224 | | %fc | feconn (frontend concurrent connections) | numeric |
19225 | | %fi | frontend_ip (accepting address) | IP |
19226 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020019227 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020019228 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020019229 | | %hr | captured_request_headers default style | string |
19230 | | %hrl | captured_request_headers CLF style | string list |
19231 | | %hs | captured_response_headers default style | string |
19232 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020019233 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020019234 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020019235 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019236 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010019237 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019238 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010019239 | | %sc | srv_conn (server concurrent connections) | numeric |
19240 | | %si | server_IP (target address) | IP |
19241 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019242 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020019243 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
19244 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010019245 | | %t | date_time (with millisecond resolution) | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019246 | H | %tr | date_time of HTTP request | date |
19247 | H | %trg | gmt_date_time of start of HTTP request | date |
Jens Bissinger15c64ff2018-08-23 14:11:27 +020019248 | H | %trl | local_date_time of start of HTTP request | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019249 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020019250 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010019251 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010019252
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020019253 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010019254
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010019255
192568.2.5. Error log format
19257-----------------------
19258
19259When an incoming connection fails due to an SSL handshake or an invalid PROXY
19260protocol header, haproxy will log the event using a shorter, fixed line format.
19261By default, logs are emitted at the LOG_INFO level, unless the option
19262"log-separate-errors" is set in the backend, in which case the LOG_ERR level
Davor Ocelice9ed2812017-12-25 17:49:28 +010019263will be used. Connections on which no data are exchanged (e.g. probes) are not
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010019264logged if the "dontlognull" option is set.
19265
19266The format looks like this :
19267
19268 >>> Dec 3 18:27:14 localhost \
19269 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
19270 Connection error during SSL handshake
19271
19272 Field Format Extract from the example above
19273 1 process_name '[' pid ']:' haproxy[6103]:
19274 2 client_ip ':' client_port 127.0.0.1:56059
19275 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
19276 4 frontend_name "/" bind_name ":" frt/f1:
19277 5 message Connection error during SSL handshake
19278
19279These fields just provide minimal information to help debugging connection
19280failures.
19281
19282
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200192838.3. Advanced logging options
19284-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019285
19286Some advanced logging options are often looked for but are not easy to find out
19287just by looking at the various options. Here is an entry point for the few
19288options which can enable better logging. Please refer to the keywords reference
19289for more information about their usage.
19290
19291
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200192928.3.1. Disabling logging of external tests
19293------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019294
19295It is quite common to have some monitoring tools perform health checks on
19296haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
19297commercial load-balancer, and sometimes it will simply be a more complete
19298monitoring system such as Nagios. When the tests are very frequent, users often
19299ask how to disable logging for those checks. There are three possibilities :
19300
19301 - if connections come from everywhere and are just TCP probes, it is often
19302 desired to simply disable logging of connections without data exchange, by
19303 setting "option dontlognull" in the frontend. It also disables logging of
19304 port scans, which may or may not be desired.
19305
19306 - if the connection come from a known source network, use "monitor-net" to
19307 declare this network as monitoring only. Any host in this network will then
19308 only be able to perform health checks, and their requests will not be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030019309 logged. This is generally appropriate to designate a list of equipment
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019310 such as other load-balancers.
19311
19312 - if the tests are performed on a known URI, use "monitor-uri" to declare
19313 this URI as dedicated to monitoring. Any host sending this request will
19314 only get the result of a health-check, and the request will not be logged.
19315
19316
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200193178.3.2. Logging before waiting for the session to terminate
19318----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019319
19320The problem with logging at end of connection is that you have no clue about
19321what is happening during very long sessions, such as remote terminal sessions
19322or large file downloads. This problem can be worked around by specifying
Davor Ocelice9ed2812017-12-25 17:49:28 +010019323"option logasap" in the frontend. HAProxy will then log as soon as possible,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019324just before data transfer begins. This means that in case of TCP, it will still
19325log the connection status to the server, and in case of HTTP, it will log just
19326after processing the server headers. In this case, the number of bytes reported
19327is the number of header bytes sent to the client. In order to avoid confusion
19328with normal logs, the total time field and the number of bytes are prefixed
19329with a '+' sign which means that real numbers are certainly larger.
19330
19331
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200193328.3.3. Raising log level upon errors
19333------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020019334
19335Sometimes it is more convenient to separate normal traffic from errors logs,
19336for instance in order to ease error monitoring from log files. When the option
19337"log-separate-errors" is used, connections which experience errors, timeouts,
19338retries, redispatches or HTTP status codes 5xx will see their syslog level
19339raised from "info" to "err". This will help a syslog daemon store the log in
19340a separate file. It is very important to keep the errors in the normal traffic
19341file too, so that log ordering is not altered. You should also be careful if
19342you already have configured your syslog daemon to store all logs higher than
19343"notice" in an "admin" file, because the "err" level is higher than "notice".
19344
19345
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200193468.3.4. Disabling logging of successful connections
19347--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020019348
19349Although this may sound strange at first, some large sites have to deal with
19350multiple thousands of logs per second and are experiencing difficulties keeping
19351them intact for a long time or detecting errors within them. If the option
19352"dontlog-normal" is set on the frontend, all normal connections will not be
19353logged. In this regard, a normal connection is defined as one without any
19354error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
19355and a response with a status 5xx is not considered normal and will be logged
19356too. Of course, doing is is really discouraged as it will remove most of the
19357useful information from the logs. Do this only if you have no other
19358alternative.
19359
19360
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200193618.4. Timing events
19362------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019363
19364Timers provide a great help in troubleshooting network problems. All values are
19365reported in milliseconds (ms). These timers should be used in conjunction with
19366the session termination flags. In TCP mode with "option tcplog" set on the
19367frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019368mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In
19369addition, three other measures are provided, "Th", "Ti", and "Tq".
19370
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010019371Timings events in HTTP mode:
19372
19373 first request 2nd request
19374 |<-------------------------------->|<-------------- ...
19375 t tr t tr ...
19376 ---|----|----|----|----|----|----|----|----|--
19377 : Th Ti TR Tw Tc Tr Td : Ti ...
19378 :<---- Tq ---->: :
19379 :<-------------- Tt -------------->:
Damien Claisse57c8eb92020-04-28 12:09:19 +000019380 :<-- -----Tu--------------->:
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010019381 :<--------- Ta --------->:
19382
19383Timings events in TCP mode:
19384
19385 TCP session
19386 |<----------------->|
19387 t t
19388 ---|----|----|----|----|---
19389 | Th Tw Tc Td |
19390 |<------ Tt ------->|
19391
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019392 - Th: total time to accept tcp connection and execute handshakes for low level
Davor Ocelice9ed2812017-12-25 17:49:28 +010019393 protocols. Currently, these protocols are proxy-protocol and SSL. This may
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019394 only happen once during the whole connection's lifetime. A large time here
19395 may indicate that the client only pre-established the connection without
19396 speaking, that it is experiencing network issues preventing it from
Davor Ocelice9ed2812017-12-25 17:49:28 +010019397 completing a handshake in a reasonable time (e.g. MTU issues), or that an
Willy Tarreau590a0512018-09-05 11:56:48 +020019398 SSL handshake was very expensive to compute. Please note that this time is
19399 reported only before the first request, so it is safe to average it over
19400 all request to calculate the amortized value. The second and subsequent
19401 request will always report zero here.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019402
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019403 - Ti: is the idle time before the HTTP request (HTTP mode only). This timer
19404 counts between the end of the handshakes and the first byte of the HTTP
19405 request. When dealing with a second request in keep-alive mode, it starts
Willy Tarreau590a0512018-09-05 11:56:48 +020019406 to count after the end of the transmission the previous response. When a
19407 multiplexed protocol such as HTTP/2 is used, it starts to count immediately
19408 after the previous request. Some browsers pre-establish connections to a
19409 server in order to reduce the latency of a future request, and keep them
19410 pending until they need it. This delay will be reported as the idle time. A
19411 value of -1 indicates that nothing was received on the connection.
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019412
19413 - TR: total time to get the client request (HTTP mode only). It's the time
19414 elapsed between the first bytes received and the moment the proxy received
19415 the empty line marking the end of the HTTP headers. The value "-1"
19416 indicates that the end of headers has never been seen. This happens when
19417 the client closes prematurely or times out. This time is usually very short
19418 since most requests fit in a single packet. A large time may indicate a
19419 request typed by hand during a test.
19420
19421 - Tq: total time to get the client request from the accept date or since the
19422 emission of the last byte of the previous response (HTTP mode only). It's
Davor Ocelice9ed2812017-12-25 17:49:28 +010019423 exactly equal to Th + Ti + TR unless any of them is -1, in which case it
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019424 returns -1 as well. This timer used to be very useful before the arrival of
19425 HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop
19426 it in favor of TR nowadays, as the idle time adds a lot of noise to the
19427 reports.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019428
19429 - Tw: total time spent in the queues waiting for a connection slot. It
19430 accounts for backend queue as well as the server queues, and depends on the
19431 queue size, and the time needed for the server to complete previous
19432 requests. The value "-1" means that the request was killed before reaching
19433 the queue, which is generally what happens with invalid or denied requests.
19434
19435 - Tc: total time to establish the TCP connection to the server. It's the time
19436 elapsed between the moment the proxy sent the connection request, and the
19437 moment it was acknowledged by the server, or between the TCP SYN packet and
19438 the matching SYN/ACK packet in return. The value "-1" means that the
19439 connection never established.
19440
19441 - Tr: server response time (HTTP mode only). It's the time elapsed between
19442 the moment the TCP connection was established to the server and the moment
19443 the server sent its complete response headers. It purely shows its request
19444 processing time, without the network overhead due to the data transmission.
19445 It is worth noting that when the client has data to send to the server, for
19446 instance during a POST request, the time already runs, and this can distort
19447 apparent response time. For this reason, it's generally wise not to trust
19448 too much this field for POST requests initiated from clients behind an
19449 untrusted network. A value of "-1" here means that the last the response
19450 header (empty line) was never seen, most likely because the server timeout
19451 stroke before the server managed to process the request.
19452
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019453 - Ta: total active time for the HTTP request, between the moment the proxy
19454 received the first byte of the request header and the emission of the last
19455 byte of the response body. The exception is when the "logasap" option is
19456 specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with
19457 a '+' sign. From this field, we can deduce "Td", the data transmission time,
19458 by subtracting other timers when valid :
19459
19460 Td = Ta - (TR + Tw + Tc + Tr)
19461
19462 Timers with "-1" values have to be excluded from this equation. Note that
19463 "Ta" can never be negative.
19464
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019465 - Tt: total session duration time, between the moment the proxy accepted it
19466 and the moment both ends were closed. The exception is when the "logasap"
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019467 option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and
19468 is prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030019469 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019470
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019471 Td = Tt - (Th + Ti + TR + Tw + Tc + Tr)
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019472
19473 Timers with "-1" values have to be excluded from this equation. In TCP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019474 mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never
19475 be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019476
Damien Claisse57c8eb92020-04-28 12:09:19 +000019477 - Tu: total estimated time as seen from client, between the moment the proxy
19478 accepted it and the moment both ends were closed, without idle time.
19479 This is useful to roughly measure end-to-end time as a user would see it,
19480 without idle time pollution from keep-alive time between requests. This
19481 timer in only an estimation of time seen by user as it assumes network
19482 latency is the same in both directions. The exception is when the "logasap"
19483 option is specified. In this case, it only equals (Th+TR+Tw+Tc+Tr), and is
19484 prefixed with a '+' sign.
19485
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019486These timers provide precious indications on trouble causes. Since the TCP
19487protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
19488that timers close to multiples of 3s are nearly always related to lost packets
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019489due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or
19490"Tt" is close to a timeout value specified in the configuration, it often means
19491that a session has been aborted on timeout.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019492
19493Most common cases :
19494
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019495 - If "Th" or "Ti" are close to 3000, a packet has probably been lost between
19496 the client and the proxy. This is very rare on local networks but might
19497 happen when clients are on far remote networks and send large requests. It
19498 may happen that values larger than usual appear here without any network
19499 cause. Sometimes, during an attack or just after a resource starvation has
19500 ended, haproxy may accept thousands of connections in a few milliseconds.
19501 The time spent accepting these connections will inevitably slightly delay
19502 processing of other connections, and it can happen that request times in the
19503 order of a few tens of milliseconds are measured after a few thousands of
19504 new connections have been accepted at once. Using one of the keep-alive
19505 modes may display larger idle times since "Ti" measures the time spent
Patrick Mezard105faca2010-06-12 17:02:46 +020019506 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019507
19508 - If "Tc" is close to 3000, a packet has probably been lost between the
19509 server and the proxy during the server connection phase. This value should
19510 always be very low, such as 1 ms on local networks and less than a few tens
19511 of ms on remote networks.
19512
Willy Tarreau55165fe2009-05-10 12:02:55 +020019513 - If "Tr" is nearly always lower than 3000 except some rare values which seem
19514 to be the average majored by 3000, there are probably some packets lost
19515 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019516
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019517 - If "Ta" is large even for small byte counts, it generally is because
19518 neither the client nor the server decides to close the connection while
19519 haproxy is running in tunnel mode and both have agreed on a keep-alive
19520 connection mode. In order to solve this issue, it will be needed to specify
19521 one of the HTTP options to manipulate keep-alive or close options on either
19522 the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is
19523 important when connection regulation is used with the "maxconn" option on
19524 the servers, since no new connection will be sent to the server until
19525 another one is released.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019526
19527Other noticeable HTTP log cases ('xx' means any value to be ignored) :
19528
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019529 TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019530 was emitted before the data phase. All the timers are valid
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019531 except "Ta" which is shorter than reality.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019532
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019533 -1/xx/xx/xx/Ta The client was not able to send a complete request in time
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019534 or it aborted too early. Check the session termination flags
19535 then "timeout http-request" and "timeout client" settings.
19536
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019537 TR/-1/xx/xx/Ta It was not possible to process the request, maybe because
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019538 servers were out of order, because the request was invalid
19539 or forbidden by ACL rules. Check the session termination
19540 flags.
19541
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019542 TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it
19543 actively refused it or it timed out after Ta-(TR+Tw) ms.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019544 Check the session termination flags, then check the
19545 "timeout connect" setting. Note that the tarpit action might
19546 return similar-looking patterns, with "Tw" equal to the time
19547 the client connection was maintained open.
19548
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019549 TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030019550 a complete response in time, or it closed its connection
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020019551 unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019552 termination flags, then check the "timeout server" setting.
19553
19554
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200195558.5. Session state at disconnection
19556-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019557
19558TCP and HTTP logs provide a session termination indicator in the
19559"termination_state" field, just before the number of active connections. It is
195602-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
19561each of which has a special meaning :
19562
19563 - On the first character, a code reporting the first event which caused the
19564 session to terminate :
19565
19566 C : the TCP session was unexpectedly aborted by the client.
19567
19568 S : the TCP session was unexpectedly aborted by the server, or the
19569 server explicitly refused it.
19570
19571 P : the session was prematurely aborted by the proxy, because of a
19572 connection limit enforcement, because a DENY filter was matched,
19573 because of a security check which detected and blocked a dangerous
19574 error in server response which might have caused information leak
Davor Ocelice9ed2812017-12-25 17:49:28 +010019575 (e.g. cacheable cookie).
Willy Tarreau570f2212013-06-10 16:42:09 +020019576
19577 L : the session was locally processed by haproxy and was not passed to
19578 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019579
19580 R : a resource on the proxy has been exhausted (memory, sockets, source
19581 ports, ...). Usually, this appears during the connection phase, and
19582 system logs should contain a copy of the precise error. If this
19583 happens, it must be considered as a very serious anomaly which
19584 should be fixed as soon as possible by any means.
19585
19586 I : an internal error was identified by the proxy during a self-check.
19587 This should NEVER happen, and you are encouraged to report any log
19588 containing this, because this would almost certainly be a bug. It
19589 would be wise to preventively restart the process after such an
19590 event too, in case it would be caused by memory corruption.
19591
Simon Horman752dc4a2011-06-21 14:34:59 +090019592 D : the session was killed by haproxy because the server was detected
19593 as down and was configured to kill all connections when going down.
19594
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070019595 U : the session was killed by haproxy on this backup server because an
19596 active server was detected as up and was configured to kill all
19597 backup connections when going up.
19598
Willy Tarreaua2a64e92011-09-07 23:01:56 +020019599 K : the session was actively killed by an admin operating on haproxy.
19600
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019601 c : the client-side timeout expired while waiting for the client to
19602 send or receive data.
19603
19604 s : the server-side timeout expired while waiting for the server to
19605 send or receive data.
19606
19607 - : normal session completion, both the client and the server closed
19608 with nothing left in the buffers.
19609
19610 - on the second character, the TCP or HTTP session state when it was closed :
19611
Willy Tarreauf7b30a92010-12-06 22:59:17 +010019612 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019613 (HTTP mode only). Nothing was sent to any server.
19614
19615 Q : the proxy was waiting in the QUEUE for a connection slot. This can
19616 only happen when servers have a 'maxconn' parameter set. It can
19617 also happen in the global queue after a redispatch consecutive to
19618 a failed attempt to connect to a dying server. If no redispatch is
19619 reported, then no connection attempt was made to any server.
19620
19621 C : the proxy was waiting for the CONNECTION to establish on the
19622 server. The server might at most have noticed a connection attempt.
19623
19624 H : the proxy was waiting for complete, valid response HEADERS from the
19625 server (HTTP only).
19626
19627 D : the session was in the DATA phase.
19628
19629 L : the proxy was still transmitting LAST data to the client while the
19630 server had already finished. This one is very rare as it can only
19631 happen when the client dies while receiving the last packets.
19632
19633 T : the request was tarpitted. It has been held open with the client
19634 during the whole "timeout tarpit" duration or until the client
19635 closed, both of which will be reported in the "Tw" timer.
19636
19637 - : normal session completion after end of data transfer.
19638
19639 - the third character tells whether the persistence cookie was provided by
19640 the client (only in HTTP mode) :
19641
19642 N : the client provided NO cookie. This is usually the case for new
19643 visitors, so counting the number of occurrences of this flag in the
19644 logs generally indicate a valid trend for the site frequentation.
19645
19646 I : the client provided an INVALID cookie matching no known server.
19647 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020019648 cookies between HTTP/HTTPS sites, persistence conditionally
19649 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019650
19651 D : the client provided a cookie designating a server which was DOWN,
19652 so either "option persist" was used and the client was sent to
19653 this server, or it was not set and the client was redispatched to
19654 another server.
19655
Willy Tarreau996a92c2010-10-13 19:30:47 +020019656 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019657 server.
19658
Willy Tarreau996a92c2010-10-13 19:30:47 +020019659 E : the client provided a valid cookie, but with a last date which was
19660 older than what is allowed by the "maxidle" cookie parameter, so
19661 the cookie is consider EXPIRED and is ignored. The request will be
19662 redispatched just as if there was no cookie.
19663
19664 O : the client provided a valid cookie, but with a first date which was
19665 older than what is allowed by the "maxlife" cookie parameter, so
19666 the cookie is consider too OLD and is ignored. The request will be
19667 redispatched just as if there was no cookie.
19668
Willy Tarreauc89ccb62012-04-05 21:18:22 +020019669 U : a cookie was present but was not used to select the server because
19670 some other server selection mechanism was used instead (typically a
19671 "use-server" rule).
19672
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019673 - : does not apply (no cookie set in configuration).
19674
19675 - the last character reports what operations were performed on the persistence
19676 cookie returned by the server (only in HTTP mode) :
19677
19678 N : NO cookie was provided by the server, and none was inserted either.
19679
19680 I : no cookie was provided by the server, and the proxy INSERTED one.
19681 Note that in "cookie insert" mode, if the server provides a cookie,
19682 it will still be overwritten and reported as "I" here.
19683
Willy Tarreau996a92c2010-10-13 19:30:47 +020019684 U : the proxy UPDATED the last date in the cookie that was presented by
19685 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030019686 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020019687 date indicated in the cookie. If any other change happens, such as
19688 a redispatch, then the cookie will be marked as inserted instead.
19689
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019690 P : a cookie was PROVIDED by the server and transmitted as-is.
19691
19692 R : the cookie provided by the server was REWRITTEN by the proxy, which
19693 happens in "cookie rewrite" or "cookie prefix" modes.
19694
19695 D : the cookie provided by the server was DELETED by the proxy.
19696
19697 - : does not apply (no cookie set in configuration).
19698
Willy Tarreau996a92c2010-10-13 19:30:47 +020019699The combination of the two first flags gives a lot of information about what
19700was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019701helpful to detect server saturation, network troubles, local system resource
19702starvation, attacks, etc...
19703
19704The most common termination flags combinations are indicated below. They are
19705alphabetically sorted, with the lowercase set just after the upper case for
19706easier finding and understanding.
19707
19708 Flags Reason
19709
19710 -- Normal termination.
19711
19712 CC The client aborted before the connection could be established to the
19713 server. This can happen when haproxy tries to connect to a recently
19714 dead (or unchecked) server, and the client aborts while haproxy is
19715 waiting for the server to respond or for "timeout connect" to expire.
19716
19717 CD The client unexpectedly aborted during data transfer. This can be
19718 caused by a browser crash, by an intermediate equipment between the
19719 client and haproxy which decided to actively break the connection,
19720 by network routing issues between the client and haproxy, or by a
19721 keep-alive session between the server and the client terminated first
19722 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010019723
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019724 cD The client did not send nor acknowledge any data for as long as the
19725 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020019726 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019727
19728 CH The client aborted while waiting for the server to start responding.
19729 It might be the server taking too long to respond or the client
19730 clicking the 'Stop' button too fast.
19731
19732 cH The "timeout client" stroke while waiting for client data during a
19733 POST request. This is sometimes caused by too large TCP MSS values
19734 for PPPoE networks which cannot transport full-sized packets. It can
19735 also happen when client timeout is smaller than server timeout and
19736 the server takes too long to respond.
19737
19738 CQ The client aborted while its session was queued, waiting for a server
19739 with enough empty slots to accept it. It might be that either all the
19740 servers were saturated or that the assigned server was taking too
19741 long a time to respond.
19742
19743 CR The client aborted before sending a full HTTP request. Most likely
19744 the request was typed by hand using a telnet client, and aborted
19745 too early. The HTTP status code is likely a 400 here. Sometimes this
19746 might also be caused by an IDS killing the connection between haproxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020019747 and the client. "option http-ignore-probes" can be used to ignore
19748 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019749
19750 cR The "timeout http-request" stroke before the client sent a full HTTP
19751 request. This is sometimes caused by too large TCP MSS values on the
19752 client side for PPPoE networks which cannot transport full-sized
19753 packets, or by clients sending requests by hand and not typing fast
19754 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020019755 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020019756 some browsers started to implement a "pre-connect" feature consisting
19757 in speculatively connecting to some recently visited web sites just
19758 in case the user would like to visit them. This results in many
19759 connections being established to web sites, which end up in 408
19760 Request Timeout if the timeout strikes first, or 400 Bad Request when
19761 the browser decides to close them first. These ones pollute the log
19762 and feed the error counters. Some versions of some browsers have even
19763 been reported to display the error code. It is possible to work
Davor Ocelice9ed2812017-12-25 17:49:28 +010019764 around the undesirable effects of this behavior by adding "option
Willy Tarreau0f228a02015-05-01 15:37:53 +020019765 http-ignore-probes" in the frontend, resulting in connections with
19766 zero data transfer to be totally ignored. This will definitely hide
19767 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019768
19769 CT The client aborted while its session was tarpitted. It is important to
19770 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020019771 wrong tarpit rules have been written. If a lot of them happen, it
19772 might make sense to lower the "timeout tarpit" value to something
19773 closer to the average reported "Tw" timer, in order not to consume
19774 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019775
Willy Tarreau570f2212013-06-10 16:42:09 +020019776 LR The request was intercepted and locally handled by haproxy. Generally
19777 it means that this was a redirect or a stats request.
19778
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010019779 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019780 the TCP connection (the proxy received a TCP RST or an ICMP message
19781 in return). Under some circumstances, it can also be the network
Davor Ocelice9ed2812017-12-25 17:49:28 +010019782 stack telling the proxy that the server is unreachable (e.g. no route,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019783 or no ARP response on local network). When this happens in HTTP mode,
19784 the status code is likely a 502 or 503 here.
19785
19786 sC The "timeout connect" stroke before a connection to the server could
19787 complete. When this happens in HTTP mode, the status code is likely a
19788 503 or 504 here.
19789
19790 SD The connection to the server died with an error during the data
19791 transfer. This usually means that haproxy has received an RST from
19792 the server or an ICMP message from an intermediate equipment while
19793 exchanging data with the server. This can be caused by a server crash
19794 or by a network issue on an intermediate equipment.
19795
19796 sD The server did not send nor acknowledge any data for as long as the
19797 "timeout server" setting during the data phase. This is often caused
Davor Ocelice9ed2812017-12-25 17:49:28 +010019798 by too short timeouts on L4 equipment before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019799 load-balancers, ...), as well as keep-alive sessions maintained
19800 between the client and the server expiring first on haproxy.
19801
19802 SH The server aborted before sending its full HTTP response headers, or
19803 it crashed while processing the request. Since a server aborting at
19804 this moment is very rare, it would be wise to inspect its logs to
19805 control whether it crashed and why. The logged request may indicate a
19806 small set of faulty requests, demonstrating bugs in the application.
19807 Sometimes this might also be caused by an IDS killing the connection
19808 between haproxy and the server.
19809
19810 sH The "timeout server" stroke before the server could return its
19811 response headers. This is the most common anomaly, indicating too
19812 long transactions, probably caused by server or database saturation.
19813 The immediate workaround consists in increasing the "timeout server"
19814 setting, but it is important to keep in mind that the user experience
19815 will suffer from these long response times. The only long term
19816 solution is to fix the application.
19817
19818 sQ The session spent too much time in queue and has been expired. See
19819 the "timeout queue" and "timeout connect" settings to find out how to
19820 fix this if it happens too often. If it often happens massively in
19821 short periods, it may indicate general problems on the affected
19822 servers due to I/O or database congestion, or saturation caused by
19823 external attacks.
19824
19825 PC The proxy refused to establish a connection to the server because the
19826 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020019827 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019828 so that it does not happen anymore. This status is very rare and
19829 might happen when the global "ulimit-n" parameter is forced by hand.
19830
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010019831 PD The proxy blocked an incorrectly formatted chunked encoded message in
19832 a request or a response, after the server has emitted its headers. In
19833 most cases, this will indicate an invalid message from the server to
Davor Ocelice9ed2812017-12-25 17:49:28 +010019834 the client. HAProxy supports chunk sizes of up to 2GB - 1 (2147483647
Willy Tarreauf3a3e132013-08-31 08:16:26 +020019835 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010019836
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019837 PH The proxy blocked the server's response, because it was invalid,
19838 incomplete, dangerous (cache control), or matched a security filter.
19839 In any case, an HTTP 502 error is sent to the client. One possible
19840 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010019841 containing unauthorized characters. It is also possible but quite
19842 rare, that the proxy blocked a chunked-encoding request from the
19843 client due to an invalid syntax, before the server responded. In this
19844 case, an HTTP 400 error is sent to the client and reported in the
19845 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019846
19847 PR The proxy blocked the client's HTTP request, either because of an
19848 invalid HTTP syntax, in which case it returned an HTTP 400 error to
19849 the client, or because a deny filter matched, in which case it
19850 returned an HTTP 403 error.
19851
19852 PT The proxy blocked the client's request and has tarpitted its
19853 connection before returning it a 500 server error. Nothing was sent
19854 to the server. The connection was maintained open for as long as
19855 reported by the "Tw" timer field.
19856
19857 RC A local resource has been exhausted (memory, sockets, source ports)
19858 preventing the connection to the server from establishing. The error
19859 logs will tell precisely what was missing. This is very rare and can
19860 only be solved by proper system tuning.
19861
Willy Tarreau996a92c2010-10-13 19:30:47 +020019862The combination of the two last flags gives a lot of information about how
19863persistence was handled by the client, the server and by haproxy. This is very
19864important to troubleshoot disconnections, when users complain they have to
19865re-authenticate. The commonly encountered flags are :
19866
19867 -- Persistence cookie is not enabled.
19868
19869 NN No cookie was provided by the client, none was inserted in the
19870 response. For instance, this can be in insert mode with "postonly"
19871 set on a GET request.
19872
19873 II A cookie designating an invalid server was provided by the client,
19874 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040019875 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020019876 value can be presented by a client when no other server knows it.
19877
19878 NI No cookie was provided by the client, one was inserted in the
19879 response. This typically happens for first requests from every user
19880 in "insert" mode, which makes it an easy way to count real users.
19881
19882 VN A cookie was provided by the client, none was inserted in the
19883 response. This happens for most responses for which the client has
19884 already got a cookie.
19885
19886 VU A cookie was provided by the client, with a last visit date which is
19887 not completely up-to-date, so an updated cookie was provided in
19888 response. This can also happen if there was no date at all, or if
19889 there was a date but the "maxidle" parameter was not set, so that the
19890 cookie can be switched to unlimited time.
19891
19892 EI A cookie was provided by the client, with a last visit date which is
19893 too old for the "maxidle" parameter, so the cookie was ignored and a
19894 new cookie was inserted in the response.
19895
19896 OI A cookie was provided by the client, with a first visit date which is
19897 too old for the "maxlife" parameter, so the cookie was ignored and a
19898 new cookie was inserted in the response.
19899
19900 DI The server designated by the cookie was down, a new server was
19901 selected and a new cookie was emitted in the response.
19902
19903 VI The server designated by the cookie was not marked dead but could not
19904 be reached. A redispatch happened and selected another one, which was
19905 then advertised in the response.
19906
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019907
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199088.6. Non-printable characters
19909-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019910
19911In order not to cause trouble to log analysis tools or terminals during log
19912consulting, non-printable characters are not sent as-is into log files, but are
19913converted to the two-digits hexadecimal representation of their ASCII code,
19914prefixed by the character '#'. The only characters that can be logged without
19915being escaped are comprised between 32 and 126 (inclusive). Obviously, the
19916escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
19917is the same for the character '"' which becomes "#22", as well as '{', '|' and
19918'}' when logging headers.
19919
19920Note that the space character (' ') is not encoded in headers, which can cause
19921issues for tools relying on space count to locate fields. A typical header
19922containing spaces is "User-Agent".
19923
19924Last, it has been observed that some syslog daemons such as syslog-ng escape
19925the quote ('"') with a backslash ('\'). The reverse operation can safely be
19926performed since no quote may appear anywhere else in the logs.
19927
19928
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199298.7. Capturing HTTP cookies
19930---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019931
19932Cookie capture simplifies the tracking a complete user session. This can be
19933achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019934section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019935cookie will simultaneously be checked in the request ("Cookie:" header) and in
19936the response ("Set-Cookie:" header). The respective values will be reported in
19937the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019938locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019939not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
19940user switches to a new session for example, because the server will reassign it
19941a new cookie. It is also possible to detect if a server unexpectedly sets a
19942wrong cookie to a client, leading to session crossing.
19943
19944 Examples :
19945 # capture the first cookie whose name starts with "ASPSESSION"
19946 capture cookie ASPSESSION len 32
19947
19948 # capture the first cookie whose name is exactly "vgnvisitor"
19949 capture cookie vgnvisitor= len 32
19950
19951
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199528.8. Capturing HTTP headers
19953---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019954
19955Header captures are useful to track unique request identifiers set by an upper
19956proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
19957the response, one can search for information about the response length, how the
19958server asked the cache to behave, or an object location during a redirection.
19959
19960Header captures are performed using the "capture request header" and "capture
19961response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020019962section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019963
19964It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010019965time. Non-existent headers are logged as empty strings, and if one header
19966appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019967are grouped within braces '{' and '}' in the same order as they were declared,
19968and delimited with a vertical bar '|' without any space. Response headers
19969follow the same representation, but are displayed after a space following the
19970request headers block. These blocks are displayed just before the HTTP request
19971in the logs.
19972
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020019973As a special case, it is possible to specify an HTTP header capture in a TCP
19974frontend. The purpose is to enable logging of headers which will be parsed in
19975an HTTP backend if the request is then switched to this HTTP backend.
19976
Willy Tarreaucc6c8912009-02-22 10:53:55 +010019977 Example :
19978 # This instance chains to the outgoing proxy
19979 listen proxy-out
19980 mode http
19981 option httplog
19982 option logasap
19983 log global
19984 server cache1 192.168.1.1:3128
19985
19986 # log the name of the virtual server
19987 capture request header Host len 20
19988
19989 # log the amount of data uploaded during a POST
19990 capture request header Content-Length len 10
19991
19992 # log the beginning of the referrer
19993 capture request header Referer len 20
19994
19995 # server name (useful for outgoing proxies only)
19996 capture response header Server len 20
19997
19998 # logging the content-length is useful with "option logasap"
19999 capture response header Content-Length len 10
20000
Davor Ocelice9ed2812017-12-25 17:49:28 +010020001 # log the expected cache behavior on the response
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020002 capture response header Cache-Control len 8
20003
20004 # the Via header will report the next proxy's name
20005 capture response header Via len 20
20006
20007 # log the URL location during a redirection
20008 capture response header Location len 20
20009
20010 >>> Aug 9 20:26:09 localhost \
20011 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
20012 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
20013 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
20014 "GET http://fr.adserver.yahoo.com/"
20015
20016 >>> Aug 9 20:30:46 localhost \
20017 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
20018 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
20019 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010020020 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020021
20022 >>> Aug 9 20:30:46 localhost \
20023 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
20024 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
20025 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
20026 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010020027 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020028
20029
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200200308.9. Examples of logs
20031---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020032
20033These are real-world examples of logs accompanied with an explanation. Some of
20034them have been made up by hand. The syslog part has been removed for better
20035reading. Their sole purpose is to explain how to decipher them.
20036
20037 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
20038 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
20039 "HEAD / HTTP/1.0"
20040
20041 => long request (6.5s) entered by hand through 'telnet'. The server replied
20042 in 147 ms, and the session ended normally ('----')
20043
20044 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
20045 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
20046 0/9 "HEAD / HTTP/1.0"
20047
20048 => Idem, but the request was queued in the global queue behind 9 other
20049 requests, and waited there for 1230 ms.
20050
20051 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
20052 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
20053 "GET /image.iso HTTP/1.0"
20054
20055 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010020056 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020057 14 ms, 243 bytes of headers were sent to the client, and total time from
20058 accept to first data byte is 30 ms.
20059
20060 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
20061 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
20062 "GET /cgi-bin/bug.cgi? HTTP/1.0"
20063
Christopher Faulet87f1f3d2019-07-18 14:51:20 +020020064 => the proxy blocked a server response either because of an "http-response
20065 deny" rule, or because the response was improperly formatted and not
20066 HTTP-compliant, or because it blocked sensitive information which risked
20067 being cached. In this case, the response is replaced with a "502 bad
20068 gateway". The flags ("PH--") tell us that it was haproxy who decided to
20069 return the 502 and not the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020070
20071 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010020072 px-http/<NOSRV> -1/-1/-1/-1/8490 -1 0 - - CR-- 2/2/2/0/0 0/0 ""
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020073
20074 => the client never completed its request and aborted itself ("C---") after
20075 8.5s, while the proxy was waiting for the request headers ("-R--").
20076 Nothing was sent to any server.
20077
20078 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
20079 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
20080
20081 => The client never completed its request, which was aborted by the
20082 time-out ("c---") after 50s, while the proxy was waiting for the request
Davor Ocelice9ed2812017-12-25 17:49:28 +010020083 headers ("-R--"). Nothing was sent to any server, but the proxy could
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020084 send a 408 return code to the client.
20085
20086 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
20087 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
20088
20089 => This log was produced with "option tcplog". The client timed out after
20090 5 seconds ("c----").
20091
20092 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
20093 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010020094 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020095
20096 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020020097 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010020098 (config says 'retries 3'), and no redispatch (otherwise we would have
20099 seen "/+3"). Status code 503 was returned to the client. There were 115
20100 connections on this server, 202 connections on this proxy, and 205 on
20101 the global process. It is possible that the server refused the
20102 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010020103
Willy Tarreau52b2d222011-09-07 23:48:48 +020020104
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200201059. Supported filters
20106--------------------
20107
20108Here are listed officially supported filters with the list of parameters they
20109accept. Depending on compile options, some of these filters might be
20110unavailable. The list of available filters is reported in haproxy -vv.
20111
20112See also : "filter"
20113
201149.1. Trace
20115----------
20116
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010020117filter trace [name <name>] [random-parsing] [random-forwarding] [hexdump]
Christopher Fauletc3fe5332016-04-07 15:30:10 +020020118
20119 Arguments:
20120 <name> is an arbitrary name that will be reported in
20121 messages. If no name is provided, "TRACE" is used.
20122
20123 <random-parsing> enables the random parsing of data exchanged between
20124 the client and the server. By default, this filter
20125 parses all available data. With this parameter, it
20126 only parses a random amount of the available data.
20127
Davor Ocelice9ed2812017-12-25 17:49:28 +010020128 <random-forwarding> enables the random forwarding of parsed data. By
Christopher Fauletc3fe5332016-04-07 15:30:10 +020020129 default, this filter forwards all previously parsed
20130 data. With this parameter, it only forwards a random
20131 amount of the parsed data.
20132
Davor Ocelice9ed2812017-12-25 17:49:28 +010020133 <hexdump> dumps all forwarded data to the server and the client.
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010020134
Christopher Fauletc3fe5332016-04-07 15:30:10 +020020135This filter can be used as a base to develop new filters. It defines all
20136callbacks and print a message on the standard error stream (stderr) with useful
20137information for all of them. It may be useful to debug the activity of other
20138filters or, quite simply, HAProxy's activity.
20139
20140Using <random-parsing> and/or <random-forwarding> parameters is a good way to
20141tests the behavior of a filter that parses data exchanged between a client and
20142a server by adding some latencies in the processing.
20143
20144
201459.2. HTTP compression
20146---------------------
20147
20148filter compression
20149
20150The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
20151keyword must still be used to enable and configure the HTTP compression. And
Christopher Fauletb30b3102019-09-12 23:03:09 +020020152when no other filter is used, it is enough. When used with the cache or the
20153fcgi-app enabled, it is also enough. In this case, the compression is always
20154done after the response is stored in the cache. But it is mandatory to
20155explicitly use a filter line to enable the HTTP compression when at least one
20156filter other than the cache or the fcgi-app is used for the same
20157listener/frontend/backend. This is important to know the filters evaluation
20158order.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020020159
Christopher Fauletb30b3102019-09-12 23:03:09 +020020160See also : "compression", section 9.4 about the cache filter and section 9.5
20161 about the fcgi-app filter.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020020162
20163
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200201649.3. Stream Processing Offload Engine (SPOE)
20165--------------------------------------------
20166
20167filter spoe [engine <name>] config <file>
20168
20169 Arguments :
20170
20171 <name> is the engine name that will be used to find the right scope in
20172 the configuration file. If not provided, all the file will be
20173 parsed.
20174
20175 <file> is the path of the engine configuration file. This file can
20176 contain configuration of several engines. In this case, each
20177 part must be placed in its own scope.
20178
20179The Stream Processing Offload Engine (SPOE) is a filter communicating with
20180external components. It allows the offload of some specifics processing on the
Davor Ocelice9ed2812017-12-25 17:49:28 +010020181streams in tiered applications. These external components and information
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020020182exchanged with them are configured in dedicated files, for the main part. It
20183also requires dedicated backends, defined in HAProxy configuration.
20184
20185SPOE communicates with external components using an in-house binary protocol,
20186the Stream Processing Offload Protocol (SPOP).
20187
Tim Düsterhus4896c442016-11-29 02:15:19 +010020188For all information about the SPOE configuration and the SPOP specification, see
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020020189"doc/SPOE.txt".
20190
Christopher Faulet99a17a22018-12-11 09:18:27 +0100201919.4. Cache
20192----------
20193
20194filter cache <name>
20195
20196 Arguments :
20197
20198 <name> is name of the cache section this filter will use.
20199
20200The cache uses a filter to store cacheable responses. The HTTP rules
20201"cache-store" and "cache-use" must be used to define how and when to use a
John Roeslerfb2fce12019-07-10 15:45:51 -050020202cache. By default the corresponding filter is implicitly defined. And when no
Christopher Fauletb30b3102019-09-12 23:03:09 +020020203other filters than fcgi-app or compression are used, it is enough. In such
20204case, the compression filter is always evaluated after the cache filter. But it
20205is mandatory to explicitly use a filter line to use a cache when at least one
20206filter other than the compression or the fcgi-app is used for the same
Christopher Faulet27d93c32018-12-15 22:32:02 +010020207listener/frontend/backend. This is important to know the filters evaluation
20208order.
Christopher Faulet99a17a22018-12-11 09:18:27 +010020209
Christopher Fauletb30b3102019-09-12 23:03:09 +020020210See also : section 9.2 about the compression filter, section 9.5 about the
20211 fcgi-app filter and section 6 about cache.
20212
20213
202149.5. Fcgi-app
20215-------------
20216
Daniel Corbett67a82712020-07-06 23:01:19 -040020217filter fcgi-app <name>
Christopher Fauletb30b3102019-09-12 23:03:09 +020020218
20219 Arguments :
20220
20221 <name> is name of the fcgi-app section this filter will use.
20222
20223The FastCGI application uses a filter to evaluate all custom parameters on the
20224request path, and to process the headers on the response path. the <name> must
20225reference an existing fcgi-app section. The directive "use-fcgi-app" should be
20226used to define the application to use. By default the corresponding filter is
20227implicitly defined. And when no other filters than cache or compression are
20228used, it is enough. But it is mandatory to explicitly use a filter line to a
20229fcgi-app when at least one filter other than the compression or the cache is
20230used for the same backend. This is important to know the filters evaluation
20231order.
20232
20233See also: "use-fcgi-app", section 9.2 about the compression filter, section 9.4
20234 about the cache filter and section 10 about FastCGI application.
20235
20236
2023710. FastCGI applications
20238-------------------------
20239
20240HAProxy is able to send HTTP requests to Responder FastCGI applications. This
20241feature was added in HAProxy 2.1. To do so, servers must be configured to use
20242the FastCGI protocol (using the keyword "proto fcgi" on the server line) and a
20243FastCGI application must be configured and used by the backend managing these
20244servers (using the keyword "use-fcgi-app" into the proxy section). Several
20245FastCGI applications may be defined, but only one can be used at a time by a
20246backend.
20247
20248HAProxy implements all features of the FastCGI specification for Responder
20249application. Especially it is able to multiplex several requests on a simple
20250connection.
20251
2025210.1. Setup
20253-----------
20254
2025510.1.1. Fcgi-app section
20256--------------------------
20257
20258fcgi-app <name>
20259 Declare a FastCGI application named <name>. To be valid, at least the
20260 document root must be defined.
20261
20262acl <aclname> <criterion> [flags] [operator] <value> ...
20263 Declare or complete an access list.
20264
20265 See "acl" keyword in section 4.2 and section 7 about ACL usage for
20266 details. ACLs defined for a FastCGI application are private. They cannot be
20267 used by any other application or by any proxy. In the same way, ACLs defined
20268 in any other section are not usable by a FastCGI application. However,
20269 Pre-defined ACLs are available.
20270
20271docroot <path>
20272 Define the document root on the remote host. <path> will be used to build
20273 the default value of FastCGI parameters SCRIPT_FILENAME and
20274 PATH_TRANSLATED. It is a mandatory setting.
20275
20276index <script-name>
20277 Define the script name that will be appended after an URI that ends with a
20278 slash ("/") to set the default value of the FastCGI parameter SCRIPT_NAME. It
20279 is an optional setting.
20280
20281 Example :
20282 index index.php
20283
20284log-stderr global
20285log-stderr <address> [len <length>] [format <format>]
20286 [sample <ranges>:<smp_size>] <facility> [<level> [<minlevel>]]
20287 Enable logging of STDERR messages reported by the FastCGI application.
20288
20289 See "log" keyword in section 4.2 for details. It is an optional setting. By
20290 default STDERR messages are ignored.
20291
20292pass-header <name> [ { if | unless } <condition> ]
20293 Specify the name of a request header which will be passed to the FastCGI
20294 application. It may optionally be followed by an ACL-based condition, in
20295 which case it will only be evaluated if the condition is true.
20296
20297 Most request headers are already available to the FastCGI application,
20298 prefixed with "HTTP_". Thus, this directive is only required to pass headers
20299 that are purposefully omitted. Currently, the headers "Authorization",
20300 "Proxy-Authorization" and hop-by-hop headers are omitted.
20301
20302 Note that the headers "Content-type" and "Content-length" are never passed to
20303 the FastCGI application because they are already converted into parameters.
20304
20305path-info <regex>
Christopher Faulet28cb3662020-02-14 14:47:37 +010020306 Define a regular expression to extract the script-name and the path-info from
Christopher Faulet6c57f2d2020-02-14 16:55:52 +010020307 the URL-decoded path. Thus, <regex> may have two captures: the first one to
20308 capture the script name and the second one to capture the path-info. The
20309 first one is mandatory, the second one is optional. This way, it is possible
20310 to extract the script-name from the path ignoring the path-info. It is an
20311 optional setting. If it is not defined, no matching is performed on the
20312 path. and the FastCGI parameters PATH_INFO and PATH_TRANSLATED are not
20313 filled.
Christopher Faulet28cb3662020-02-14 14:47:37 +010020314
20315 For security reason, when this regular expression is defined, the newline and
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050020316 the null characters are forbidden from the path, once URL-decoded. The reason
Christopher Faulet28cb3662020-02-14 14:47:37 +010020317 to such limitation is because otherwise the matching always fails (due to a
20318 limitation one the way regular expression are executed in HAProxy). So if one
20319 of these two characters is found in the URL-decoded path, an error is
20320 returned to the client. The principle of least astonishment is applied here.
Christopher Fauletb30b3102019-09-12 23:03:09 +020020321
20322 Example :
Christopher Faulet6c57f2d2020-02-14 16:55:52 +010020323 path-info ^(/.+\.php)(/.*)?$ # both script-name and path-info may be set
20324 path-info ^(/.+\.php) # the path-info is ignored
Christopher Fauletb30b3102019-09-12 23:03:09 +020020325
20326option get-values
20327no option get-values
20328 Enable or disable the retrieve of variables about connection management.
20329
Daniel Corbett67a82712020-07-06 23:01:19 -040020330 HAProxy is able to send the record FCGI_GET_VALUES on connection
Christopher Fauletb30b3102019-09-12 23:03:09 +020020331 establishment to retrieve the value for following variables:
20332
20333 * FCGI_MAX_REQS The maximum number of concurrent requests this
20334 application will accept.
20335
William Lallemand93e548e2019-09-30 13:54:02 +020020336 * FCGI_MPXS_CONNS "0" if this application does not multiplex connections,
20337 "1" otherwise.
Christopher Fauletb30b3102019-09-12 23:03:09 +020020338
20339 Some FastCGI applications does not support this feature. Some others close
Ilya Shipitsin11057a32020-06-21 21:18:27 +050020340 the connection immediately after sending their response. So, by default, this
Christopher Fauletb30b3102019-09-12 23:03:09 +020020341 option is disabled.
20342
20343 Note that the maximum number of concurrent requests accepted by a FastCGI
20344 application is a connection variable. It only limits the number of streams
20345 per connection. If the global load must be limited on the application, the
20346 server parameters "maxconn" and "pool-max-conn" must be set. In addition, if
20347 an application does not support connection multiplexing, the maximum number
20348 of concurrent requests is automatically set to 1.
20349
20350option keep-conn
20351no option keep-conn
20352 Instruct the FastCGI application to keep the connection open or not after
20353 sending a response.
20354
20355 If disabled, the FastCGI application closes the connection after responding
20356 to this request. By default, this option is enabled.
20357
20358option max-reqs <reqs>
20359 Define the maximum number of concurrent requests this application will
20360 accept.
20361
20362 This option may be overwritten if the variable FCGI_MAX_REQS is retrieved
20363 during connection establishment. Furthermore, if the application does not
20364 support connection multiplexing, this option will be ignored. By default set
20365 to 1.
20366
20367option mpxs-conns
20368no option mpxs-conns
20369 Enable or disable the support of connection multiplexing.
20370
20371 This option may be overwritten if the variable FCGI_MPXS_CONNS is retrieved
20372 during connection establishment. It is disabled by default.
20373
20374set-param <name> <fmt> [ { if | unless } <condition> ]
20375 Set a FastCGI parameter that should be passed to this application. Its
20376 value, defined by <fmt> must follows the log-format rules (see section 8.2.4
20377 "Custom Log format"). It may optionally be followed by an ACL-based
20378 condition, in which case it will only be evaluated if the condition is true.
20379
20380 With this directive, it is possible to overwrite the value of default FastCGI
20381 parameters. If the value is evaluated to an empty string, the rule is
20382 ignored. These directives are evaluated in their declaration order.
20383
20384 Example :
20385 # PHP only, required if PHP was built with --enable-force-cgi-redirect
20386 set-param REDIRECT_STATUS 200
20387
20388 set-param PHP_AUTH_DIGEST %[req.hdr(Authorization)]
20389
20390
2039110.1.2. Proxy section
20392---------------------
20393
20394use-fcgi-app <name>
20395 Define the FastCGI application to use for the backend.
20396
20397 Arguments :
20398 <name> is the name of the FastCGI application to use.
20399
20400 This keyword is only available for HTTP proxies with the backend capability
20401 and with at least one FastCGI server. However, FastCGI servers can be mixed
20402 with HTTP servers. But except there is a good reason to do so, it is not
20403 recommended (see section 10.3 about the limitations for details). Only one
20404 application may be defined at a time per backend.
20405
20406 Note that, once a FastCGI application is referenced for a backend, depending
20407 on the configuration some processing may be done even if the request is not
20408 sent to a FastCGI server. Rules to set parameters or pass headers to an
20409 application are evaluated.
20410
20411
2041210.1.3. Example
20413---------------
20414
20415 frontend front-http
20416 mode http
20417 bind *:80
20418 bind *:
20419
20420 use_backend back-dynamic if { path_reg ^/.+\.php(/.*)?$ }
20421 default_backend back-static
20422
20423 backend back-static
20424 mode http
20425 server www A.B.C.D:80
20426
20427 backend back-dynamic
20428 mode http
20429 use-fcgi-app php-fpm
20430 server php-fpm A.B.C.D:9000 proto fcgi
20431
20432 fcgi-app php-fpm
20433 log-stderr global
20434 option keep-conn
20435
20436 docroot /var/www/my-app
20437 index index.php
20438 path-info ^(/.+\.php)(/.*)?$
20439
20440
2044110.2. Default parameters
20442------------------------
20443
20444A Responder FastCGI application has the same purpose as a CGI/1.1 program. In
20445the CGI/1.1 specification (RFC3875), several variables must be passed to the
Ilya Shipitsin8525fd92020-02-29 12:34:59 +050020446script. So HAProxy set them and some others commonly used by FastCGI
Christopher Fauletb30b3102019-09-12 23:03:09 +020020447applications. All these variables may be overwritten, with caution though.
20448
20449 +-------------------+-----------------------------------------------------+
20450 | AUTH_TYPE | Identifies the mechanism, if any, used by HAProxy |
20451 | | to authenticate the user. Concretely, only the |
20452 | | BASIC authentication mechanism is supported. |
20453 | | |
20454 +-------------------+-----------------------------------------------------+
20455 | CONTENT_LENGTH | Contains the size of the message-body attached to |
20456 | | the request. It means only requests with a known |
20457 | | size are considered as valid and sent to the |
20458 | | application. |
20459 | | |
20460 +-------------------+-----------------------------------------------------+
20461 | CONTENT_TYPE | Contains the type of the message-body attached to |
20462 | | the request. It may not be set. |
20463 | | |
20464 +-------------------+-----------------------------------------------------+
20465 | DOCUMENT_ROOT | Contains the document root on the remote host under |
20466 | | which the script should be executed, as defined in |
20467 | | the application's configuration. |
20468 | | |
20469 +-------------------+-----------------------------------------------------+
20470 | GATEWAY_INTERFACE | Contains the dialect of CGI being used by HAProxy |
20471 | | to communicate with the FastCGI application. |
20472 | | Concretely, it is set to "CGI/1.1". |
20473 | | |
20474 +-------------------+-----------------------------------------------------+
20475 | PATH_INFO | Contains the portion of the URI path hierarchy |
20476 | | following the part that identifies the script |
20477 | | itself. To be set, the directive "path-info" must |
20478 | | be defined. |
20479 | | |
20480 +-------------------+-----------------------------------------------------+
20481 | PATH_TRANSLATED | If PATH_INFO is set, it is its translated version. |
20482 | | It is the concatenation of DOCUMENT_ROOT and |
20483 | | PATH_INFO. If PATH_INFO is not set, this parameters |
20484 | | is not set too. |
20485 | | |
20486 +-------------------+-----------------------------------------------------+
20487 | QUERY_STRING | Contains the request's query string. It may not be |
20488 | | set. |
20489 | | |
20490 +-------------------+-----------------------------------------------------+
20491 | REMOTE_ADDR | Contains the network address of the client sending |
20492 | | the request. |
20493 | | |
20494 +-------------------+-----------------------------------------------------+
20495 | REMOTE_USER | Contains the user identification string supplied by |
20496 | | client as part of user authentication. |
20497 | | |
20498 +-------------------+-----------------------------------------------------+
20499 | REQUEST_METHOD | Contains the method which should be used by the |
20500 | | script to process the request. |
20501 | | |
20502 +-------------------+-----------------------------------------------------+
20503 | REQUEST_URI | Contains the request's URI. |
20504 | | |
20505 +-------------------+-----------------------------------------------------+
20506 | SCRIPT_FILENAME | Contains the absolute pathname of the script. it is |
20507 | | the concatenation of DOCUMENT_ROOT and SCRIPT_NAME. |
20508 | | |
20509 +-------------------+-----------------------------------------------------+
20510 | SCRIPT_NAME | Contains the name of the script. If the directive |
20511 | | "path-info" is defined, it is the first part of the |
20512 | | URI path hierarchy, ending with the script name. |
20513 | | Otherwise, it is the entire URI path. |
20514 | | |
20515 +-------------------+-----------------------------------------------------+
20516 | SERVER_NAME | Contains the name of the server host to which the |
20517 | | client request is directed. It is the value of the |
20518 | | header "Host", if defined. Otherwise, the |
20519 | | destination address of the connection on the client |
20520 | | side. |
20521 | | |
20522 +-------------------+-----------------------------------------------------+
20523 | SERVER_PORT | Contains the destination TCP port of the connection |
20524 | | on the client side, which is the port the client |
20525 | | connected to. |
20526 | | |
20527 +-------------------+-----------------------------------------------------+
20528 | SERVER_PROTOCOL | Contains the request's protocol. |
20529 | | |
20530 +-------------------+-----------------------------------------------------+
20531 | HTTPS | Set to a non-empty value ("on") if the script was |
20532 | | queried through the HTTPS protocol. |
20533 | | |
20534 +-------------------+-----------------------------------------------------+
20535
20536
2053710.3. Limitations
20538------------------
20539
20540The current implementation have some limitations. The first one is about the
20541way some request headers are hidden to the FastCGI applications. This happens
20542during the headers analysis, on the backend side, before the connection
20543establishment. At this stage, HAProxy know the backend is using a FastCGI
20544application but it don't know if the request will be routed to a FastCGI server
20545or not. But to hide request headers, it simply removes them from the HTX
20546message. So, if the request is finally routed to an HTTP server, it never see
20547these headers. For this reason, it is not recommended to mix FastCGI servers
20548and HTTP servers under the same backend.
20549
20550Similarly, the rules "set-param" and "pass-header" are evaluated during the
20551request headers analysis. So the evaluation is always performed, even if the
20552requests is finally forwarded to an HTTP server.
20553
20554About the rules "set-param", when a rule is applied, a pseudo header is added
20555into the HTX message. So, the same way than for HTTP header rewrites, it may
20556fail if the buffer is full. The rules "set-param" will compete with
20557"http-request" ones.
20558
20559Finally, all FastCGI params and HTTP headers are sent into a unique record
20560FCGI_PARAM. Encoding of this record must be done in one pass, otherwise a
20561processing error is returned. It means the record FCGI_PARAM, once encoded,
20562must not exceeds the size of a buffer. However, there is no reserve to respect
20563here.
William Lallemand86d0df02017-11-24 21:36:45 +010020564
Willy Tarreau0ba27502007-12-24 16:55:16 +010020565/*
20566 * Local variables:
20567 * fill-column: 79
20568 * End:
20569 */