blob: b5e37f7ecaba511fa13bdbd250b8b1a8070555a2 [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 Tarreaufba74ea2018-12-22 11:19:45 +01005 version 2.0
Willy Tarreau6a06a402007-07-15 20:15:28 +02006 willy tarreau
William Lallemand4f392792020-06-12 17:31:06 +02007 2020/06/12
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
Willy Tarreauc57f0e22009-05-10 13:12:33 +020055
564. Proxies
574.1. Proxy keywords matrix
584.2. Alphabetically sorted keywords reference
59
Davor Ocelice9ed2812017-12-25 17:49:28 +0100605. Bind and server options
Willy Tarreau086fbf52012-09-24 20:34:51 +0200615.1. Bind options
625.2. Server and default-server options
Baptiste Assmann1fa66662015-04-14 00:28:47 +0200635.3. Server DNS resolution
645.3.1. Global overview
655.3.2. The resolvers section
Willy Tarreauc57f0e22009-05-10 13:12:33 +020066
676. HTTP header manipulation
68
Willy Tarreau74ca5042013-06-11 23:12:07 +0200697. Using ACLs and fetching samples
707.1. ACL basics
717.1.1. Matching booleans
727.1.2. Matching integers
737.1.3. Matching strings
747.1.4. Matching regular expressions (regexes)
757.1.5. Matching arbitrary data blocks
767.1.6. Matching IPv4 and IPv6 addresses
777.2. Using ACLs to form conditions
787.3. Fetching samples
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200797.3.1. Converters
807.3.2. Fetching samples from internal states
817.3.3. Fetching samples at Layer 4
827.3.4. Fetching samples at Layer 5
837.3.5. Fetching samples from buffer contents (Layer 6)
847.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +0200857.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020086
878. Logging
888.1. Log levels
898.2. Log formats
908.2.1. Default log format
918.2.2. TCP log format
928.2.3. HTTP log format
William Lallemand48940402012-01-30 16:47:22 +0100938.2.4. Custom log format
Willy Tarreau5f51e1a2012-12-03 18:40:10 +0100948.2.5. Error log format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200958.3. Advanced logging options
968.3.1. Disabling logging of external tests
978.3.2. Logging before waiting for the session to terminate
988.3.3. Raising log level upon errors
998.3.4. Disabling logging of successful connections
1008.4. Timing events
1018.5. Session state at disconnection
1028.6. Non-printable characters
1038.7. Capturing HTTP cookies
1048.8. Capturing HTTP headers
1058.9. Examples of logs
106
Christopher Fauletc3fe5332016-04-07 15:30:10 +02001079. Supported filters
1089.1. Trace
1099.2. HTTP compression
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001109.3. Stream Processing Offload Engine (SPOE)
Christopher Faulet99a17a22018-12-11 09:18:27 +01001119.4. Cache
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200112
William Lallemand86d0df02017-11-24 21:36:45 +010011310. Cache
Cyril Bonté7b888f12017-11-26 22:24:31 +010011410.1. Limitation
11510.2. Setup
11610.2.1. Cache section
11710.2.2. Proxy section
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200118
1191. Quick reminder about HTTP
120----------------------------
121
Davor Ocelice9ed2812017-12-25 17:49:28 +0100122When HAProxy is running in HTTP mode, both the request and the response are
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200123fully analyzed and indexed, thus it becomes possible to build matching criteria
124on almost anything found in the contents.
125
126However, it is important to understand how HTTP requests and responses are
127formed, and how HAProxy decomposes them. It will then become easier to write
128correct rules and to debug existing configurations.
129
130
1311.1. The HTTP transaction model
132-------------------------------
133
134The HTTP protocol is transaction-driven. This means that each request will lead
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100135to one and only one response. Traditionally, a TCP connection is established
Davor Ocelice9ed2812017-12-25 17:49:28 +0100136from the client to the server, a request is sent by the client through the
137connection, the server responds, and the connection is closed. A new request
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200138will involve a new connection :
139
140 [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ...
141
142In this mode, called the "HTTP close" mode, there are as many connection
143establishments as there are HTTP transactions. Since the connection is closed
144by the server after the response, the client does not need to know the content
145length.
146
147Due to the transactional nature of the protocol, it was possible to improve it
148to avoid closing a connection between two subsequent transactions. In this mode
149however, it is mandatory that the server indicates the content length for each
150response so that the client does not wait indefinitely. For this, a special
151header is used: "Content-length". This mode is called the "keep-alive" mode :
152
153 [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ...
154
155Its advantages are a reduced latency between transactions, and less processing
156power required on the server side. It is generally better than the close mode,
157but not always because the clients often limit their concurrent connections to
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200158a smaller value.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200159
Willy Tarreau95c4e142017-11-26 12:18:55 +0100160Another improvement in the communications is the pipelining mode. It still uses
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200161keep-alive, but the client does not wait for the first response to send the
162second request. This is useful for fetching large number of images composing a
163page :
164
165 [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ...
166
167This can obviously have a tremendous benefit on performance because the network
168latency is eliminated between subsequent requests. Many HTTP agents do not
169correctly support pipelining since there is no way to associate a response with
170the corresponding request in HTTP. For this reason, it is mandatory for the
Cyril Bonté78caf842010-03-10 22:41:43 +0100171server to reply in the exact same order as the requests were received.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200172
Willy Tarreau95c4e142017-11-26 12:18:55 +0100173The next improvement is the multiplexed mode, as implemented in HTTP/2. This
174time, each transaction is assigned a single stream identifier, and all streams
175are multiplexed over an existing connection. Many requests can be sent in
176parallel by the client, and responses can arrive in any order since they also
177carry the stream identifier.
178
Willy Tarreau70dffda2014-01-30 03:07:23 +0100179By default HAProxy operates in keep-alive mode with regards to persistent
180connections: for each connection it processes each request and response, and
181leaves the connection idle on both sides between the end of a response and the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100182start of a new request. When it receives HTTP/2 connections from a client, it
183processes all the requests in parallel and leaves the connection idling,
184waiting for new requests, just as if it was a keep-alive HTTP connection.
Patrick Mezard9ec2ec42010-06-12 17:02:45 +0200185
Christopher Faulet315b39c2018-09-21 16:26:19 +0200186HAProxy supports 4 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +0100187 - keep alive : all requests and responses are processed (default)
188 - tunnel : only the first request and response are processed,
Christopher Faulet6c9bbb22019-03-26 21:37:23 +0100189 everything else is forwarded with no analysis (deprecated).
Willy Tarreau70dffda2014-01-30 03:07:23 +0100190 - server close : the server-facing connection is closed after the response.
Christopher Faulet315b39c2018-09-21 16:26:19 +0200191 - close : the connection is actively closed after end of response.
Willy Tarreau70dffda2014-01-30 03:07:23 +0100192
Davor Ocelice9ed2812017-12-25 17:49:28 +0100193For HTTP/2, the connection mode resembles more the "server close" mode : given
194the independence of all streams, there is currently no place to hook the idle
Willy Tarreau95c4e142017-11-26 12:18:55 +0100195server connection after a response, so it is closed after the response. HTTP/2
196is only supported for incoming connections, not on connections going to
197servers.
198
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200199
2001.2. HTTP request
201-----------------
202
203First, let's consider this HTTP request :
204
205 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100206 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200207 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1
208 2 Host: www.mydomain.com
209 3 User-agent: my small browser
210 4 Accept: image/jpeg, image/gif
211 5 Accept: image/png
212
213
2141.2.1. The Request line
215-----------------------
216
217Line 1 is the "request line". It is always composed of 3 fields :
218
219 - a METHOD : GET
220 - a URI : /serv/login.php?lang=en&profile=2
221 - a version tag : HTTP/1.1
222
223All of them are delimited by what the standard calls LWS (linear white spaces),
224which are commonly spaces, but can also be tabs or line feeds/carriage returns
225followed by spaces/tabs. The method itself cannot contain any colon (':') and
226is limited to alphabetic letters. All those various combinations make it
227desirable that HAProxy performs the splitting itself rather than leaving it to
228the user to write a complex or inaccurate regular expression.
229
230The URI itself can have several forms :
231
232 - A "relative URI" :
233
234 /serv/login.php?lang=en&profile=2
235
236 It is a complete URL without the host part. This is generally what is
237 received by servers, reverse proxies and transparent proxies.
238
239 - An "absolute URI", also called a "URL" :
240
241 http://192.168.0.12:8080/serv/login.php?lang=en&profile=2
242
243 It is composed of a "scheme" (the protocol name followed by '://'), a host
244 name or address, optionally a colon (':') followed by a port number, then
245 a relative URI beginning at the first slash ('/') after the address part.
246 This is generally what proxies receive, but a server supporting HTTP/1.1
247 must accept this form too.
248
249 - a star ('*') : this form is only accepted in association with the OPTIONS
250 method and is not relayable. It is used to inquiry a next hop's
251 capabilities.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100252
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200253 - an address:port combination : 192.168.0.12:80
254 This is used with the CONNECT method, which is used to establish TCP
255 tunnels through HTTP proxies, generally for HTTPS, but sometimes for
256 other protocols too.
257
258In a relative URI, two sub-parts are identified. The part before the question
259mark is called the "path". It is typically the relative path to static objects
260on the server. The part after the question mark is called the "query string".
261It is mostly used with GET requests sent to dynamic scripts and is very
262specific to the language, framework or application in use.
263
Willy Tarreau95c4e142017-11-26 12:18:55 +0100264HTTP/2 doesn't convey a version information with the request, so the version is
Davor Ocelice9ed2812017-12-25 17:49:28 +0100265assumed to be the same as the one of the underlying protocol (i.e. "HTTP/2").
Willy Tarreau95c4e142017-11-26 12:18:55 +0100266However, haproxy natively processes HTTP/1.x requests and headers, so requests
267received over an HTTP/2 connection are transcoded to HTTP/1.1 before being
268processed. This explains why they still appear as "HTTP/1.1" in haproxy's logs
269as well as in server logs.
270
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200271
2721.2.2. The request headers
273--------------------------
274
275The headers start at the second line. They are composed of a name at the
276beginning of the line, immediately followed by a colon (':'). Traditionally,
277an LWS is added after the colon but that's not required. Then come the values.
278Multiple identical headers may be folded into one single line, delimiting the
279values with commas, provided that their order is respected. This is commonly
280encountered in the "Cookie:" field. A header may span over multiple lines if
281the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5
282define a total of 3 values for the "Accept:" header.
283
Davor Ocelice9ed2812017-12-25 17:49:28 +0100284Contrary to a common misconception, header names are not case-sensitive, and
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200285their values are not either if they refer to other header names (such as the
Willy Tarreau95c4e142017-11-26 12:18:55 +0100286"Connection:" header). In HTTP/2, header names are always sent in lower case,
287as can be seen when running in debug mode.
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200288
289The end of the headers is indicated by the first empty line. People often say
290that it's a double line feed, which is not exact, even if a double line feed
291is one valid form of empty line.
292
293Fortunately, HAProxy takes care of all these complex combinations when indexing
294headers, checking values and counting them, so there is no reason to worry
295about the way they could be written, but it is important not to accuse an
296application of being buggy if it does unusual, valid things.
297
298Important note:
Lukas Tribus23953682017-04-28 13:24:30 +0000299 As suggested by RFC7231, HAProxy normalizes headers by replacing line breaks
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200300 in the middle of headers by LWS in order to join multi-line headers. This
301 is necessary for proper analysis and helps less capable HTTP parsers to work
302 correctly and not to be fooled by such complex constructs.
303
304
3051.3. HTTP response
306------------------
307
308An HTTP response looks very much like an HTTP request. Both are called HTTP
309messages. Let's consider this HTTP response :
310
311 Line Contents
Willy Tarreaud72758d2010-01-12 10:42:19 +0100312 number
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200313 1 HTTP/1.1 200 OK
314 2 Content-length: 350
315 3 Content-Type: text/html
316
Willy Tarreau816b9792009-09-15 21:25:21 +0200317As a special case, HTTP supports so called "Informational responses" as status
318codes 1xx. These messages are special in that they don't convey any part of the
319response, they're just used as sort of a signaling message to ask a client to
Willy Tarreau5843d1a2010-02-01 15:13:32 +0100320continue to post its request for instance. In the case of a status 100 response
321the requested information will be carried by the next non-100 response message
322following the informational one. This implies that multiple responses may be
323sent to a single request, and that this only works when keep-alive is enabled
324(1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to
325correctly forward and skip them, and only process the next non-100 response. As
326such, these messages are neither logged nor transformed, unless explicitly
327state otherwise. Status 101 messages indicate that the protocol is changing
328over the same connection and that haproxy must switch to tunnel mode, just as
329if a CONNECT had occurred. Then the Upgrade header would contain additional
330information about the type of protocol the connection is switching to.
Willy Tarreau816b9792009-09-15 21:25:21 +0200331
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200332
Davor Ocelice9ed2812017-12-25 17:49:28 +01003331.3.1. The response line
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200334------------------------
335
336Line 1 is the "response line". It is always composed of 3 fields :
337
338 - a version tag : HTTP/1.1
339 - a status code : 200
340 - a reason : OK
341
342The status code is always 3-digit. The first digit indicates a general status :
Davor Ocelice9ed2812017-12-25 17:49:28 +0100343 - 1xx = informational message to be skipped (e.g. 100, 101)
344 - 2xx = OK, content is following (e.g. 200, 206)
345 - 3xx = OK, no content following (e.g. 302, 304)
346 - 4xx = error caused by the client (e.g. 401, 403, 404)
347 - 5xx = error caused by the server (e.g. 500, 502, 503)
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200348
Lukas Tribus23953682017-04-28 13:24:30 +0000349Please refer to RFC7231 for the detailed meaning of all such codes. The
Willy Tarreaud72758d2010-01-12 10:42:19 +0100350"reason" field is just a hint, but is not parsed by clients. Anything can be
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200351found there, but it's a common practice to respect the well-established
352messages. It can be composed of one or multiple words, such as "OK", "Found",
353or "Authentication Required".
354
Davor Ocelice9ed2812017-12-25 17:49:28 +0100355HAProxy may emit the following status codes by itself :
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200356
357 Code When / reason
358 200 access to stats page, and when replying to monitoring requests
359 301 when performing a redirection, depending on the configured code
360 302 when performing a redirection, depending on the configured code
361 303 when performing a redirection, depending on the configured code
Willy Tarreaub67fdc42013-03-29 19:28:11 +0100362 307 when performing a redirection, depending on the configured code
363 308 when performing a redirection, depending on the configured code
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200364 400 for an invalid or too large request
365 401 when an authentication is required to perform the action (when
366 accessing the stats page)
367 403 when a request is forbidden by a "block" ACL or "reqdeny" filter
Florian Tham9f3bda02020-01-08 13:35:30 +0100368 404 when the requested resource could not be found
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200369 408 when the request timeout strikes before the request is complete
Florian Thamc09f7972020-01-08 10:19:05 +0100370 410 when the requested resource is no longer available and will not
371 be available again
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200372 500 when haproxy encounters an unrecoverable internal error, such as a
373 memory allocation failure, which should never happen
374 502 when the server returns an empty, invalid or incomplete response, or
375 when an "rspdeny" filter blocks the response.
376 503 when no server was available to handle the request, or in response to
377 monitoring requests which match the "monitor fail" condition
378 504 when the response timeout strikes before the server responds
379
380The error 4xx and 5xx codes above may be customized (see "errorloc" in section
3814.2).
382
383
3841.3.2. The response headers
385---------------------------
386
387Response headers work exactly like request headers, and as such, HAProxy uses
388the same parsing function for both. Please refer to paragraph 1.2.2 for more
389details.
390
391
3922. Configuring HAProxy
393----------------------
394
3952.1. Configuration file format
396------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +0200397
398HAProxy's configuration process involves 3 major sources of parameters :
399
400 - the arguments from the command-line, which always take precedence
401 - the "global" section, which sets process-wide parameters
402 - the proxies sections which can take form of "defaults", "listen",
403 "frontend" and "backend".
404
Willy Tarreau0ba27502007-12-24 16:55:16 +0100405The configuration file syntax consists in lines beginning with a keyword
406referenced in this manual, optionally followed by one or several parameters
William Lallemandf9873ba2015-05-05 17:37:14 +0200407delimited by spaces.
Willy Tarreau0ba27502007-12-24 16:55:16 +0100408
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200409
William Lallemandf9873ba2015-05-05 17:37:14 +02004102.2. Quoting and escaping
411-------------------------
412
413HAProxy's configuration introduces a quoting and escaping system similar to
414many programming languages. The configuration file supports 3 types: escaping
415with a backslash, weak quoting with double quotes, and strong quoting with
416single quotes.
417
418If spaces have to be entered in strings, then they must be escaped by preceding
419them by a backslash ('\') or by quoting them. Backslashes also have to be
420escaped by doubling or strong quoting them.
421
422Escaping is achieved by preceding a special character by a backslash ('\'):
423
424 \ to mark a space and differentiate it from a delimiter
425 \# to mark a hash and differentiate it from a comment
426 \\ to use a backslash
427 \' to use a single quote and differentiate it from strong quoting
428 \" to use a double quote and differentiate it from weak quoting
429
430Weak quoting is achieved by using double quotes (""). Weak quoting prevents
431the interpretation of:
432
433 space as a parameter separator
434 ' single quote as a strong quoting delimiter
435 # hash as a comment start
436
William Lallemandb2f07452015-05-12 14:27:13 +0200437Weak quoting permits the interpretation of variables, if you want to use a non
438-interpreted dollar within a double quoted string, you should escape it with a
439backslash ("\$"), it does not work outside weak quoting.
440
441Interpretation of escaping and special characters are not prevented by weak
William Lallemandf9873ba2015-05-05 17:37:14 +0200442quoting.
443
444Strong quoting is achieved by using single quotes (''). Inside single quotes,
445nothing is interpreted, it's the efficient way to quote regexes.
446
447Quoted and escaped strings are replaced in memory by their interpreted
448equivalent, it allows you to perform concatenation.
449
450 Example:
451 # those are equivalents:
452 log-format %{+Q}o\ %t\ %s\ %{-Q}r
453 log-format "%{+Q}o %t %s %{-Q}r"
454 log-format '%{+Q}o %t %s %{-Q}r'
455 log-format "%{+Q}o %t"' %s %{-Q}r'
456 log-format "%{+Q}o %t"' %s'\ %{-Q}r
457
458 # those are equivalents:
459 reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2
460 reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2'
461 reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2"
462 reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2"
463
464
William Lallemandb2f07452015-05-12 14:27:13 +02004652.3. Environment variables
466--------------------------
467
468HAProxy's configuration supports environment variables. Those variables are
469interpreted only within double quotes. Variables are expanded during the
470configuration parsing. Variable names must be preceded by a dollar ("$") and
471optionally enclosed with braces ("{}") similarly to what is done in Bourne
472shell. Variable names can contain alphanumerical characters or the character
473underscore ("_") but should not start with a digit.
474
475 Example:
476
477 bind "fd@${FD_APP1}"
478
479 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
480
481 user "$HAPROXY_USER"
482
William Lallemand4d03e432019-06-14 15:35:37 +0200483Some variables are defined by HAProxy, they can be used in the configuration
484file, or could be inherited by a program (See 3.7. Programs):
William Lallemanddaf4cd22018-04-17 16:46:13 +0200485
William Lallemand4d03e432019-06-14 15:35:37 +0200486* HAPROXY_LOCALPEER: defined at the startup of the process which contains the
487 name of the local peer. (See "-L" in the management guide.)
488
489* HAPROXY_CFGFILES: list of the configuration files loaded by HAProxy,
490 separated by semicolons. Can be useful in the case you specified a
491 directory.
492
493* HAPROXY_MWORKER: In master-worker mode, this variable is set to 1.
494
John Roesler27c754c2019-07-10 15:45:51 -0500495* HAPROXY_CLI: configured listeners addresses of the stats socket for every
William Lallemand4d03e432019-06-14 15:35:37 +0200496 processes, separated by semicolons.
497
John Roesler27c754c2019-07-10 15:45:51 -0500498* HAPROXY_MASTER_CLI: In master-worker mode, listeners addresses of the master
William Lallemand4d03e432019-06-14 15:35:37 +0200499 CLI, separated by semicolons.
500
501See also "external-check command" for other variables.
William Lallemandb2f07452015-05-12 14:27:13 +0200502
5032.4. Time format
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200504----------------
505
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +0100506Some parameters involve values representing time, such as timeouts. These
Willy Tarreau0ba27502007-12-24 16:55:16 +0100507values are generally expressed in milliseconds (unless explicitly stated
508otherwise) but may be expressed in any other unit by suffixing the unit to the
509numeric value. It is important to consider this because it will not be repeated
510for every keyword. Supported units are :
511
512 - us : microseconds. 1 microsecond = 1/1000000 second
513 - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default.
514 - s : seconds. 1s = 1000ms
515 - m : minutes. 1m = 60s = 60000ms
516 - h : hours. 1h = 60m = 3600s = 3600000ms
517 - d : days. 1d = 24h = 1440m = 86400s = 86400000ms
518
519
Lukas Tribusaa83a312017-03-21 09:25:09 +00005202.5. Examples
Patrick Mezard35da19c2010-06-12 17:02:47 +0200521-------------
522
523 # Simple configuration for an HTTP proxy listening on port 80 on all
524 # interfaces and forwarding requests to a single backend "servers" with a
525 # single server "server1" listening on 127.0.0.1:8000
526 global
527 daemon
528 maxconn 256
529
530 defaults
531 mode http
532 timeout connect 5000ms
533 timeout client 50000ms
534 timeout server 50000ms
535
536 frontend http-in
537 bind *:80
538 default_backend servers
539
540 backend servers
541 server server1 127.0.0.1:8000 maxconn 32
542
543
544 # The same configuration defined with a single listen block. Shorter but
545 # less expressive, especially in HTTP mode.
546 global
547 daemon
548 maxconn 256
549
550 defaults
551 mode http
552 timeout connect 5000ms
553 timeout client 50000ms
554 timeout server 50000ms
555
556 listen http-in
557 bind *:80
558 server server1 127.0.0.1:8000 maxconn 32
559
560
561Assuming haproxy is in $PATH, test these configurations in a shell with:
562
Willy Tarreauccb289d2010-12-11 20:19:38 +0100563 $ sudo haproxy -f configuration.conf -c
Patrick Mezard35da19c2010-06-12 17:02:47 +0200564
565
Willy Tarreauc57f0e22009-05-10 13:12:33 +02005663. Global parameters
Willy Tarreau6a06a402007-07-15 20:15:28 +0200567--------------------
568
569Parameters in the "global" section are process-wide and often OS-specific. They
570are generally set once for all and do not need being changed once correct. Some
571of them have command-line equivalents.
572
573The following keywords are supported in the "global" section :
574
575 * Process management and security
Emeric Brunc8e8d122012-10-02 18:42:10 +0200576 - ca-base
Willy Tarreau6a06a402007-07-15 20:15:28 +0200577 - chroot
Emeric Brunc8e8d122012-10-02 18:42:10 +0200578 - crt-base
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200579 - cpu-map
Willy Tarreau6a06a402007-07-15 20:15:28 +0200580 - daemon
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200581 - description
582 - deviceatlas-json-file
583 - deviceatlas-log-level
584 - deviceatlas-separator
585 - deviceatlas-properties-cookie
Simon Horman98637e52014-06-20 12:30:16 +0900586 - external-check
Willy Tarreau6a06a402007-07-15 20:15:28 +0200587 - gid
588 - group
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100589 - hard-stop-after
Christopher Fauleta99ff4d2019-07-22 16:18:24 +0200590 - h1-case-adjust
591 - h1-case-adjust-file
Willy Tarreau6a06a402007-07-15 20:15:28 +0200592 - log
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200593 - log-tag
Joe Williamsdf5b38f2010-12-29 17:05:48 +0100594 - log-send-hostname
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200595 - lua-load
William Lallemand27edc4b2019-05-07 17:49:33 +0200596 - mworker-max-reloads
Willy Tarreau6a06a402007-07-15 20:15:28 +0200597 - nbproc
Christopher Fauletbe0faa22017-08-29 15:37:10 +0200598 - nbthread
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200599 - node
Willy Tarreau6a06a402007-07-15 20:15:28 +0200600 - pidfile
Willy Tarreau1d549722016-02-16 12:41:57 +0100601 - presetenv
602 - resetenv
Willy Tarreau6a06a402007-07-15 20:15:28 +0200603 - uid
604 - ulimit-n
605 - user
Willy Tarreau636848a2019-04-15 19:38:50 +0200606 - set-dumpable
Willy Tarreau1d549722016-02-16 12:41:57 +0100607 - setenv
Willy Tarreaufbee7132007-10-18 13:53:22 +0200608 - stats
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200609 - ssl-default-bind-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200610 - ssl-default-bind-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200611 - ssl-default-bind-options
612 - ssl-default-server-ciphers
Dirkjan Bussink415150f2018-09-14 11:14:21 +0200613 - ssl-default-server-ciphersuites
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200614 - ssl-default-server-options
615 - ssl-dh-param-file
Emeric Brun850efd52014-01-29 12:24:34 +0100616 - ssl-server-verify
Willy Tarreauceb24bc2010-11-09 12:46:41 +0100617 - unix-bind
Willy Tarreau1d549722016-02-16 12:41:57 +0100618 - unsetenv
Thomas Holmesdb04f192015-05-18 13:21:39 +0100619 - 51degrees-data-file
620 - 51degrees-property-name-list
Dragan Dosen93b38d92015-06-29 16:43:25 +0200621 - 51degrees-property-separator
Dragan Dosenae6d39a2015-06-29 16:43:27 +0200622 - 51degrees-cache-size
Willy Tarreaub3cc9f22019-04-19 16:03:32 +0200623 - wurfl-data-file
624 - wurfl-information-list
625 - wurfl-information-list-separator
Willy Tarreaub3cc9f22019-04-19 16:03:32 +0200626 - wurfl-cache-size
Willy Tarreaud72758d2010-01-12 10:42:19 +0100627
Willy Tarreau6a06a402007-07-15 20:15:28 +0200628 * Performance tuning
Willy Tarreau1746eec2014-04-25 10:46:47 +0200629 - max-spread-checks
Willy Tarreau6a06a402007-07-15 20:15:28 +0200630 - maxconn
Willy Tarreau81c25d02011-09-07 15:17:21 +0200631 - maxconnrate
William Lallemandd85f9172012-11-09 17:05:39 +0100632 - maxcomprate
William Lallemand072a2bf2012-11-20 17:01:01 +0100633 - maxcompcpuusage
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100634 - maxpipes
Willy Tarreau93e7c002013-10-07 18:51:07 +0200635 - maxsessrate
Willy Tarreau403edff2012-09-06 11:58:37 +0200636 - maxsslconn
Willy Tarreaue43d5322013-10-07 20:01:52 +0200637 - maxsslrate
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200638 - maxzlibmem
Willy Tarreau6a06a402007-07-15 20:15:28 +0200639 - noepoll
640 - nokqueue
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +0000641 - noevports
Willy Tarreau6a06a402007-07-15 20:15:28 +0200642 - nopoll
Willy Tarreauff4f82d2009-02-06 11:28:13 +0100643 - nosplice
Jarno Huuskonen0e82b922014-04-12 18:22:19 +0300644 - nogetaddrinfo
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +0000645 - noreuseport
Willy Tarreau75c62c22018-11-22 11:02:09 +0100646 - profiling.tasks
Willy Tarreaufe255b72007-10-14 23:09:26 +0200647 - spread-checks
Baptiste Assmann5626f482015-08-23 10:00:10 +0200648 - server-state-base
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +0200649 - server-state-file
Grant Zhang872f9c22017-01-21 01:10:18 +0000650 - ssl-engine
Grant Zhangfa6c7ee2017-01-14 01:42:15 +0000651 - ssl-mode-async
Baptiste Assmann3493d0f2015-10-12 20:21:23 +0200652 - tune.buffers.limit
653 - tune.buffers.reserve
Willy Tarreau27a674e2009-08-17 07:23:33 +0200654 - tune.bufsize
Willy Tarreau43961d52010-10-04 20:39:20 +0200655 - tune.chksize
William Lallemandf3747832012-11-09 12:33:10 +0100656 - tune.comp.maxlevel
Willy Tarreaufe20e5b2017-07-27 11:42:14 +0200657 - tune.h2.header-table-size
Willy Tarreaue6baec02017-07-27 11:45:11 +0200658 - tune.h2.initial-window-size
Willy Tarreau5242ef82017-07-27 11:47:28 +0200659 - tune.h2.max-concurrent-streams
Willy Tarreau193b8c62012-11-22 00:17:38 +0100660 - tune.http.cookielen
Stéphane Cottin23e9e932017-05-18 08:58:41 +0200661 - tune.http.logurilen
Willy Tarreauac1932d2011-10-24 19:14:41 +0200662 - tune.http.maxhdr
Willy Tarreau7e312732014-02-12 16:35:14 +0100663 - tune.idletimer
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100664 - tune.lua.forced-yield
Willy Tarreau32f61e22015-03-18 17:54:59 +0100665 - tune.lua.maxmem
Thierry FOURNIER90da1912015-03-05 11:17:06 +0100666 - tune.lua.session-timeout
667 - tune.lua.task-timeout
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +0200668 - tune.lua.service-timeout
Willy Tarreaua0250ba2008-01-06 11:22:57 +0100669 - tune.maxaccept
670 - tune.maxpollevents
Willy Tarreau27a674e2009-08-17 07:23:33 +0200671 - tune.maxrewrite
Willy Tarreauf3045d22015-04-29 16:24:50 +0200672 - tune.pattern.cache-size
Willy Tarreaubd9a0a72011-10-23 21:14:29 +0200673 - tune.pipesize
Willy Tarreaue803de22010-01-21 17:43:04 +0100674 - tune.rcvbuf.client
675 - tune.rcvbuf.server
Willy Tarreaub22fc302015-12-14 12:04:35 +0100676 - tune.recv_enough
Olivier Houchard1599b802018-05-24 18:59:04 +0200677 - tune.runqueue-depth
Willy Tarreaue803de22010-01-21 17:43:04 +0100678 - tune.sndbuf.client
679 - tune.sndbuf.server
Willy Tarreau6ec58db2012-11-16 16:32:15 +0100680 - tune.ssl.cachesize
Willy Tarreaubfd59462013-02-21 07:46:09 +0100681 - tune.ssl.lifetime
Emeric Brun8dc60392014-05-09 13:52:00 +0200682 - tune.ssl.force-private-cache
Willy Tarreaubfd59462013-02-21 07:46:09 +0100683 - tune.ssl.maxrecord
Remi Gacognef46cd6e2014-06-12 14:58:40 +0200684 - tune.ssl.default-dh-param
Christopher Faulet31af49d2015-06-09 17:29:50 +0200685 - tune.ssl.ssl-ctx-cache-size
Thierry FOURNIER5bf77322017-02-25 12:45:22 +0100686 - tune.ssl.capture-cipherlist-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200687 - tune.vars.global-max-size
Christopher Fauletff2613e2016-11-09 11:36:17 +0100688 - tune.vars.proc-max-size
Thierry FOURNIER4834bc72015-06-06 19:29:07 +0200689 - tune.vars.reqres-max-size
690 - tune.vars.sess-max-size
691 - tune.vars.txn-max-size
William Lallemanda509e4c2012-11-07 16:54:34 +0100692 - tune.zlib.memlevel
693 - tune.zlib.windowsize
Willy Tarreaud72758d2010-01-12 10:42:19 +0100694
Willy Tarreau6a06a402007-07-15 20:15:28 +0200695 * Debugging
696 - debug
697 - quiet
Willy Tarreau6a06a402007-07-15 20:15:28 +0200698
699
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007003.1. Process management and security
Willy Tarreau6a06a402007-07-15 20:15:28 +0200701------------------------------------
702
Emeric Brunc8e8d122012-10-02 18:42:10 +0200703ca-base <dir>
704 Assigns a default directory to fetch SSL CA certificates and CRLs from when a
Emeric Brunfd33a262012-10-11 16:28:27 +0200705 relative path is used with "ca-file" or "crl-file" directives. Absolute
706 locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".
Emeric Brunc8e8d122012-10-02 18:42:10 +0200707
Willy Tarreau6a06a402007-07-15 20:15:28 +0200708chroot <jail dir>
709 Changes current directory to <jail dir> and performs a chroot() there before
710 dropping privileges. This increases the security level in case an unknown
711 vulnerability would be exploited, since it would make it very hard for the
712 attacker to exploit the system. This only works when the process is started
713 with superuser privileges. It is important to ensure that <jail_dir> is both
Davor Ocelice9ed2812017-12-25 17:49:28 +0100714 empty and non-writable to anyone.
Willy Tarreaud72758d2010-01-12 10:42:19 +0100715
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100716cpu-map [auto:]<process-set>[/<thread-set>] <cpu-set>...
717 On Linux 2.6 and above, it is possible to bind a process or a thread to a
718 specific CPU set. This means that the process or the thread will never run on
719 other CPUs. The "cpu-map" directive specifies CPU sets for process or thread
720 sets. The first argument is a process set, eventually followed by a thread
721 set. These sets have the format
722
723 all | odd | even | number[-[number]]
724
725 <number>> must be a number between 1 and 32 or 64, depending on the machine's
Davor Ocelice9ed2812017-12-25 17:49:28 +0100726 word size. Any process IDs above nbproc and any thread IDs above nbthread are
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100727 ignored. It is possible to specify a range with two such number delimited by
728 a dash ('-'). It also is possible to specify all processes at once using
Christopher Faulet1dcb9cb2017-11-22 10:24:40 +0100729 "all", only odd numbers using "odd" or even numbers using "even", just like
730 with the "bind-process" directive. The second and forthcoming arguments are
Davor Ocelice9ed2812017-12-25 17:49:28 +0100731 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 +0100732 range with two such numbers delimited by a dash ('-'). Multiple CPU numbers
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100733 or ranges may be specified, and the processes or threads will be allowed to
Davor Ocelice9ed2812017-12-25 17:49:28 +0100734 bind to all of them. Obviously, multiple "cpu-map" directives may be
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100735 specified. Each "cpu-map" directive will replace the previous ones when they
736 overlap. A thread will be bound on the intersection of its mapping and the
737 one of the process on which it is attached. If the intersection is null, no
738 specific binding will be set for the thread.
Willy Tarreaufc6c0322012-11-16 16:12:27 +0100739
Christopher Fauletff4121f2017-11-22 16:38:49 +0100740 Ranges can be partially defined. The higher bound can be omitted. In such
741 case, it is replaced by the corresponding maximum value, 32 or 64 depending
742 on the machine's word size.
743
Christopher Faulet26028f62017-11-22 15:01:51 +0100744 The prefix "auto:" can be added before the process set to let HAProxy
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100745 automatically bind a process or a thread to a CPU by incrementing
746 process/thread and CPU sets. To be valid, both sets must have the same
747 size. No matter the declaration order of the CPU sets, it will be bound from
748 the lowest to the highest bound. Having a process and a thread range with the
749 "auto:" prefix is not supported. Only one range is supported, the other one
750 must be a fixed number.
Christopher Faulet26028f62017-11-22 15:01:51 +0100751
752 Examples:
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100753 cpu-map 1-4 0-3 # bind processes 1 to 4 on the first 4 CPUs
754
755 cpu-map 1/all 0-3 # bind all threads of the first process on the
756 # first 4 CPUs
757
758 cpu-map 1- 0- # will be replaced by "cpu-map 1-64 0-63"
759 # or "cpu-map 1-32 0-31" depending on the machine's
760 # word size.
761
Christopher Faulet26028f62017-11-22 15:01:51 +0100762 # all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100763 # and so on.
Christopher Faulet26028f62017-11-22 15:01:51 +0100764 cpu-map auto:1-4 0-3
765 cpu-map auto:1-4 0-1 2-3
766 cpu-map auto:1-4 3 2 1 0
767
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100768 # all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
769 # and so on.
770 cpu-map auto:1/1-4 0-3
771 cpu-map auto:1/1-4 0-1 2-3
772 cpu-map auto:1/1-4 3 2 1 0
773
Davor Ocelice9ed2812017-12-25 17:49:28 +0100774 # bind each process to exactly one CPU using all/odd/even keyword
Christopher Faulet26028f62017-11-22 15:01:51 +0100775 cpu-map auto:all 0-63
776 cpu-map auto:even 0-31
777 cpu-map auto:odd 32-63
778
779 # invalid cpu-map because process and CPU sets have different sizes.
780 cpu-map auto:1-4 0 # invalid
781 cpu-map auto:1 0-3 # invalid
782
Christopher Fauletcb6a9452017-11-22 16:50:41 +0100783 # invalid cpu-map because automatic binding is used with a process range
784 # and a thread range.
785 cpu-map auto:all/all 0 # invalid
786 cpu-map auto:all/1-4 0 # invalid
787 cpu-map auto:1-4/all 0 # invalid
788
Emeric Brunc8e8d122012-10-02 18:42:10 +0200789crt-base <dir>
790 Assigns a default directory to fetch SSL certificates from when a relative
791 path is used with "crtfile" directives. Absolute locations specified after
792 "crtfile" prevail and ignore "crt-base".
793
Willy Tarreau6a06a402007-07-15 20:15:28 +0200794daemon
795 Makes the process fork into background. This is the recommended mode of
796 operation. It is equivalent to the command line "-D" argument. It can be
Lukas Tribusf46bf952017-11-21 12:39:34 +0100797 disabled by the command line "-db" argument. This option is ignored in
798 systemd mode.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200799
David Carlier8167f302015-06-01 13:50:06 +0200800deviceatlas-json-file <path>
801 Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
Davor Ocelice9ed2812017-12-25 17:49:28 +0100802 The path must be a valid JSON data file and accessible by HAProxy process.
David Carlier8167f302015-06-01 13:50:06 +0200803
804deviceatlas-log-level <value>
Davor Ocelice9ed2812017-12-25 17:49:28 +0100805 Sets the level of information returned by the API. This directive is
David Carlier8167f302015-06-01 13:50:06 +0200806 optional and set to 0 by default if not set.
807
808deviceatlas-separator <char>
809 Sets the character separator for the API properties results. This directive
810 is optional and set to | by default if not set.
811
Cyril Bonté0306c4a2015-10-26 22:37:38 +0100812deviceatlas-properties-cookie <name>
Cyril Bonté307ee1e2015-09-28 23:16:06 +0200813 Sets the client cookie's name used for the detection if the DeviceAtlas
814 Client-side component was used during the request. This directive is optional
815 and set to DAPROPS by default if not set.
David Carlier29b3ca32015-09-25 14:09:21 +0100816
Simon Horman98637e52014-06-20 12:30:16 +0900817external-check
818 Allows the use of an external agent to perform health checks.
819 This is disabled by default as a security precaution.
820 See "option external-check".
821
Willy Tarreau6a06a402007-07-15 20:15:28 +0200822gid <number>
823 Changes the process' group ID to <number>. It is recommended that the group
824 ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
825 be started with a user belonging to this group, or with superuser privileges.
Michael Schererab012dd2013-01-12 18:35:19 +0100826 Note that if haproxy is started from a user having supplementary groups, it
827 will only be able to drop these groups if started with superuser privileges.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200828 See also "group" and "uid".
Willy Tarreaud72758d2010-01-12 10:42:19 +0100829
Willy Tarreau8b852462019-12-03 08:29:22 +0100830group <group name>
831 Similar to "gid" but uses the GID of group name <group name> from /etc/group.
832 See also "gid" and "user".
833
Cyril Bonté203ec5a2017-03-23 22:44:13 +0100834hard-stop-after <time>
835 Defines the maximum time allowed to perform a clean soft-stop.
836
837 Arguments :
838 <time> is the maximum time (by default in milliseconds) for which the
839 instance will remain alive when a soft-stop is received via the
840 SIGUSR1 signal.
841
842 This may be used to ensure that the instance will quit even if connections
843 remain opened during a soft-stop (for example with long timeouts for a proxy
844 in tcp mode). It applies both in TCP and HTTP mode.
845
846 Example:
847 global
848 hard-stop-after 30s
849
Christopher Fauleta99ff4d2019-07-22 16:18:24 +0200850h1-case-adjust <from> <to>
851 Defines the case adjustment to apply, when enabled, to the header name
852 <from>, to change it to <to> before sending it to HTTP/1 clients or
853 servers. <from> must be in lower case, and <from> and <to> must not differ
854 except for their case. It may be repeated if several header names need to be
Ilya Shipitsin5c836fd2020-02-29 12:34:59 +0500855 adjusted. Duplicate entries are not allowed. If a lot of header names have to
Christopher Fauleta99ff4d2019-07-22 16:18:24 +0200856 be adjusted, it might be more convenient to use "h1-case-adjust-file".
857 Please note that no transformation will be applied unless "option
858 h1-case-adjust-bogus-client" or "option h1-case-adjust-bogus-server" is
859 specified in a proxy.
860
861 There is no standard case for header names because, as stated in RFC7230,
862 they are case-insensitive. So applications must handle them in a case-
863 insensitive manner. But some bogus applications violate the standards and
864 erroneously rely on the cases most commonly used by browsers. This problem
865 becomes critical with HTTP/2 because all header names must be exchanged in
866 lower case, and HAProxy follows the same convention. All header names are
867 sent in lower case to clients and servers, regardless of the HTTP version.
868
869 Applications which fail to properly process requests or responses may require
870 to temporarily use such workarounds to adjust header names sent to them for
871 the time it takes the application to be fixed. Please note that an
872 application which requires such workarounds might be vulnerable to content
873 smuggling attacks and must absolutely be fixed.
874
875 Example:
876 global
877 h1-case-adjust content-length Content-Length
878
879 See "h1-case-adjust-file", "option h1-case-adjust-bogus-client" and
880 "option h1-case-adjust-bogus-server".
881
882h1-case-adjust-file <hdrs-file>
883 Defines a file containing a list of key/value pairs used to adjust the case
884 of some header names before sending them to HTTP/1 clients or servers. The
885 file <hdrs-file> must contain 2 header names per line. The first one must be
886 in lower case and both must not differ except for their case. Lines which
887 start with '#' are ignored, just like empty lines. Leading and trailing tabs
888 and spaces are stripped. Duplicate entries are not allowed. Please note that
889 no transformation will be applied unless "option h1-case-adjust-bogus-client"
890 or "option h1-case-adjust-bogus-server" is specified in a proxy.
891
892 If this directive is repeated, only the last one will be processed. It is an
893 alternative to the directive "h1-case-adjust" if a lot of header names need
894 to be adjusted. Please read the risks associated with using this.
895
896 See "h1-case-adjust", "option h1-case-adjust-bogus-client" and
897 "option h1-case-adjust-bogus-server".
898
Frédéric Lécailled690dfa2019-04-25 10:52:17 +0200899log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
900 <facility> [max level [min level]]
Cyril Bonté3e954872018-03-20 23:30:27 +0100901 Adds a global syslog server. Several global servers can be defined. They
Davor Ocelice9ed2812017-12-25 17:49:28 +0100902 will receive logs for starts and exits, as well as all logs from proxies
Robert Tsai81ae1952007-12-05 10:47:29 +0100903 configured with "log global".
904
905 <address> can be one of:
906
Willy Tarreau2769aa02007-12-27 18:26:09 +0100907 - An IPv4 address optionally followed by a colon and a UDP port. If
Robert Tsai81ae1952007-12-05 10:47:29 +0100908 no port is specified, 514 is used by default (the standard syslog
909 port).
910
David du Colombier24bb5f52011-03-17 10:40:23 +0100911 - An IPv6 address followed by a colon and optionally a UDP port. If
912 no port is specified, 514 is used by default (the standard syslog
913 port).
914
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100915 - A filesystem path to a datagram UNIX domain socket, keeping in mind
Robert Tsai81ae1952007-12-05 10:47:29 +0100916 considerations for chroot (be sure the path is accessible inside
917 the chroot) and uid/gid (be sure the path is appropriately
Davor Ocelice9ed2812017-12-25 17:49:28 +0100918 writable).
Robert Tsai81ae1952007-12-05 10:47:29 +0100919
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100920 - A file descriptor number in the form "fd@<number>", which may point
921 to a pipe, terminal, or socket. In this case unbuffered logs are used
922 and one writev() call per log is performed. This is a bit expensive
923 but acceptable for most workloads. Messages sent this way will not be
924 truncated but may be dropped, in which case the DroppedLogs counter
925 will be incremented. The writev() call is atomic even on pipes for
926 messages up to PIPE_BUF size, which POSIX recommends to be at least
927 512 and which is 4096 bytes on most modern operating systems. Any
928 larger message may be interleaved with messages from other processes.
929 Exceptionally for debugging purposes the file descriptor may also be
930 directed to a file, but doing so will significantly slow haproxy down
931 as non-blocking calls will be ignored. Also there will be no way to
932 purge nor rotate this file without restarting the process. Note that
933 the configured syslog format is preserved, so the output is suitable
Willy Tarreauc1b06452018-11-12 11:57:56 +0100934 for use with a TCP syslog server. See also the "short" and "raw"
935 format below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +0100936
937 - "stdout" / "stderr", which are respectively aliases for "fd@1" and
938 "fd@2", see above.
939
William Lallemandb2f07452015-05-12 14:27:13 +0200940 You may want to reference some environment variables in the address
941 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +0100942
Willy Tarreau18324f52014-06-27 18:10:07 +0200943 <length> is an optional maximum line length. Log lines larger than this value
944 will be truncated before being sent. The reason is that syslog
945 servers act differently on log line length. All servers support the
946 default value of 1024, but some servers simply drop larger lines
947 while others do log them. If a server supports long lines, it may
948 make sense to set this value here in order to avoid truncating long
949 lines. Similarly, if a server drops long lines, it is preferable to
950 truncate them before sending them. Accepted values are 80 to 65535
951 inclusive. The default value of 1024 is generally fine for all
952 standard usages. Some specific cases of long captures or
Davor Ocelice9ed2812017-12-25 17:49:28 +0100953 JSON-formatted logs may require larger values. You may also need to
954 increase "tune.http.logurilen" if your request URIs are truncated.
Willy Tarreau18324f52014-06-27 18:10:07 +0200955
Dragan Dosen7ad31542015-09-28 17:16:47 +0200956 <format> is the log format used when generating syslog messages. It may be
957 one of the following :
958
959 rfc3164 The RFC3164 syslog message format. This is the default.
960 (https://tools.ietf.org/html/rfc3164)
961
962 rfc5424 The RFC5424 syslog message format.
963 (https://tools.ietf.org/html/rfc5424)
964
Willy Tarreaue8746a02018-11-12 08:45:00 +0100965 short A message containing only a level between angle brackets such as
966 '<3>', followed by the text. The PID, date, time, process name
967 and system name are omitted. This is designed to be used with a
968 local log server. This format is compatible with what the systemd
969 logger consumes.
970
Willy Tarreauc1b06452018-11-12 11:57:56 +0100971 raw A message containing only the text. The level, PID, date, time,
972 process name and system name are omitted. This is designed to be
973 used in containers or during development, where the severity only
974 depends on the file descriptor used (stdout/stderr).
975
Frédéric Lécailled690dfa2019-04-25 10:52:17 +0200976 <ranges> A list of comma-separated ranges to identify the logs to sample.
977 This is used to balance the load of the logs to send to the log
978 server. The limits of the ranges cannot be null. They are numbered
979 from 1. The size or period (in number of logs) of the sample must be
980 set with <sample_size> parameter.
981
982 <sample_size>
983 The size of the sample in number of logs to consider when balancing
984 their logging loads. It is used to balance the load of the logs to
985 send to the syslog server. This size must be greater or equal to the
986 maximum of the high limits of the ranges.
987 (see also <ranges> parameter).
988
Robert Tsai81ae1952007-12-05 10:47:29 +0100989 <facility> must be one of the 24 standard syslog facilities :
Willy Tarreau6a06a402007-07-15 20:15:28 +0200990
Willy Tarreaue8746a02018-11-12 08:45:00 +0100991 kern user mail daemon auth syslog lpr news
992 uucp cron auth2 ftp ntp audit alert cron2
993 local0 local1 local2 local3 local4 local5 local6 local7
994
Willy Tarreauc1b06452018-11-12 11:57:56 +0100995 Note that the facility is ignored for the "short" and "raw"
996 formats, but still required as a positional field. It is
997 recommended to use "daemon" in this case to make it clear that
998 it's only supposed to be used locally.
Willy Tarreau6a06a402007-07-15 20:15:28 +0200999
1000 An optional level can be specified to filter outgoing messages. By default,
Willy Tarreauf7edefa2009-05-10 17:20:05 +02001001 all messages are sent. If a maximum level is specified, only messages with a
1002 severity at least as important as this level will be sent. An optional minimum
1003 level can be specified. If it is set, logs emitted with a more severe level
1004 than this one will be capped to this level. This is used to avoid sending
1005 "emerg" messages on all terminals on some default syslog configurations.
1006 Eight levels are known :
Willy Tarreau6a06a402007-07-15 20:15:28 +02001007
Cyril Bontédc4d9032012-04-08 21:57:39 +02001008 emerg alert crit err warning notice info debug
Willy Tarreau6a06a402007-07-15 20:15:28 +02001009
Joe Williamsdf5b38f2010-12-29 17:05:48 +01001010log-send-hostname [<string>]
1011 Sets the hostname field in the syslog header. If optional "string" parameter
1012 is set the header is set to the string contents, otherwise uses the hostname
1013 of the system. Generally used if one is not relaying logs through an
1014 intermediate syslog server or for simply customizing the hostname printed in
1015 the logs.
1016
Kevinm48936af2010-12-22 16:08:21 +00001017log-tag <string>
1018 Sets the tag field in the syslog header to this string. It defaults to the
1019 program name as launched from the command line, which usually is "haproxy".
1020 Sometimes it can be useful to differentiate between multiple processes
Willy Tarreau094af4e2015-01-07 15:03:42 +01001021 running on the same host. See also the per-proxy "log-tag" directive.
Kevinm48936af2010-12-22 16:08:21 +00001022
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001023lua-load <file>
1024 This global directive loads and executes a Lua file. This directive can be
1025 used multiple times.
1026
William Lallemand4cfede82017-11-24 22:02:34 +01001027master-worker [no-exit-on-failure]
William Lallemande202b1e2017-06-01 17:38:56 +02001028 Master-worker mode. It is equivalent to the command line "-W" argument.
1029 This mode will launch a "master" which will monitor the "workers". Using
1030 this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001031 the master. The master-worker mode is compatible either with the foreground
William Lallemande202b1e2017-06-01 17:38:56 +02001032 or daemon mode. It is recommended to use this mode with multiprocess and
1033 systemd.
William Lallemand4cfede82017-11-24 22:02:34 +01001034 By default, if a worker exits with a bad return code, in the case of a
1035 segfault for example, all workers will be killed, and the master will leave.
1036 It is convenient to combine this behavior with Restart=on-failure in a
1037 systemd unit file in order to relaunch the whole process. If you don't want
1038 this behavior, you must use the keyword "no-exit-on-failure".
William Lallemande202b1e2017-06-01 17:38:56 +02001039
William Lallemand4cfede82017-11-24 22:02:34 +01001040 See also "-W" in the management guide.
William Lallemande202b1e2017-06-01 17:38:56 +02001041
William Lallemand27edc4b2019-05-07 17:49:33 +02001042mworker-max-reloads <number>
1043 In master-worker mode, this option limits the number of time a worker can
John Roesler27c754c2019-07-10 15:45:51 -05001044 survive to a reload. If the worker did not leave after a reload, once its
William Lallemand27edc4b2019-05-07 17:49:33 +02001045 number of reloads is greater than this number, the worker will receive a
1046 SIGTERM. This option helps to keep under control the number of workers.
1047 See also "show proc" in the Management Guide.
1048
Willy Tarreau6a06a402007-07-15 20:15:28 +02001049nbproc <number>
1050 Creates <number> processes when going daemon. This requires the "daemon"
1051 mode. By default, only one process is created, which is the recommended mode
1052 of operation. For systems limited to small sets of file descriptors per
Willy Tarreau149ab772019-01-26 14:27:06 +01001053 process, it may be needed to fork multiple daemons. When set to a value
1054 larger than 1, threads are automatically disabled. USING MULTIPLE PROCESSES
Willy Tarreau1f672a82019-01-26 14:20:55 +01001055 IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon" and
1056 "nbthread".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001057
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001058nbthread <number>
1059 This setting is only available when support for threads was built in. It
Willy Tarreau26f6ae12019-02-02 12:56:15 +01001060 makes haproxy run on <number> threads. This is exclusive with "nbproc". While
1061 "nbproc" historically used to be the only way to use multiple processors, it
1062 also involved a number of shortcomings related to the lack of synchronization
1063 between processes (health-checks, peers, stick-tables, stats, ...) which do
1064 not affect threads. As such, any modern configuration is strongly encouraged
Willy Tarreau149ab772019-01-26 14:27:06 +01001065 to migrate away from "nbproc" to "nbthread". "nbthread" also works when
1066 HAProxy is started in foreground. On some platforms supporting CPU affinity,
1067 when nbproc is not used, the default "nbthread" value is automatically set to
1068 the number of CPUs the process is bound to upon startup. This means that the
1069 thread count can easily be adjusted from the calling process using commands
1070 like "taskset" or "cpuset". Otherwise, this value defaults to 1. The default
1071 value is reported in the output of "haproxy -vv". See also "nbproc".
Christopher Fauletbe0faa22017-08-29 15:37:10 +02001072
Willy Tarreau6a06a402007-07-15 20:15:28 +02001073pidfile <pidfile>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001074 Writes PIDs of all daemons into file <pidfile>. This option is equivalent to
Willy Tarreau6a06a402007-07-15 20:15:28 +02001075 the "-p" command line argument. The file must be accessible to the user
1076 starting the process. See also "daemon".
1077
Willy Tarreau1d549722016-02-16 12:41:57 +01001078presetenv <name> <value>
1079 Sets environment variable <name> to value <value>. If the variable exists, it
1080 is NOT overwritten. The changes immediately take effect so that the next line
1081 in the configuration file sees the new value. See also "setenv", "resetenv",
1082 and "unsetenv".
1083
1084resetenv [<name> ...]
1085 Removes all environment variables except the ones specified in argument. It
1086 allows to use a clean controlled environment before setting new values with
1087 setenv or unsetenv. Please note that some internal functions may make use of
1088 some environment variables, such as time manipulation functions, but also
1089 OpenSSL or even external checks. This must be used with extreme care and only
1090 after complete validation. The changes immediately take effect so that the
1091 next line in the configuration file sees the new environment. See also
1092 "setenv", "presetenv", and "unsetenv".
1093
Christopher Fauletff4121f2017-11-22 16:38:49 +01001094stats bind-process [ all | odd | even | <process_num>[-[process_num>]] ] ...
Willy Tarreau35b7b162012-10-22 23:17:18 +02001095 Limits the stats socket to a certain set of processes numbers. By default the
1096 stats socket is bound to all processes, causing a warning to be emitted when
1097 nbproc is greater than 1 because there is no way to select the target process
1098 when connecting. However, by using this setting, it becomes possible to pin
1099 the stats socket to a specific set of processes, typically the first one. The
1100 warning will automatically be disabled when this setting is used, whatever
Willy Tarreaua9db57e2013-01-18 11:29:29 +01001101 the number of processes used. The maximum process ID depends on the machine's
Christopher Fauletff4121f2017-11-22 16:38:49 +01001102 word size (32 or 64). Ranges can be partially defined. The higher bound can
1103 be omitted. In such case, it is replaced by the corresponding maximum
1104 value. A better option consists in using the "process" setting of the "stats
1105 socket" line to force the process on each line.
Willy Tarreau35b7b162012-10-22 23:17:18 +02001106
Baptiste Assmann5626f482015-08-23 10:00:10 +02001107server-state-base <directory>
1108 Specifies the directory prefix to be prepended in front of all servers state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001109 file names which do not start with a '/'. See also "server-state-file",
1110 "load-server-state-from-file" and "server-state-file-name".
Baptiste Assmannef1f0fc2015-08-23 10:06:39 +02001111
1112server-state-file <file>
1113 Specifies the path to the file containing state of servers. If the path starts
1114 with a slash ('/'), it is considered absolute, otherwise it is considered
1115 relative to the directory specified using "server-state-base" (if set) or to
1116 the current directory. Before reloading HAProxy, it is possible to save the
1117 servers' current state using the stats command "show servers state". The
1118 output of this command must be written in the file pointed by <file>. When
1119 starting up, before handling traffic, HAProxy will read, load and apply state
1120 for each server found in the file and available in its current running
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02001121 configuration. See also "server-state-base" and "show servers state",
1122 "load-server-state-from-file" and "server-state-file-name"
Baptiste Assmann5626f482015-08-23 10:00:10 +02001123
Willy Tarreau1d549722016-02-16 12:41:57 +01001124setenv <name> <value>
1125 Sets environment variable <name> to value <value>. If the variable exists, it
1126 is overwritten. The changes immediately take effect so that the next line in
1127 the configuration file sees the new value. See also "presetenv", "resetenv",
1128 and "unsetenv".
1129
Willy Tarreau636848a2019-04-15 19:38:50 +02001130set-dumpable
1131 This option is better left disabled by default and enabled only upon a
1132 developer's request. It has no impact on performance nor stability but will
1133 try hard to re-enable core dumps that were possibly disabled by file size
1134 limitations (ulimit -f), core size limitations (ulimit -c), or "dumpability"
1135 of a process after changing its UID/GID (such as /proc/sys/fs/suid_dumpable
1136 on Linux). Core dumps might still be limited by the current directory's
1137 permissions (check what directory the file is started from), the chroot
1138 directory's permission (it may be needed to temporarily disable the chroot
1139 directive or to move it to a dedicated writable location), or any other
1140 system-specific constraint. For example, some Linux flavours are notorious
1141 for replacing the default core file with a path to an executable not even
1142 installed on the system (check /proc/sys/kernel/core_pattern). Often, simply
1143 writing "core", "core.%p" or "/var/log/core/core.%p" addresses the issue.
1144 When trying to enable this option waiting for a rare issue to re-appear, it's
1145 often a good idea to first try to obtain such a dump by issuing, for example,
1146 "kill -11" to the haproxy process and verify that it leaves a core where
1147 expected when dying.
1148
Willy Tarreau610f04b2014-02-13 11:36:41 +01001149ssl-default-bind-ciphers <ciphers>
1150 This setting is only available when support for OpenSSL was built in. It sets
1151 the default string describing the list of cipher algorithms ("cipher suite")
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001152 that are negotiated during the SSL/TLS handshake up to TLSv1.2 for all
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001153 "bind" lines which do not explicitly define theirs. The format of the string
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001154 is defined in "man 1 ciphers" from OpenSSL man pages. For background
1155 information and recommendations see e.g.
1156 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1157 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
1158 cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword.
1159 Please check the "bind" keyword for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001160
1161ssl-default-bind-ciphersuites <ciphersuites>
1162 This setting is only available when support for OpenSSL was built in and
1163 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
1164 describing the list of cipher algorithms ("cipher suite") that are negotiated
1165 during the TLSv1.3 handshake for all "bind" lines which do not explicitly define
1166 theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001167 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1168 cipher configuration for TLSv1.2 and earlier, please check the
1169 "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001170 information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001171
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001172ssl-default-bind-options [<option>]...
1173 This setting is only available when support for OpenSSL was built in. It sets
1174 default ssl-options to force on all "bind" lines. Please check the "bind"
1175 keyword to see available options.
1176
1177 Example:
1178 global
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +02001179 ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001180
Willy Tarreau610f04b2014-02-13 11:36:41 +01001181ssl-default-server-ciphers <ciphers>
1182 This setting is only available when support for OpenSSL was built in. It
1183 sets the default string describing the list of cipher algorithms that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +00001184 negotiated during the SSL/TLS handshake up to TLSv1.2 with the server,
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001185 for all "server" lines which do not explicitly define theirs. The format of
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001186 the string is defined in "man 1 ciphers" from OpenSSL man pages. For background
1187 information and recommendations see e.g.
1188 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
1189 (https://mozilla.github.io/server-side-tls/ssl-config-generator/).
1190 For TLSv1.3 cipher configuration, please check the
1191 "ssl-default-server-ciphersuites" keyword. Please check the "server" keyword
1192 for more information.
Dirkjan Bussink415150f2018-09-14 11:14:21 +02001193
1194ssl-default-server-ciphersuites <ciphersuites>
1195 This setting is only available when support for OpenSSL was built in and
1196 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
1197 string describing the list of cipher algorithms that are negotiated during
1198 the TLSv1.3 handshake with the server, for all "server" lines which do not
1199 explicitly define theirs. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +00001200 "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
1201 cipher configuration for TLSv1.2 and earlier, please check the
1202 "ssl-default-server-ciphers" keyword. Please check the "server" keyword for
1203 more information.
Willy Tarreau610f04b2014-02-13 11:36:41 +01001204
Emeric Brun2c86cbf2014-10-30 15:56:50 +01001205ssl-default-server-options [<option>]...
1206 This setting is only available when support for OpenSSL was built in. It sets
1207 default ssl-options to force on all "server" lines. Please check the "server"
1208 keyword to see available options.
1209
Remi Gacogne47783ef2015-05-29 15:53:22 +02001210ssl-dh-param-file <file>
1211 This setting is only available when support for OpenSSL was built in. It sets
1212 the default DH parameters that are used during the SSL/TLS handshake when
1213 ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines
Davor Ocelice9ed2812017-12-25 17:49:28 +01001214 which do not explicitly define theirs. It will be overridden by custom DH
Remi Gacogne47783ef2015-05-29 15:53:22 +02001215 parameters found in a bind certificate file if any. If custom DH parameters
Cyril Bonté307ee1e2015-09-28 23:16:06 +02001216 are not specified either by using ssl-dh-param-file or by setting them
1217 directly in the certificate file, pre-generated DH parameters of the size
1218 specified by tune.ssl.default-dh-param will be used. Custom parameters are
1219 known to be more secure and therefore their use is recommended.
Remi Gacogne47783ef2015-05-29 15:53:22 +02001220 Custom DH parameters may be generated by using the OpenSSL command
1221 "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
1222 parameters should not be considered secure anymore.
1223
Emeric Brun850efd52014-01-29 12:24:34 +01001224ssl-server-verify [none|required]
1225 The default behavior for SSL verify on servers side. If specified to 'none',
1226 servers certificates are not verified. The default is 'required' except if
1227 forced using cmdline option '-dV'.
1228
Willy Tarreauabb175f2012-09-24 12:43:26 +02001229stats socket [<address:port>|<path>] [param*]
1230 Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
1231 Connections to this socket will return various statistics outputs and even
1232 allow some commands to be issued to change some runtime settings. Please
Willy Tarreau1af20c72017-06-23 16:01:14 +02001233 consult section 9.3 "Unix Socket commands" of Management Guide for more
Kevin Decherf949c7202015-10-13 23:26:44 +02001234 details.
Willy Tarreau6162db22009-10-10 17:13:00 +02001235
Willy Tarreauabb175f2012-09-24 12:43:26 +02001236 All parameters supported by "bind" lines are supported, for instance to
1237 restrict access to some users or their access rights. Please consult
1238 section 5.1 for more information.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001239
1240stats timeout <timeout, in milliseconds>
1241 The default timeout on the stats socket is set to 10 seconds. It is possible
1242 to change this value with "stats timeout". The value must be passed in
Willy Tarreaubefdff12007-12-02 22:27:38 +01001243 milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
Willy Tarreaufbee7132007-10-18 13:53:22 +02001244
1245stats maxconn <connections>
1246 By default, the stats socket is limited to 10 concurrent connections. It is
1247 possible to change this value with "stats maxconn".
1248
Willy Tarreau6a06a402007-07-15 20:15:28 +02001249uid <number>
1250 Changes the process' user ID to <number>. It is recommended that the user ID
1251 is dedicated to HAProxy or to a small set of similar daemons. HAProxy must
1252 be started with superuser privileges in order to be able to switch to another
1253 one. See also "gid" and "user".
1254
1255ulimit-n <number>
1256 Sets the maximum number of per-process file-descriptors to <number>. By
1257 default, it is automatically computed, so it is recommended not to use this
1258 option.
1259
Willy Tarreauceb24bc2010-11-09 12:46:41 +01001260unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ]
1261 [ group <group> ] [ gid <gid> ]
1262
1263 Fixes common settings to UNIX listening sockets declared in "bind" statements.
1264 This is mainly used to simplify declaration of those UNIX sockets and reduce
1265 the risk of errors, since those settings are most commonly required but are
1266 also process-specific. The <prefix> setting can be used to force all socket
1267 path to be relative to that directory. This might be needed to access another
1268 component's chroot. Note that those paths are resolved before haproxy chroots
1269 itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
1270 all have the same meaning as their homonyms used by the "bind" statement. If
1271 both are specified, the "bind" statement has priority, meaning that the
1272 "unix-bind" settings may be seen as process-wide default settings.
1273
Willy Tarreau1d549722016-02-16 12:41:57 +01001274unsetenv [<name> ...]
1275 Removes environment variables specified in arguments. This can be useful to
1276 hide some sensitive information that are occasionally inherited from the
1277 user's environment during some operations. Variables which did not exist are
1278 silently ignored so that after the operation, it is certain that none of
1279 these variables remain. The changes immediately take effect so that the next
1280 line in the configuration file will not see these variables. See also
1281 "setenv", "presetenv", and "resetenv".
1282
Willy Tarreau6a06a402007-07-15 20:15:28 +02001283user <user name>
1284 Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
1285 See also "uid" and "group".
1286
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02001287node <name>
1288 Only letters, digits, hyphen and underscore are allowed, like in DNS names.
1289
1290 This statement is useful in HA configurations where two or more processes or
1291 servers share the same IP address. By setting a different node-name on all
1292 nodes, it becomes easy to immediately spot what server is handling the
1293 traffic.
1294
1295description <text>
1296 Add a text that describes the instance.
1297
1298 Please note that it is required to escape certain characters (# for example)
1299 and this text is inserted into a html page so you should avoid using
1300 "<" and ">" characters.
1301
Thomas Holmesdb04f192015-05-18 13:21:39 +0100130251degrees-data-file <file path>
1303 The path of the 51Degrees data file to provide device detection services. The
Davor Ocelice9ed2812017-12-25 17:49:28 +01001304 file should be unzipped and accessible by HAProxy with relevant permissions.
Thomas Holmesdb04f192015-05-18 13:21:39 +01001305
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001306 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001307 compiled with USE_51DEGREES.
1308
Ben Shillitof25e8e52016-12-02 14:25:37 +0000130951degrees-property-name-list [<string> ...]
Thomas Holmesdb04f192015-05-18 13:21:39 +01001310 A list of 51Degrees property names to be load from the dataset. A full list
1311 of names is available on the 51Degrees website:
1312 https://51degrees.com/resources/property-dictionary
1313
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001314 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001315 compiled with USE_51DEGREES.
1316
Dragan Dosen93b38d92015-06-29 16:43:25 +0200131751degrees-property-separator <char>
Thomas Holmesdb04f192015-05-18 13:21:39 +01001318 A char that will be appended to every property value in a response header
1319 containing 51Degrees results. If not set that will be set as ','.
1320
Dragan Dosenae6d39a2015-06-29 16:43:27 +02001321 Please note that this option is only available when haproxy has been
1322 compiled with USE_51DEGREES.
1323
132451degrees-cache-size <number>
1325 Sets the size of the 51Degrees converter cache to <number> entries. This
1326 is an LRU cache which reminds previous device detections and their results.
1327 By default, this cache is disabled.
1328
1329 Please note that this option is only available when haproxy has been
Thomas Holmesdb04f192015-05-18 13:21:39 +01001330 compiled with USE_51DEGREES.
1331
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001332wurfl-data-file <file path>
1333 The path of the WURFL data file to provide device detection services. The
1334 file should be accessible by HAProxy with relevant permissions.
1335
1336 Please note that this option is only available when haproxy has been compiled
1337 with USE_WURFL=1.
1338
1339wurfl-information-list [<capability>]*
1340 A space-delimited list of WURFL capabilities, virtual capabilities, property
1341 names we plan to use in injected headers. A full list of capability and
1342 virtual capability names is available on the Scientiamobile website :
1343
1344 https://www.scientiamobile.com/wurflCapability
1345
1346 Valid WURFL properties are:
1347 - wurfl_id Contains the device ID of the matched device.
1348
1349 - wurfl_root_id Contains the device root ID of the matched
1350 device.
1351
1352 - wurfl_isdevroot Tells if the matched device is a root device.
1353 Possible values are "TRUE" or "FALSE".
1354
1355 - wurfl_useragent The original useragent coming with this
1356 particular web request.
1357
1358 - wurfl_api_version Contains a string representing the currently
1359 used Libwurfl API version.
1360
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001361 - wurfl_info A string containing information on the parsed
1362 wurfl.xml and its full path.
1363
1364 - wurfl_last_load_time Contains the UNIX timestamp of the last time
1365 WURFL has been loaded successfully.
1366
1367 - wurfl_normalized_useragent The normalized useragent.
1368
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001369 Please note that this option is only available when haproxy has been compiled
1370 with USE_WURFL=1.
1371
1372wurfl-information-list-separator <char>
1373 A char that will be used to separate values in a response header containing
1374 WURFL results. If not set that a comma (',') will be used by default.
1375
1376 Please note that this option is only available when haproxy has been compiled
1377 with USE_WURFL=1.
1378
1379wurfl-patch-file [<file path>]
1380 A list of WURFL patch file paths. Note that patches are loaded during startup
1381 thus before the chroot.
1382
1383 Please note that this option is only available when haproxy has been compiled
1384 with USE_WURFL=1.
1385
paulborilebad132c2019-04-18 11:57:04 +02001386wurfl-cache-size <size>
1387 Sets the WURFL Useragent cache size. For faster lookups, already processed user
1388 agents are kept in a LRU cache :
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001389 - "0" : no cache is used.
paulborilebad132c2019-04-18 11:57:04 +02001390 - <size> : size of lru cache in elements.
Willy Tarreaub3cc9f22019-04-19 16:03:32 +02001391
1392 Please note that this option is only available when haproxy has been compiled
1393 with USE_WURFL=1.
1394
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013953.2. Performance tuning
Willy Tarreau6a06a402007-07-15 20:15:28 +02001396-----------------------
1397
Willy Tarreaubeb859a2018-11-22 18:07:59 +01001398busy-polling
1399 In some situations, especially when dealing with low latency on processors
1400 supporting a variable frequency or when running inside virtual machines, each
1401 time the process waits for an I/O using the poller, the processor goes back
1402 to sleep or is offered to another VM for a long time, and it causes
1403 excessively high latencies. This option provides a solution preventing the
1404 processor from sleeping by always using a null timeout on the pollers. This
1405 results in a significant latency reduction (30 to 100 microseconds observed)
1406 at the expense of a risk to overheat the processor. It may even be used with
1407 threads, in which case improperly bound threads may heavily conflict,
1408 resulting in a worse performance and high values for the CPU stolen fields
1409 in "show info" output, indicating which threads are misconfigured. It is
1410 important not to let the process run on the same processor as the network
1411 interrupts when this option is used. It is also better to avoid using it on
1412 multiple CPU threads sharing the same core. This option is disabled by
1413 default. If it has been enabled, it may still be forcibly disabled by
1414 prefixing it with the "no" keyword. It is ignored by the "select" and
1415 "poll" pollers.
1416
William Dauchy857b9432019-12-28 15:36:02 +01001417 This option is automatically disabled on old processes in the context of
1418 seamless reload; it avoids too much cpu conflicts when multiple processes
1419 stay around for some time waiting for the end of their current connections.
1420
Willy Tarreau1746eec2014-04-25 10:46:47 +02001421max-spread-checks <delay in milliseconds>
1422 By default, haproxy tries to spread the start of health checks across the
1423 smallest health check interval of all the servers in a farm. The principle is
1424 to avoid hammering services running on the same server. But when using large
1425 check intervals (10 seconds or more), the last servers in the farm take some
1426 time before starting to be tested, which can be a problem. This parameter is
1427 used to enforce an upper bound on delay between the first and the last check,
1428 even if the servers' check intervals are larger. When servers run with
1429 shorter intervals, their intervals will be respected though.
1430
Willy Tarreau6a06a402007-07-15 20:15:28 +02001431maxconn <number>
1432 Sets the maximum per-process number of concurrent connections to <number>. It
1433 is equivalent to the command-line argument "-n". Proxies will stop accepting
1434 connections when this limit is reached. The "ulimit-n" parameter is
Willy Tarreau8274e102014-06-19 15:31:25 +02001435 automatically adjusted according to this value. See also "ulimit-n". Note:
1436 the "select" poller cannot reliably use more than 1024 file descriptors on
1437 some platforms. If your platform only supports select and reports "select
1438 FAILED" on startup, you need to reduce maxconn until it works (slightly
Willy Tarreaub28f3442019-03-04 08:13:43 +01001439 below 500 in general). If this value is not set, it will automatically be
1440 calculated based on the current file descriptors limit reported by the
1441 "ulimit -n" command, possibly reduced to a lower value if a memory limit
1442 is enforced, based on the buffer size, memory allocated to compression, SSL
1443 cache size, and use or not of SSL and the associated maxsslconn (which can
1444 also be automatic).
Willy Tarreau6a06a402007-07-15 20:15:28 +02001445
Willy Tarreau81c25d02011-09-07 15:17:21 +02001446maxconnrate <number>
1447 Sets the maximum per-process number of connections per second to <number>.
1448 Proxies will stop accepting connections when this limit is reached. It can be
1449 used to limit the global capacity regardless of each frontend capacity. It is
1450 important to note that this can only be used as a service protection measure,
1451 as there will not necessarily be a fair share between frontends when the
1452 limit is reached, so it's a good idea to also limit each frontend to some
1453 value close to its expected share. Also, lowering tune.maxaccept can improve
1454 fairness.
1455
William Lallemandd85f9172012-11-09 17:05:39 +01001456maxcomprate <number>
1457 Sets the maximum per-process input compression rate to <number> kilobytes
Davor Ocelice9ed2812017-12-25 17:49:28 +01001458 per second. For each session, if the maximum is reached, the compression
William Lallemandd85f9172012-11-09 17:05:39 +01001459 level will be decreased during the session. If the maximum is reached at the
1460 beginning of a session, the session will not compress at all. If the maximum
1461 is not reached, the compression level will be increased up to
Davor Ocelice9ed2812017-12-25 17:49:28 +01001462 tune.comp.maxlevel. A value of zero means there is no limit, this is the
William Lallemandd85f9172012-11-09 17:05:39 +01001463 default value.
1464
William Lallemand072a2bf2012-11-20 17:01:01 +01001465maxcompcpuusage <number>
1466 Sets the maximum CPU usage HAProxy can reach before stopping the compression
1467 for new requests or decreasing the compression level of current requests.
1468 It works like 'maxcomprate' but measures CPU usage instead of incoming data
1469 bandwidth. The value is expressed in percent of the CPU used by haproxy. In
1470 case of multiple processes (nbproc > 1), each process manages its individual
1471 usage. A value of 100 disable the limit. The default value is 100. Setting
1472 a lower value will prevent the compression work from slowing the whole
1473 process down and from introducing high latencies.
1474
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001475maxpipes <number>
1476 Sets the maximum per-process number of pipes to <number>. Currently, pipes
1477 are only used by kernel-based tcp splicing. Since a pipe contains two file
1478 descriptors, the "ulimit-n" value will be increased accordingly. The default
1479 value is maxconn/4, which seems to be more than enough for most heavy usages.
1480 The splice code dynamically allocates and releases pipes, and can fall back
1481 to standard copy, so setting this value too low may only impact performance.
1482
Willy Tarreau93e7c002013-10-07 18:51:07 +02001483maxsessrate <number>
1484 Sets the maximum per-process number of sessions per second to <number>.
1485 Proxies will stop accepting connections when this limit is reached. It can be
1486 used to limit the global capacity regardless of each frontend capacity. It is
1487 important to note that this can only be used as a service protection measure,
1488 as there will not necessarily be a fair share between frontends when the
1489 limit is reached, so it's a good idea to also limit each frontend to some
1490 value close to its expected share. Also, lowering tune.maxaccept can improve
1491 fairness.
1492
Willy Tarreau403edff2012-09-06 11:58:37 +02001493maxsslconn <number>
1494 Sets the maximum per-process number of concurrent SSL connections to
1495 <number>. By default there is no SSL-specific limit, which means that the
1496 global maxconn setting will apply to all connections. Setting this limit
1497 avoids having openssl use too much memory and crash when malloc returns NULL
1498 (since it unfortunately does not reliably check for such conditions). Note
1499 that the limit applies both to incoming and outgoing connections, so one
1500 connection which is deciphered then ciphered accounts for 2 SSL connections.
Willy Tarreaud0256482015-01-15 21:45:22 +01001501 If this value is not set, but a memory limit is enforced, this value will be
1502 automatically computed based on the memory limit, maxconn, the buffer size,
1503 memory allocated to compression, SSL cache size, and use of SSL in either
1504 frontends, backends or both. If neither maxconn nor maxsslconn are specified
1505 when there is a memory limit, haproxy will automatically adjust these values
1506 so that 100% of the connections can be made over SSL with no risk, and will
1507 consider the sides where it is enabled (frontend, backend, both).
Willy Tarreau403edff2012-09-06 11:58:37 +02001508
Willy Tarreaue43d5322013-10-07 20:01:52 +02001509maxsslrate <number>
1510 Sets the maximum per-process number of SSL sessions per second to <number>.
1511 SSL listeners will stop accepting connections when this limit is reached. It
1512 can be used to limit the global SSL CPU usage regardless of each frontend
1513 capacity. It is important to note that this can only be used as a service
1514 protection measure, as there will not necessarily be a fair share between
1515 frontends when the limit is reached, so it's a good idea to also limit each
1516 frontend to some value close to its expected share. It is also important to
1517 note that the sessions are accounted before they enter the SSL stack and not
1518 after, which also protects the stack against bad handshakes. Also, lowering
1519 tune.maxaccept can improve fairness.
1520
William Lallemand9d5f5482012-11-07 16:12:57 +01001521maxzlibmem <number>
1522 Sets the maximum amount of RAM in megabytes per process usable by the zlib.
1523 When the maximum amount is reached, future sessions will not compress as long
1524 as RAM is unavailable. When sets to 0, there is no limit.
William Lallemande3a7d992012-11-20 11:25:20 +01001525 The default value is 0. The value is available in bytes on the UNIX socket
1526 with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is
1527 "ZlibMemUsage" in bytes.
1528
Willy Tarreau6a06a402007-07-15 20:15:28 +02001529noepoll
1530 Disables the use of the "epoll" event polling system on Linux. It is
1531 equivalent to the command-line argument "-de". The next polling system
Willy Tarreaue9f49e72012-11-11 17:42:00 +01001532 used will generally be "poll". See also "nopoll".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001533
1534nokqueue
1535 Disables the use of the "kqueue" event polling system on BSD. It is
1536 equivalent to the command-line argument "-dk". The next polling system
1537 used will generally be "poll". See also "nopoll".
1538
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001539noevports
1540 Disables the use of the event ports event polling system on SunOS systems
1541 derived from Solaris 10 and later. It is equivalent to the command-line
1542 argument "-dv". The next polling system used will generally be "poll". See
1543 also "nopoll".
1544
Willy Tarreau6a06a402007-07-15 20:15:28 +02001545nopoll
1546 Disables the use of the "poll" event polling system. It is equivalent to the
1547 command-line argument "-dp". The next polling system used will be "select".
Willy Tarreau0ba27502007-12-24 16:55:16 +01001548 It should never be needed to disable "poll" since it's available on all
Emmanuel Hocdet0ba4f482019-04-08 16:53:32 +00001549 platforms supported by HAProxy. See also "nokqueue", "noepoll" and
1550 "noevports".
Willy Tarreau6a06a402007-07-15 20:15:28 +02001551
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001552nosplice
1553 Disables the use of kernel tcp splicing between sockets on Linux. It is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001554 equivalent to the command line argument "-dS". Data will then be copied
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001555 using conventional and more portable recv/send calls. Kernel tcp splicing is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01001556 limited to some very recent instances of kernel 2.6. Most versions between
Willy Tarreauff4f82d2009-02-06 11:28:13 +01001557 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not
1558 be used. This option makes it easier to globally disable kernel splicing in
1559 case of doubt. See also "option splice-auto", "option splice-request" and
1560 "option splice-response".
1561
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001562nogetaddrinfo
1563 Disables the use of getaddrinfo(3) for name resolving. It is equivalent to
1564 the command line argument "-dG". Deprecated gethostbyname(3) will be used.
1565
Lukas Tribusa0bcbdc2016-09-12 21:42:20 +00001566noreuseport
1567 Disables the use of SO_REUSEPORT - see socket(7). It is equivalent to the
1568 command line argument "-dR".
1569
Willy Tarreaud2d33482019-04-25 17:09:07 +02001570profiling.tasks { auto | on | off }
1571 Enables ('on') or disables ('off') per-task CPU profiling. When set to 'auto'
1572 the profiling automatically turns on a thread when it starts to suffer from
1573 an average latency of 1000 microseconds or higher as reported in the
1574 "avg_loop_us" activity field, and automatically turns off when the latency
John Roesler27c754c2019-07-10 15:45:51 -05001575 returns below 990 microseconds (this value is an average over the last 1024
Willy Tarreaud2d33482019-04-25 17:09:07 +02001576 loops so it does not vary quickly and tends to significantly smooth short
1577 spikes). It may also spontaneously trigger from time to time on overloaded
1578 systems, containers, or virtual machines, or when the system swaps (which
1579 must absolutely never happen on a load balancer).
1580
1581 CPU profiling per task can be very convenient to report where the time is
1582 spent and which requests have what effect on which other request. Enabling
1583 it will typically affect the overall's performance by less than 1%, thus it
1584 is recommended to leave it to the default 'auto' value so that it only
1585 operates when a problem is identified. This feature requires a system
Willy Tarreau75c62c22018-11-22 11:02:09 +01001586 supporting the clock_gettime(2) syscall with clock identifiers
1587 CLOCK_MONOTONIC and CLOCK_THREAD_CPUTIME_ID, otherwise the reported time will
1588 be zero. This option may be changed at run time using "set profiling" on the
1589 CLI.
1590
Willy Tarreaufe255b72007-10-14 23:09:26 +02001591spread-checks <0..50, in percent>
Simon Hormand60d6912013-11-25 10:46:36 +09001592 Sometimes it is desirable to avoid sending agent and health checks to
1593 servers at exact intervals, for instance when many logical servers are
1594 located on the same physical server. With the help of this parameter, it
1595 becomes possible to add some randomness in the check interval between 0
1596 and +/- 50%. A value between 2 and 5 seems to show good results. The
1597 default value remains at 0.
Willy Tarreaufe255b72007-10-14 23:09:26 +02001598
Davor Ocelice9ed2812017-12-25 17:49:28 +01001599ssl-engine <name> [algo <comma-separated list of algorithms>]
Grant Zhang872f9c22017-01-21 01:10:18 +00001600 Sets the OpenSSL engine to <name>. List of valid values for <name> may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01001601 obtained using the command "openssl engine". This statement may be used
Grant Zhang872f9c22017-01-21 01:10:18 +00001602 multiple times, it will simply enable multiple crypto engines. Referencing an
1603 unsupported engine will prevent haproxy from starting. Note that many engines
1604 will lead to lower HTTPS performance than pure software with recent
1605 processors. The optional command "algo" sets the default algorithms an ENGINE
1606 will supply using the OPENSSL function ENGINE_set_default_string(). A value
Davor Ocelice9ed2812017-12-25 17:49:28 +01001607 of "ALL" uses the engine for all cryptographic operations. If no list of
1608 algo is specified then the value of "ALL" is used. A comma-separated list
Grant Zhang872f9c22017-01-21 01:10:18 +00001609 of different algorithms may be specified, including: RSA, DSA, DH, EC, RAND,
1610 CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. This is the same format that
1611 openssl configuration file uses:
1612 https://www.openssl.org/docs/man1.0.2/apps/config.html
1613
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001614ssl-mode-async
1615 Adds SSL_MODE_ASYNC mode to the SSL context. This enables asynchronous TLS
Emeric Brun3854e012017-05-17 20:42:48 +02001616 I/O operations if asynchronous capable SSL engines are used. The current
Emeric Brunb5e42a82017-06-06 12:35:14 +00001617 implementation supports a maximum of 32 engines. The Openssl ASYNC API
1618 doesn't support moving read/write buffers and is not compliant with
1619 haproxy's buffer management. So the asynchronous mode is disabled on
John Roesler27c754c2019-07-10 15:45:51 -05001620 read/write operations (it is only enabled during initial and renegotiation
Emeric Brunb5e42a82017-06-06 12:35:14 +00001621 handshakes).
Grant Zhangfa6c7ee2017-01-14 01:42:15 +00001622
Willy Tarreau33cb0652014-12-23 22:52:37 +01001623tune.buffers.limit <number>
1624 Sets a hard limit on the number of buffers which may be allocated per process.
1625 The default value is zero which means unlimited. The minimum non-zero value
1626 will always be greater than "tune.buffers.reserve" and should ideally always
1627 be about twice as large. Forcing this value can be particularly useful to
1628 limit the amount of memory a process may take, while retaining a sane
Davor Ocelice9ed2812017-12-25 17:49:28 +01001629 behavior. When this limit is reached, sessions which need a buffer wait for
Willy Tarreau33cb0652014-12-23 22:52:37 +01001630 another one to be released by another session. Since buffers are dynamically
1631 allocated and released, the waiting time is very short and not perceptible
1632 provided that limits remain reasonable. In fact sometimes reducing the limit
1633 may even increase performance by increasing the CPU cache's efficiency. Tests
1634 have shown good results on average HTTP traffic with a limit to 1/10 of the
1635 expected global maxconn setting, which also significantly reduces memory
1636 usage. The memory savings come from the fact that a number of connections
1637 will not allocate 2*tune.bufsize. It is best not to touch this value unless
1638 advised to do so by an haproxy core developer.
1639
Willy Tarreau1058ae72014-12-23 22:40:40 +01001640tune.buffers.reserve <number>
1641 Sets the number of buffers which are pre-allocated and reserved for use only
1642 during memory shortage conditions resulting in failed memory allocations. The
1643 minimum value is 2 and is also the default. There is no reason a user would
1644 want to change this value, it's mostly aimed at haproxy core developers.
1645
Willy Tarreau27a674e2009-08-17 07:23:33 +02001646tune.bufsize <number>
1647 Sets the buffer size to this size (in bytes). Lower values allow more
1648 sessions to coexist in the same amount of RAM, and higher values allow some
1649 applications with very large cookies to work. The default value is 16384 and
1650 can be changed at build time. It is strongly recommended not to change this
1651 from the default value, as very low values will break some services such as
1652 statistics, and values larger than default size will increase memory usage,
1653 possibly causing the system to run out of memory. At least the global maxconn
Willy Tarreau45a66cc2017-11-24 11:28:00 +01001654 parameter should be decreased by the same factor as this one is increased. In
1655 addition, use of HTTP/2 mandates that this value must be 16384 or more. If an
1656 HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will
Dmitry Sivachenkof6f4f7b2012-10-21 18:10:25 +04001657 return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger
Willy Tarreauc77d3642018-12-12 06:19:42 +01001658 than this size, haproxy will return HTTP 502 (Bad Gateway). Note that the
1659 value set using this parameter will automatically be rounded up to the next
1660 multiple of 8 on 32-bit machines and 16 on 64-bit machines.
Willy Tarreau27a674e2009-08-17 07:23:33 +02001661
Willy Tarreau43961d52010-10-04 20:39:20 +02001662tune.chksize <number>
1663 Sets the check buffer size to this size (in bytes). Higher values may help
1664 find string or regex patterns in very large pages, though doing so may imply
1665 more memory and CPU usage. The default value is 16384 and can be changed at
1666 build time. It is not recommended to change this value, but to use better
1667 checks whenever possible.
1668
William Lallemandf3747832012-11-09 12:33:10 +01001669tune.comp.maxlevel <number>
1670 Sets the maximum compression level. The compression level affects CPU
1671 usage during compression. This value affects CPU usage during compression.
1672 Each session using compression initializes the compression algorithm with
1673 this value. The default value is 1.
1674
Willy Tarreauc299e1e2019-02-27 11:35:12 +01001675tune.fail-alloc
1676 If compiled with DEBUG_FAIL_ALLOC, gives the percentage of chances an
1677 allocation attempt fails. Must be between 0 (no failure) and 100 (no
1678 success). This is useful to debug and make sure memory failures are handled
1679 gracefully.
1680
Willy Tarreaufe20e5b2017-07-27 11:42:14 +02001681tune.h2.header-table-size <number>
1682 Sets the HTTP/2 dynamic header table size. It defaults to 4096 bytes and
1683 cannot be larger than 65536 bytes. A larger value may help certain clients
1684 send more compact requests, depending on their capabilities. This amount of
1685 memory is consumed for each HTTP/2 connection. It is recommended not to
1686 change it.
1687
Willy Tarreaue6baec02017-07-27 11:45:11 +02001688tune.h2.initial-window-size <number>
1689 Sets the HTTP/2 initial window size, which is the number of bytes the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01001690 can upload before waiting for an acknowledgment from haproxy. This setting
1691 only affects payload contents (i.e. the body of POST requests), not headers.
Willy Tarreaue6baec02017-07-27 11:45:11 +02001692 The default value is 65535, which roughly allows up to 5 Mbps of upload
1693 bandwidth per client over a network showing a 100 ms ping time, or 500 Mbps
1694 over a 1-ms local network. It can make sense to increase this value to allow
1695 faster uploads, or to reduce it to increase fairness when dealing with many
1696 clients. It doesn't affect resource usage.
1697
Willy Tarreau5242ef82017-07-27 11:47:28 +02001698tune.h2.max-concurrent-streams <number>
1699 Sets the HTTP/2 maximum number of concurrent streams per connection (ie the
1700 number of outstanding requests on a single connection). The default value is
1701 100. A larger one may slightly improve page load time for complex sites when
1702 visited over high latency networks, but increases the amount of resources a
1703 single client may allocate. A value of zero disables the limit so a single
1704 client may create as many streams as allocatable by haproxy. It is highly
1705 recommended not to change this value.
1706
Willy Tarreaua24b35c2019-02-21 13:24:36 +01001707tune.h2.max-frame-size <number>
1708 Sets the HTTP/2 maximum frame size that haproxy announces it is willing to
1709 receive to its peers. The default value is the largest between 16384 and the
1710 buffer size (tune.bufsize). In any case, haproxy will not announce support
1711 for frame sizes larger than buffers. The main purpose of this setting is to
1712 allow to limit the maximum frame size setting when using large buffers. Too
1713 large frame sizes might have performance impact or cause some peers to
1714 misbehave. It is highly recommended not to change this value.
1715
Willy Tarreau193b8c62012-11-22 00:17:38 +01001716tune.http.cookielen <number>
1717 Sets the maximum length of captured cookies. This is the maximum value that
1718 the "capture cookie xxx len yyy" will be allowed to take, and any upper value
1719 will automatically be truncated to this one. It is important not to set too
1720 high a value because all cookie captures still allocate this size whatever
1721 their configured value (they share a same pool). This value is per request
1722 per response, so the memory allocated is twice this value per connection.
1723 When not specified, the limit is set to 63 characters. It is recommended not
1724 to change this value.
1725
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001726tune.http.logurilen <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001727 Sets the maximum length of request URI in logs. This prevents truncating long
1728 request URIs with valuable query strings in log lines. This is not related
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001729 to syslog limits. If you increase this limit, you may also increase the
Davor Ocelice9ed2812017-12-25 17:49:28 +01001730 'log ... len yyy' parameter. Your syslog daemon may also need specific
Stéphane Cottin23e9e932017-05-18 08:58:41 +02001731 configuration directives too.
1732 The default value is 1024.
1733
Willy Tarreauac1932d2011-10-24 19:14:41 +02001734tune.http.maxhdr <number>
1735 Sets the maximum number of headers in a request. When a request comes with a
1736 number of headers greater than this value (including the first line), it is
1737 rejected with a "400 Bad Request" status code. Similarly, too large responses
1738 are blocked with "502 Bad Gateway". The default value is 101, which is enough
1739 for all usages, considering that the widely deployed Apache server uses the
1740 same limit. It can be useful to push this limit further to temporarily allow
Christopher Faulet50174f32017-06-21 16:31:35 +02001741 a buggy application to work by the time it gets fixed. The accepted range is
1742 1..32767. Keep in mind that each new header consumes 32bits of memory for
1743 each session, so don't push this limit too high.
Willy Tarreauac1932d2011-10-24 19:14:41 +02001744
Willy Tarreau7e312732014-02-12 16:35:14 +01001745tune.idletimer <timeout>
1746 Sets the duration after which haproxy will consider that an empty buffer is
1747 probably associated with an idle stream. This is used to optimally adjust
1748 some packet sizes while forwarding large and small data alternatively. The
1749 decision to use splice() or to send large buffers in SSL is modulated by this
1750 parameter. The value is in milliseconds between 0 and 65535. A value of zero
1751 means that haproxy will not try to detect idle streams. The default is 1000,
Davor Ocelice9ed2812017-12-25 17:49:28 +01001752 which seems to correctly detect end user pauses (e.g. read a page before
John Roesler27c754c2019-07-10 15:45:51 -05001753 clicking). There should be no reason for changing this value. Please check
Willy Tarreau7e312732014-02-12 16:35:14 +01001754 tune.ssl.maxrecord below.
1755
Willy Tarreau7ac908b2019-02-27 12:02:18 +01001756tune.listener.multi-queue { on | off }
1757 Enables ('on') or disables ('off') the listener's multi-queue accept which
1758 spreads the incoming traffic to all threads a "bind" line is allowed to run
1759 on instead of taking them for itself. This provides a smoother traffic
1760 distribution and scales much better, especially in environments where threads
1761 may be unevenly loaded due to external activity (network interrupts colliding
1762 with one thread for example). This option is enabled by default, but it may
1763 be forcefully disabled for troubleshooting or for situations where it is
1764 estimated that the operating system already provides a good enough
1765 distribution and connections are extremely short-lived.
1766
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001767tune.lua.forced-yield <number>
1768 This directive forces the Lua engine to execute a yield each <number> of
Tim Düsterhus4896c442016-11-29 02:15:19 +01001769 instructions executed. This permits interrupting a long script and allows the
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001770 HAProxy scheduler to process other tasks like accepting connections or
1771 forwarding traffic. The default value is 10000 instructions. If HAProxy often
Davor Ocelice9ed2812017-12-25 17:49:28 +01001772 executes some Lua code but more responsiveness is required, this value can be
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001773 lowered. If the Lua code is quite long and its result is absolutely required
1774 to process the data, the <number> can be increased.
1775
Willy Tarreau32f61e22015-03-18 17:54:59 +01001776tune.lua.maxmem
1777 Sets the maximum amount of RAM in megabytes per process usable by Lua. By
1778 default it is zero which means unlimited. It is important to set a limit to
1779 ensure that a bug in a script will not result in the system running out of
1780 memory.
1781
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001782tune.lua.session-timeout <timeout>
1783 This is the execution timeout for the Lua sessions. This is useful for
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001784 preventing infinite loops or spending too much time in Lua. This timeout
1785 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001786 not taken in account. The default timeout is 4s.
Thierry FOURNIER90da1912015-03-05 11:17:06 +01001787
1788tune.lua.task-timeout <timeout>
1789 Purpose is the same as "tune.lua.session-timeout", but this timeout is
1790 dedicated to the tasks. By default, this timeout isn't set because a task may
1791 remain alive during of the lifetime of HAProxy. For example, a task used to
1792 check servers.
1793
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001794tune.lua.service-timeout <timeout>
1795 This is the execution timeout for the Lua services. This is useful for
1796 preventing infinite loops or spending too much time in Lua. This timeout
1797 counts only the pure Lua runtime. If the Lua does a sleep, the sleep is
Davor Ocelice9ed2812017-12-25 17:49:28 +01001798 not taken in account. The default timeout is 4s.
Thierry FOURNIER7dd784b2015-10-01 14:49:33 +02001799
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001800tune.maxaccept <number>
Willy Tarreau16a21472012-11-19 12:39:59 +01001801 Sets the maximum number of consecutive connections a process may accept in a
1802 row before switching to other work. In single process mode, higher numbers
1803 give better performance at high connection rates. However in multi-process
1804 modes, keeping a bit of fairness between processes generally is better to
1805 increase performance. This value applies individually to each listener, so
1806 that the number of processes a listener is bound to is taken into account.
1807 This value defaults to 64. In multi-process mode, it is divided by twice
1808 the number of processes the listener is bound to. Setting this value to -1
1809 completely disables the limitation. It should normally not be needed to tweak
1810 this value.
Willy Tarreaua0250ba2008-01-06 11:22:57 +01001811
1812tune.maxpollevents <number>
1813 Sets the maximum amount of events that can be processed at once in a call to
1814 the polling system. The default value is adapted to the operating system. It
1815 has been noticed that reducing it below 200 tends to slightly decrease
1816 latency at the expense of network bandwidth, and increasing it above 200
1817 tends to trade latency for slightly increased bandwidth.
1818
Willy Tarreau27a674e2009-08-17 07:23:33 +02001819tune.maxrewrite <number>
1820 Sets the reserved buffer space to this size in bytes. The reserved space is
1821 used for header rewriting or appending. The first reads on sockets will never
1822 fill more than bufsize-maxrewrite. Historically it has defaulted to half of
1823 bufsize, though that does not make much sense since there are rarely large
1824 numbers of headers to add. Setting it too high prevents processing of large
1825 requests or responses. Setting it too low prevents addition of new headers
1826 to already large requests or to POST requests. It is generally wise to set it
1827 to about 1024. It is automatically readjusted to half of bufsize if it is
1828 larger than that. This means you don't have to worry about it when changing
1829 bufsize.
1830
Willy Tarreauf3045d22015-04-29 16:24:50 +02001831tune.pattern.cache-size <number>
1832 Sets the size of the pattern lookup cache to <number> entries. This is an LRU
1833 cache which reminds previous lookups and their results. It is used by ACLs
1834 and maps on slow pattern lookups, namely the ones using the "sub", "reg",
1835 "dir", "dom", "end", "bin" match methods as well as the case-insensitive
1836 strings. It applies to pattern expressions which means that it will be able
1837 to memorize the result of a lookup among all the patterns specified on a
1838 configuration line (including all those loaded from files). It automatically
1839 invalidates entries which are updated using HTTP actions or on the CLI. The
1840 default cache size is set to 10000 entries, which limits its footprint to
Willy Tarreau7fdd81c2019-10-23 06:59:31 +02001841 about 5 MB per process/thread on 32-bit systems and 8 MB per process/thread
1842 on 64-bit systems, as caches are thread/process local. There is a very low
Willy Tarreauf3045d22015-04-29 16:24:50 +02001843 risk of collision in this cache, which is in the order of the size of the
1844 cache divided by 2^64. Typically, at 10000 requests per second with the
1845 default cache size of 10000 entries, there's 1% chance that a brute force
1846 attack could cause a single collision after 60 years, or 0.1% after 6 years.
1847 This is considered much lower than the risk of a memory corruption caused by
1848 aging components. If this is not acceptable, the cache can be disabled by
1849 setting this parameter to 0.
1850
Willy Tarreaubd9a0a72011-10-23 21:14:29 +02001851tune.pipesize <number>
1852 Sets the kernel pipe buffer size to this size (in bytes). By default, pipes
1853 are the default size for the system. But sometimes when using TCP splicing,
1854 it can improve performance to increase pipe sizes, especially if it is
1855 suspected that pipes are not filled and that many calls to splice() are
1856 performed. This has an impact on the kernel's memory footprint, so this must
1857 not be changed if impacts are not understood.
1858
Olivier Houchard88698d92019-04-16 19:07:22 +02001859tune.pool-low-fd-ratio <number>
1860 This setting sets the max number of file descriptors (in percentage) used by
1861 haproxy globally against the maximum number of file descriptors haproxy can
1862 use before we stop putting connection into the idle pool for reuse. The
1863 default is 20.
1864
1865tune.pool-high-fd-ratio <number>
1866 This setting sets the max number of file descriptors (in percentage) used by
1867 haproxy globally against the maximum number of file descriptors haproxy can
1868 use before we start killing idle connections when we can't reuse a connection
1869 and we have to create a new one. The default is 25 (one quarter of the file
1870 descriptor will mean that roughly half of the maximum front connections can
1871 keep an idle connection behind, anything beyond this probably doesn't make
John Roesler27c754c2019-07-10 15:45:51 -05001872 much sense in the general case when targeting connection reuse).
Olivier Houchard88698d92019-04-16 19:07:22 +02001873
Willy Tarreaue803de22010-01-21 17:43:04 +01001874tune.rcvbuf.client <number>
1875tune.rcvbuf.server <number>
1876 Forces the kernel socket receive buffer size on the client or the server side
1877 to the specified value in bytes. This value applies to all TCP/HTTP frontends
1878 and backends. It should normally never be set, and the default size (0) lets
John Roesler27c754c2019-07-10 15:45:51 -05001879 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001880 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01001881 order to save kernel memory by preventing it from buffering too large amounts
1882 of received data. Lower values will significantly increase CPU usage though.
1883
Willy Tarreaub22fc302015-12-14 12:04:35 +01001884tune.recv_enough <number>
Davor Ocelice9ed2812017-12-25 17:49:28 +01001885 HAProxy uses some hints to detect that a short read indicates the end of the
Willy Tarreaub22fc302015-12-14 12:04:35 +01001886 socket buffers. One of them is that a read returns more than <recv_enough>
1887 bytes, which defaults to 10136 (7 segments of 1448 each). This default value
1888 may be changed by this setting to better deal with workloads involving lots
1889 of short messages such as telnet or SSH sessions.
1890
Olivier Houchard1599b802018-05-24 18:59:04 +02001891tune.runqueue-depth <number>
John Roesler27c754c2019-07-10 15:45:51 -05001892 Sets the maximum amount of task that can be processed at once when running
Olivier Houchard1599b802018-05-24 18:59:04 +02001893 tasks. The default value is 200. Increasing it may incur latency when
1894 dealing with I/Os, making it too small can incur extra overhead.
1895
Willy Tarreaue803de22010-01-21 17:43:04 +01001896tune.sndbuf.client <number>
1897tune.sndbuf.server <number>
1898 Forces the kernel socket send buffer size on the client or the server side to
1899 the specified value in bytes. This value applies to all TCP/HTTP frontends
1900 and backends. It should normally never be set, and the default size (0) lets
John Roesler27c754c2019-07-10 15:45:51 -05001901 the kernel auto-tune this value depending on the amount of available memory.
Davor Ocelice9ed2812017-12-25 17:49:28 +01001902 However it can sometimes help to set it to very low values (e.g. 4096) in
Willy Tarreaue803de22010-01-21 17:43:04 +01001903 order to save kernel memory by preventing it from buffering too large amounts
1904 of received data. Lower values will significantly increase CPU usage though.
1905 Another use case is to prevent write timeouts with extremely slow clients due
1906 to the kernel waiting for a large part of the buffer to be read before
1907 notifying haproxy again.
1908
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001909tune.ssl.cachesize <number>
Emeric Brunaf9619d2012-11-28 18:47:52 +01001910 Sets the size of the global SSL session cache, in a number of blocks. A block
1911 is large enough to contain an encoded session without peer certificate.
1912 An encoded session with peer certificate is stored in multiple blocks
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001913 depending on the size of the peer certificate. A block uses approximately
Emeric Brunaf9619d2012-11-28 18:47:52 +01001914 200 bytes of memory. The default value may be forced at build time, otherwise
Davor Ocelice9ed2812017-12-25 17:49:28 +01001915 defaults to 20000. When the cache is full, the most idle entries are purged
Emeric Brunaf9619d2012-11-28 18:47:52 +01001916 and reassigned. Higher values reduce the occurrence of such a purge, hence
1917 the number of CPU-intensive SSL handshakes by ensuring that all users keep
1918 their session as long as possible. All entries are pre-allocated upon startup
Emeric Brun22890a12012-12-28 14:41:32 +01001919 and are shared between all processes if "nbproc" is greater than 1. Setting
1920 this value to 0 disables the SSL session cache.
Willy Tarreau6ec58db2012-11-16 16:32:15 +01001921
Emeric Brun8dc60392014-05-09 13:52:00 +02001922tune.ssl.force-private-cache
Lukas Tribus27935782018-10-01 02:00:16 +02001923 This option disables SSL session cache sharing between all processes. It
Emeric Brun8dc60392014-05-09 13:52:00 +02001924 should normally not be used since it will force many renegotiations due to
1925 clients hitting a random process. But it may be required on some operating
1926 systems where none of the SSL cache synchronization method may be used. In
1927 this case, adding a first layer of hash-based load balancing before the SSL
1928 layer might limit the impact of the lack of session sharing.
1929
Emeric Brun4f65bff2012-11-16 15:11:00 +01001930tune.ssl.lifetime <timeout>
1931 Sets how long a cached SSL session may remain valid. This time is expressed
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001932 in seconds and defaults to 300 (5 min). It is important to understand that it
Emeric Brun4f65bff2012-11-16 15:11:00 +01001933 does not guarantee that sessions will last that long, because if the cache is
1934 full, the longest idle sessions will be purged despite their configured
1935 lifetime. The real usefulness of this setting is to prevent sessions from
1936 being used for too long.
1937
Willy Tarreaubfd59462013-02-21 07:46:09 +01001938tune.ssl.maxrecord <number>
1939 Sets the maximum amount of bytes passed to SSL_write() at a time. Default
1940 value 0 means there is no limit. Over SSL/TLS, the client can decipher the
1941 data only once it has received a full record. With large records, it means
1942 that clients might have to download up to 16kB of data before starting to
1943 process them. Limiting the value can improve page load times on browsers
1944 located over high latency or low bandwidth networks. It is suggested to find
1945 optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
1946 Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
1947 keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
1948 2859 gave good results during tests. Use "strace -e trace=write" to find the
Davor Ocelice9ed2812017-12-25 17:49:28 +01001949 best value. HAProxy will automatically switch to this setting after an idle
Willy Tarreau7e312732014-02-12 16:35:14 +01001950 stream has been detected (see tune.idletimer above).
Willy Tarreaubfd59462013-02-21 07:46:09 +01001951
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001952tune.ssl.default-dh-param <number>
1953 Sets the maximum size of the Diffie-Hellman parameters used for generating
1954 the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
1955 final size will try to match the size of the server's RSA (or DSA) key (e.g,
1956 a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
1957 this maximum value. Default value if 1024. Only 1024 or higher values are
1958 allowed. Higher values will increase the CPU load, and values greater than
1959 1024 bits are not supported by Java 7 and earlier clients. This value is not
Remi Gacogne47783ef2015-05-29 15:53:22 +02001960 used if static Diffie-Hellman parameters are supplied either directly
1961 in the certificate file or by using the ssl-dh-param-file parameter.
Remi Gacognef46cd6e2014-06-12 14:58:40 +02001962
Christopher Faulet31af49d2015-06-09 17:29:50 +02001963tune.ssl.ssl-ctx-cache-size <number>
1964 Sets the size of the cache used to store generated certificates to <number>
1965 entries. This is a LRU cache. Because generating a SSL certificate
1966 dynamically is expensive, they are cached. The default cache size is set to
1967 1000 entries.
1968
Thierry FOURNIER5bf77322017-02-25 12:45:22 +01001969tune.ssl.capture-cipherlist-size <number>
1970 Sets the maximum size of the buffer used for capturing client-hello cipher
1971 list. If the value is 0 (default value) the capture is disabled, otherwise
1972 a buffer is allocated for each SSL/TLS connection.
1973
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001974tune.vars.global-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01001975tune.vars.proc-max-size <size>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001976tune.vars.reqres-max-size <size>
1977tune.vars.sess-max-size <size>
1978tune.vars.txn-max-size <size>
Christopher Fauletff2613e2016-11-09 11:36:17 +01001979 These five tunes help to manage the maximum amount of memory used by the
1980 variables system. "global" limits the overall amount of memory available for
1981 all scopes. "proc" limits the memory for the process scope, "sess" limits the
1982 memory for the session scope, "txn" for the transaction scope, and "reqres"
1983 limits the memory for each request or response processing.
1984 Memory accounting is hierarchical, meaning more coarse grained limits include
1985 the finer grained ones: "proc" includes "sess", "sess" includes "txn", and
1986 "txn" includes "reqres".
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001987
Daniel Schneller0b547052016-03-21 20:46:57 +01001988 For example, when "tune.vars.sess-max-size" is limited to 100,
1989 "tune.vars.txn-max-size" and "tune.vars.reqres-max-size" cannot exceed
1990 100 either. If we create a variable "txn.var" that contains 100 bytes,
1991 all available space is consumed.
1992 Notice that exceeding the limits at runtime will not result in an error
1993 message, but values might be cut off or corrupted. So make sure to accurately
1994 plan for the amount of space needed to store all your variables.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02001995
William Lallemanda509e4c2012-11-07 16:54:34 +01001996tune.zlib.memlevel <number>
1997 Sets the memLevel parameter in zlib initialization for each session. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03001998 defines how much memory should be allocated for the internal compression
William Lallemanda509e4c2012-11-07 16:54:34 +01001999 state. A value of 1 uses minimum memory but is slow and reduces compression
Davor Ocelice9ed2812017-12-25 17:49:28 +01002000 ratio, a value of 9 uses maximum memory for optimal speed. Can be a value
William Lallemanda509e4c2012-11-07 16:54:34 +01002001 between 1 and 9. The default value is 8.
2002
2003tune.zlib.windowsize <number>
2004 Sets the window size (the size of the history buffer) as a parameter of the
2005 zlib initialization for each session. Larger values of this parameter result
Davor Ocelice9ed2812017-12-25 17:49:28 +01002006 in better compression at the expense of memory usage. Can be a value between
2007 8 and 15. The default value is 15.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002008
Willy Tarreauc57f0e22009-05-10 13:12:33 +020020093.3. Debugging
2010--------------
Willy Tarreau6a06a402007-07-15 20:15:28 +02002011
2012debug
2013 Enables debug mode which dumps to stdout all exchanges, and disables forking
2014 into background. It is the equivalent of the command-line argument "-d". It
2015 should never be used in a production configuration since it may prevent full
2016 system startup.
2017
2018quiet
2019 Do not display any message during startup. It is equivalent to the command-
2020 line argument "-q".
2021
Emeric Brunf099e792010-09-27 12:05:28 +02002022
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010020233.4. Userlists
2024--------------
2025It is possible to control access to frontend/backend/listen sections or to
2026http stats by allowing only authenticated and authorized users. To do this,
2027it is required to create at least one userlist and to define users.
2028
2029userlist <listname>
Cyril Bonté78caf842010-03-10 22:41:43 +01002030 Creates new userlist with name <listname>. Many independent userlists can be
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002031 used to store authentication & authorization data for independent customers.
2032
2033group <groupname> [users <user>,<user>,(...)]
Cyril Bonté78caf842010-03-10 22:41:43 +01002034 Adds group <groupname> to the current userlist. It is also possible to
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002035 attach users to this group by using a comma separated list of names
2036 proceeded by "users" keyword.
2037
Cyril Bontéf0c60612010-02-06 14:44:47 +01002038user <username> [password|insecure-password <password>]
2039 [groups <group>,<group>,(...)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002040 Adds user <username> to the current userlist. Both secure (encrypted) and
2041 insecure (unencrypted) passwords can be used. Encrypted passwords are
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002042 evaluated using the crypt(3) function, so depending on the system's
2043 capabilities, different algorithms are supported. For example, modern Glibc
2044 based Linux systems support MD5, SHA-256, SHA-512, and, of course, the
2045 classic DES-based method of encrypting passwords.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002046
Daniel Schnellerd06f31c2017-11-06 16:51:04 +01002047 Attention: Be aware that using encrypted passwords might cause significantly
2048 increased CPU usage, depending on the number of requests, and the algorithm
2049 used. For any of the hashed variants, the password for each request must
2050 be processed through the chosen algorithm, before it can be compared to the
2051 value specified in the config file. Most current algorithms are deliberately
2052 designed to be expensive to compute to achieve resistance against brute
2053 force attacks. They do not simply salt/hash the clear text password once,
2054 but thousands of times. This can quickly become a major factor in haproxy's
2055 overall CPU consumption!
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002056
2057 Example:
Cyril Bontéf0c60612010-02-06 14:44:47 +01002058 userlist L1
2059 group G1 users tiger,scott
2060 group G2 users xdb,scott
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002061
Cyril Bontéf0c60612010-02-06 14:44:47 +01002062 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
2063 user scott insecure-password elgato
2064 user xdb insecure-password hello
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002065
Cyril Bontéf0c60612010-02-06 14:44:47 +01002066 userlist L2
2067 group G1
2068 group G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002069
Cyril Bontéf0c60612010-02-06 14:44:47 +01002070 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
2071 user scott insecure-password elgato groups G1,G2
2072 user xdb insecure-password hello groups G2
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01002073
2074 Please note that both lists are functionally identical.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002075
Emeric Brunf099e792010-09-27 12:05:28 +02002076
20773.5. Peers
Cyril Bontédc4d9032012-04-08 21:57:39 +02002078----------
Emeric Brun94900952015-06-11 18:25:54 +02002079It is possible to propagate entries of any data-types in stick-tables between
2080several haproxy instances over TCP connections in a multi-master fashion. Each
2081instance pushes its local updates and insertions to remote peers. The pushed
2082values overwrite remote ones without aggregation. Interrupted exchanges are
2083automatically detected and recovered from the last known point.
2084In addition, during a soft restart, the old process connects to the new one
2085using such a TCP connection to push all its entries before the new process
2086tries to connect to other peers. That ensures very fast replication during a
2087reload, it typically takes a fraction of a second even for large tables.
2088Note that Server IDs are used to identify servers remotely, so it is important
2089that configurations look similar or at least that the same IDs are forced on
2090each server on all participants.
Emeric Brunf099e792010-09-27 12:05:28 +02002091
2092peers <peersect>
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002093 Creates a new peer list with name <peersect>. It is an independent section,
Emeric Brunf099e792010-09-27 12:05:28 +02002094 which is referenced by one or more stick-tables.
2095
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002096bind [<address>]:<port_range> [, ...] [param*]
2097 Defines the binding parameters of the local peer of this "peers" section.
2098 Such lines are not supported with "peer" line in the same "peers" section.
2099
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002100disabled
2101 Disables a peers section. It disables both listening and any synchronization
2102 related to this section. This is provided to disable synchronization of stick
2103 tables without having to comment out all "peers" references.
2104
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002105default-bind [param*]
2106 Defines the binding parameters for the local peer, excepted its address.
2107
2108default-server [param*]
2109 Change default options for a server in a "peers" section.
2110
2111 Arguments:
2112 <param*> is a list of parameters for this server. The "default-server"
2113 keyword accepts an important number of options and has a complete
2114 section dedicated to it. Please refer to section 5 for more
2115 details.
2116
2117
2118 See also: "server" and section 5 about server options
2119
Willy Tarreau77e4bd12015-05-01 20:02:17 +02002120enable
2121 This re-enables a disabled peers section which was previously disabled.
2122
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002123peer <peername> <ip>:<port> [param*]
Emeric Brunf099e792010-09-27 12:05:28 +02002124 Defines a peer inside a peers section.
2125 If <peername> is set to the local peer name (by default hostname, or forced
2126 using "-L" command line option), haproxy will listen for incoming remote peer
2127 connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to
2128 to join the remote peer, and <peername> is used at the protocol level to
2129 identify and validate the remote peer on the server side.
2130
2131 During a soft restart, local peer <ip>:<port> is used by the old instance to
2132 connect the new one and initiate a complete replication (teaching process).
2133
2134 It is strongly recommended to have the exact same peers declaration on all
2135 peers and to only rely on the "-L" command line argument to change the local
2136 peer name. This makes it easier to maintain coherent configuration files
2137 across all peers.
2138
William Lallemandb2f07452015-05-12 14:27:13 +02002139 You may want to reference some environment variables in the address
2140 parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01002141
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002142 Note: "peer" keyword may transparently be replaced by "server" keyword (see
2143 "server" keyword explanation below).
2144
2145server <peername> [<ip>:<port>] [param*]
Michael Prokop4438c602019-05-24 10:25:45 +02002146 As previously mentioned, "peer" keyword may be replaced by "server" keyword
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002147 with a support for all "server" parameters found in 5.2 paragraph.
2148 If the underlying peer is local, <ip>:<port> parameters must not be present.
2149 These parameters must be provided on a "bind" line (see "bind" keyword
2150 of this "peers" section).
2151 Some of these parameters are irrelevant for "peers" sections.
2152
2153
Cyril Bontédc4d9032012-04-08 21:57:39 +02002154 Example:
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002155 # The old way.
Emeric Brunf099e792010-09-27 12:05:28 +02002156 peers mypeers
Willy Tarreauf7b30a92010-12-06 22:59:17 +01002157 peer haproxy1 192.168.0.1:1024
2158 peer haproxy2 192.168.0.2:1024
2159 peer haproxy3 10.2.0.1:1024
Emeric Brunf099e792010-09-27 12:05:28 +02002160
2161 backend mybackend
2162 mode tcp
2163 balance roundrobin
2164 stick-table type ip size 20k peers mypeers
2165 stick on src
2166
Willy Tarreauf7b30a92010-12-06 22:59:17 +01002167 server srv1 192.168.0.30:80
2168 server srv2 192.168.0.31:80
Emeric Brunf099e792010-09-27 12:05:28 +02002169
Frédéric Lécaille2f167b32019-01-11 14:13:54 +01002170 Example:
2171 peers mypeers
2172 bind 127.0.0.11:10001 ssl crt mycerts/pem
2173 default-server ssl verify none
2174 server hostA 127.0.0.10:10000
2175 server hostB #local peer
Emeric Brunf099e792010-09-27 12:05:28 +02002176
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002177
2178table <tablename> type {ip | integer | string [len <length>] | binary [len <length>]}
2179 size <size> [expire <expire>] [nopurge] [store <data_type>]*
2180
2181 Configure a stickiness table for the current section. This line is parsed
2182 exactly the same way as the "stick-table" keyword in others section, except
John Roesler27c754c2019-07-10 15:45:51 -05002183 for the "peers" argument which is not required here and with an additional
Frédéric Lécaille4f5b77c2019-03-18 14:05:58 +01002184 mandatory first parameter to designate the stick-table. Contrary to others
2185 sections, there may be several "table" lines in "peers" sections (see also
2186 "stick-table" keyword).
2187
2188 Also be aware of the fact that "peers" sections have their own stick-table
2189 namespaces to avoid collisions between stick-table names identical in
2190 different "peers" section. This is internally handled prepending the "peers"
2191 sections names to the name of the stick-tables followed by a '/' character.
2192 If somewhere else in the configuration file you have to refer to such
2193 stick-tables declared in "peers" sections you must use the prefixed version
2194 of the stick-table name as follows:
2195
2196 peers mypeers
2197 peer A ...
2198 peer B ...
2199 table t1 ...
2200
2201 frontend fe1
2202 tcp-request content track-sc0 src table mypeers/t1
2203
2204 This is also this prefixed version of the stick-table names which must be
2205 used to refer to stick-tables through the CLI.
2206
2207 About "peers" protocol, as only "peers" belonging to the same section may
2208 communicate with each others, there is no need to do such a distinction.
2209 Several "peers" sections may declare stick-tables with the same name.
2210 This is shorter version of the stick-table name which is sent over the network.
2211 There is only a '/' character as prefix to avoid stick-table name collisions between
2212 stick-tables declared as backends and stick-table declared in "peers" sections
2213 as follows in this weird but supported configuration:
2214
2215 peers mypeers
2216 peer A ...
2217 peer B ...
2218 table t1 type string size 10m store gpc0
2219
2220 backend t1
2221 stick-table type string size 10m store gpc0 peers mypeers
2222
2223 Here "t1" table declared in "mypeeers" section has "mypeers/t1" as global name.
2224 "t1" table declared as a backend as "t1" as global name. But at peer protocol
2225 level the former table is named "/t1", the latter is again named "t1".
2226
Simon Horman51a1cf62015-02-03 13:00:44 +090022273.6. Mailers
2228------------
2229It is possible to send email alerts when the state of servers changes.
2230If configured email alerts are sent to each mailer that is configured
2231in a mailers section. Email is sent to mailers using SMTP.
2232
Pieter Baauw386a1272015-08-16 15:26:24 +02002233mailers <mailersect>
Simon Horman51a1cf62015-02-03 13:00:44 +09002234 Creates a new mailer list with the name <mailersect>. It is an
2235 independent section which is referenced by one or more proxies.
2236
2237mailer <mailername> <ip>:<port>
2238 Defines a mailer inside a mailers section.
2239
2240 Example:
2241 mailers mymailers
2242 mailer smtp1 192.168.0.1:587
2243 mailer smtp2 192.168.0.2:587
2244
2245 backend mybackend
2246 mode tcp
2247 balance roundrobin
2248
2249 email-alert mailers mymailers
2250 email-alert from test1@horms.org
2251 email-alert to test2@horms.org
2252
2253 server srv1 192.168.0.30:80
2254 server srv2 192.168.0.31:80
2255
Pieter Baauw235fcfc2016-02-13 15:33:40 +01002256timeout mail <time>
2257 Defines the time available for a mail/connection to be made and send to
2258 the mail-server. If not defined the default value is 10 seconds. To allow
2259 for at least two SYN-ACK packets to be send during initial TCP handshake it
2260 is advised to keep this value above 4 seconds.
2261
2262 Example:
2263 mailers mymailers
2264 timeout mail 20s
2265 mailer smtp1 192.168.0.1:587
Simon Horman51a1cf62015-02-03 13:00:44 +09002266
William Lallemandc9515522019-06-12 16:32:11 +020022673.7. Programs
2268-------------
2269In master-worker mode, it is possible to launch external binaries with the
2270master, these processes are called programs. These programs are launched and
2271managed the same way as the workers.
2272
2273During a reload of HAProxy, those processes are dealing with the same
2274sequence as a worker:
2275
2276 - the master is re-executed
2277 - the master sends a SIGUSR1 signal to the program
2278 - if "option start-on-reload" is not disabled, the master launches a new
2279 instance of the program
2280
2281During a stop, or restart, a SIGTERM is sent to the programs.
2282
2283program <name>
2284 This is a new program section, this section will create an instance <name>
2285 which is visible in "show proc" on the master CLI. (See "9.4. Master CLI" in
2286 the management guide).
2287
2288command <command> [arguments*]
2289 Define the command to start with optional arguments. The command is looked
2290 up in the current PATH if it does not include an absolute path. This is a
2291 mandatory option of the program section. Arguments containing spaces must
2292 be enclosed in quotes or double quotes or be prefixed by a backslash.
2293
2294option start-on-reload
2295no option start-on-reload
2296 Start (or not) a new instance of the program upon a reload of the master.
2297 The default is to start a new instance. This option may only be used in a
2298 program section.
2299
2300
Willy Tarreauc57f0e22009-05-10 13:12:33 +020023014. Proxies
Willy Tarreau6a06a402007-07-15 20:15:28 +02002302----------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002303
Willy Tarreau6a06a402007-07-15 20:15:28 +02002304Proxy configuration can be located in a set of sections :
William Lallemand6e62fb62015-04-28 16:55:23 +02002305 - defaults [<name>]
Willy Tarreau6a06a402007-07-15 20:15:28 +02002306 - frontend <name>
2307 - backend <name>
2308 - listen <name>
2309
2310A "defaults" section sets default parameters for all other sections following
2311its declaration. Those default parameters are reset by the next "defaults"
2312section. See below for the list of parameters which can be set in a "defaults"
Willy Tarreau0ba27502007-12-24 16:55:16 +01002313section. The name is optional but its use is encouraged for better readability.
Willy Tarreau6a06a402007-07-15 20:15:28 +02002314
2315A "frontend" section describes a set of listening sockets accepting client
2316connections.
2317
2318A "backend" section describes a set of servers to which the proxy will connect
2319to forward incoming connections.
2320
2321A "listen" section defines a complete proxy with its frontend and backend
2322parts combined in one section. It is generally useful for TCP-only traffic.
2323
Willy Tarreau0ba27502007-12-24 16:55:16 +01002324All proxy names must be formed from upper and lower case letters, digits,
2325'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
2326case-sensitive, which means that "www" and "WWW" are two different proxies.
2327
2328Historically, all proxy names could overlap, it just caused troubles in the
2329logs. Since the introduction of content switching, it is mandatory that two
2330proxies with overlapping capabilities (frontend/backend) have different names.
2331However, it is still permitted that a frontend and a backend share the same
2332name, as this configuration seems to be commonly encountered.
2333
2334Right now, two major proxy modes are supported : "tcp", also known as layer 4,
2335and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002336bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
Willy Tarreau0ba27502007-12-24 16:55:16 +01002337protocol, and can interact with it by allowing, blocking, switching, adding,
2338modifying, or removing arbitrary contents in requests or responses, based on
2339arbitrary criteria.
2340
Willy Tarreau70dffda2014-01-30 03:07:23 +01002341In HTTP mode, the processing applied to requests and responses flowing over
2342a connection depends in the combination of the frontend's HTTP options and
Julien Pivotto599788e2019-12-10 13:11:17 +01002343the backend's. HAProxy supports 3 connection modes :
Willy Tarreau70dffda2014-01-30 03:07:23 +01002344
2345 - KAL : keep alive ("option http-keep-alive") which is the default mode : all
2346 requests and responses are processed, and connections remain open but idle
2347 between responses and new requests.
2348
2349 - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
2350 1.0 to 1.5-dev21 : only the first request and response are processed, and
2351 everything else is forwarded with no analysis at all. This mode should not
Christopher Faulet6c9bbb22019-03-26 21:37:23 +01002352 be used as it creates lots of trouble with logging and HTTP processing.
2353 And because it cannot work in HTTP/2, this option is deprecated and it is
2354 only supported on legacy HTTP frontends. In HTX, it is ignored and a
2355 warning is emitted during HAProxy startup.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002356
Willy Tarreau70dffda2014-01-30 03:07:23 +01002357 - SCL: server close ("option http-server-close") : the server-facing
2358 connection is closed after the end of the response is received, but the
2359 client-facing connection remains open.
2360
Christopher Faulet315b39c2018-09-21 16:26:19 +02002361 - CLO: close ("option httpclose"): the connection is closed after the end of
2362 the response and "Connection: close" appended in both directions.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002363
2364The effective mode that will be applied to a connection passing through a
2365frontend and a backend can be determined by both proxy modes according to the
2366following matrix, but in short, the modes are symmetric, keep-alive is the
Christopher Faulet315b39c2018-09-21 16:26:19 +02002367weakest option and close is the strongest.
Willy Tarreau70dffda2014-01-30 03:07:23 +01002368
Christopher Faulet315b39c2018-09-21 16:26:19 +02002369 Backend mode
Willy Tarreau70dffda2014-01-30 03:07:23 +01002370
Christopher Faulet315b39c2018-09-21 16:26:19 +02002371 | KAL | SCL | CLO
2372 ----+-----+-----+----
2373 KAL | KAL | SCL | CLO
2374 ----+-----+-----+----
2375 TUN | TUN | SCL | CLO
2376 Frontend ----+-----+-----+----
2377 mode SCL | SCL | SCL | CLO
2378 ----+-----+-----+----
2379 CLO | CLO | CLO | CLO
Willy Tarreau70dffda2014-01-30 03:07:23 +01002380
Willy Tarreau0ba27502007-12-24 16:55:16 +01002381
Willy Tarreau70dffda2014-01-30 03:07:23 +01002382
Willy Tarreauc57f0e22009-05-10 13:12:33 +020023834.1. Proxy keywords matrix
2384--------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002385
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002386The following list of keywords is supported. Most of them may only be used in a
2387limited set of section types. Some of them are marked as "deprecated" because
2388they are inherited from an old syntax which may be confusing or functionally
2389limited, and there are new recommended keywords to replace them. Keywords
Davor Ocelice9ed2812017-12-25 17:49:28 +01002390marked with "(*)" can be optionally inverted using the "no" prefix, e.g. "no
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002391option contstats". This makes sense when the option has been enabled by default
Willy Tarreau3842f002009-06-14 11:39:52 +02002392and must be disabled for a specific instance. Such options may also be prefixed
2393with "default" in order to restore default settings regardless of what has been
2394specified in a previous "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002395
Willy Tarreau6a06a402007-07-15 20:15:28 +02002396
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002397 keyword defaults frontend listen backend
2398------------------------------------+----------+----------+---------+---------
2399acl - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002400backlog X X X -
2401balance X - X X
2402bind - X X -
2403bind-process X X X X
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02002404block (deprecated) - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002405capture cookie - X X -
2406capture request header - X X -
2407capture response header - X X -
2408clitimeout (deprecated) X X X -
William Lallemand82fe75c2012-10-23 10:25:10 +02002409compression X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002410contimeout (deprecated) X - X X
2411cookie X - X X
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02002412declare capture - X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002413default-server X - X X
2414default_backend X X X -
2415description - X X X
2416disabled X X X X
2417dispatch - - X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002418email-alert from X X X X
Simon Horman64e34162015-02-06 11:11:57 +09002419email-alert level X X X X
Simon Horman51a1cf62015-02-03 13:00:44 +09002420email-alert mailers X X X X
2421email-alert myhostname X X X X
2422email-alert to X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002423enabled X X X X
2424errorfile X X X X
2425errorloc X X X X
2426errorloc302 X X X X
2427-- keyword -------------------------- defaults - frontend - listen -- backend -
2428errorloc303 X X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002429force-persist - - X X
Christopher Fauletc3fe5332016-04-07 15:30:10 +02002430filter - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002431fullconn X - X X
2432grace X X X X
2433hash-type X - X X
2434http-check disable-on-404 X - X X
Willy Tarreaubd741542010-03-16 18:46:54 +01002435http-check expect - - X X
Willy Tarreau7ab6aff2010-10-12 06:30:16 +02002436http-check send-state X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002437http-request - X X X
Willy Tarreaue365c0b2013-06-11 16:06:12 +02002438http-response - X X X
Willy Tarreau30631952015-08-06 15:05:24 +02002439http-reuse X - X X
Baptiste Assmann2c42ef52013-10-09 21:57:02 +02002440http-send-name-header - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002441id - X X X
Cyril Bonté4288c5a2018-03-12 22:02:59 +01002442ignore-persist - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002443load-server-state-from-file X - X X
William Lallemand0f99e342011-10-12 17:50:54 +02002444log (*) X X X X
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01002445log-format X X X -
Dragan Dosen7ad31542015-09-28 17:16:47 +02002446log-format-sd X X X -
Willy Tarreau094af4e2015-01-07 15:03:42 +01002447log-tag X X X X
Willy Tarreauc35362a2014-04-25 13:58:37 +02002448max-keep-alive-queue X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002449maxconn X X X -
2450mode X X X X
2451monitor fail - X X -
2452monitor-net X X X -
2453monitor-uri X X X -
2454option abortonclose (*) X - X X
2455option accept-invalid-http-request (*) X X X -
2456option accept-invalid-http-response (*) X - X X
2457option allbackups (*) X - X X
2458option checkcache (*) X - X X
2459option clitcpka (*) X X X -
2460option contstats (*) X X X -
2461option dontlog-normal (*) X X X -
2462option dontlognull (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002463-- keyword -------------------------- defaults - frontend - listen -- backend -
2464option forwardfor X X X X
Christopher Fauleta99ff4d2019-07-22 16:18:24 +02002465option h1-case-adjust-bogus-client (*) X X X -
2466option h1-case-adjust-bogus-server (*) X - X X
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02002467option http-buffer-request (*) X X X X
Willy Tarreau82649f92015-05-01 22:40:51 +02002468option http-ignore-probes (*) X X X -
Willy Tarreau16bfb022010-01-16 19:48:41 +01002469option http-keep-alive (*) X X X X
Willy Tarreau96e31212011-05-30 18:10:30 +02002470option http-no-delay (*) X X X X
Christopher Faulet98db9762018-09-21 10:25:19 +02002471option http-pretend-keepalive (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002472option http-server-close (*) X X X X
Christopher Faulet6c9bbb22019-03-26 21:37:23 +01002473option http-tunnel (deprecated) (*) X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002474option http-use-proxy-header (*) X X X -
Willy Tarreau68ad3a42018-10-22 11:49:15 +02002475option http-use-htx (*) X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002476option httpchk X - X X
2477option httpclose (*) X X X X
Freddy Spierenburge88b7732019-03-25 14:35:17 +01002478option httplog X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002479option http_proxy (*) X X X X
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002480option independent-streams (*) X X X X
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02002481option ldap-check X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002482option external-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002483option log-health-checks (*) X - X X
2484option log-separate-errors (*) X X X -
2485option logasap (*) X X X -
2486option mysql-check X - X X
2487option nolinger (*) X X X X
2488option originalto X X X X
2489option persist (*) X - X X
Baptiste Assmann809e22a2015-10-12 20:22:55 +02002490option pgsql-check X - X X
2491option prefer-last-server (*) X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002492option redispatch (*) X - X X
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02002493option redis-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002494option smtpchk X - X X
2495option socket-stats (*) X X X -
2496option splice-auto (*) X X X X
2497option splice-request (*) X X X X
2498option splice-response (*) X X X X
Christopher Fauletba7bc162016-11-07 21:07:38 +01002499option spop-check - - - X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002500option srvtcpka (*) X - X X
2501option ssl-hello-chk X - X X
2502-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreaued179852013-12-16 01:07:00 +01002503option tcp-check X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002504option tcp-smart-accept (*) X X X -
2505option tcp-smart-connect (*) X - X X
2506option tcpka X X X X
2507option tcplog X X X X
2508option transparent (*) X - X X
Simon Horman98637e52014-06-20 12:30:16 +09002509external-check command X - X X
2510external-check path X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002511persist rdp-cookie X - X X
2512rate-limit sessions X X X -
2513redirect - X X X
2514redisp (deprecated) X - X X
2515redispatch (deprecated) X - X X
Willy Tarreau96d51952019-05-22 20:34:35 +02002516reqadd (deprecated) - X X X
2517reqallow (deprecated) - X X X
2518reqdel (deprecated) - X X X
2519reqdeny (deprecated) - X X X
2520reqiallow (deprecated) - X X X
2521reqidel (deprecated) - X X X
2522reqideny (deprecated) - X X X
2523reqipass (deprecated) - X X X
2524reqirep (deprecated) - X X X
2525reqitarpit (deprecated) - X X X
2526reqpass (deprecated) - X X X
2527reqrep (deprecated) - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002528-- keyword -------------------------- defaults - frontend - listen -- backend -
Willy Tarreau96d51952019-05-22 20:34:35 +02002529reqtarpit (deprecated) - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002530retries X - X X
Olivier Houcharda254a372019-04-05 15:30:12 +02002531retry-on X - X X
Willy Tarreau96d51952019-05-22 20:34:35 +02002532rspadd (deprecated) - X X X
2533rspdel (deprecated) - X X X
2534rspdeny (deprecated) - X X X
2535rspidel (deprecated) - X X X
2536rspideny (deprecated) - X X X
2537rspirep (deprecated) - X X X
2538rsprep (deprecated) - X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002539server - - X X
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02002540server-state-file-name X - X X
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02002541server-template - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002542source X - X X
2543srvtimeout (deprecated) X - X X
Baptiste Assmann5a549212015-10-12 20:30:24 +02002544stats admin - X X X
2545stats auth X X X X
2546stats enable X X X X
2547stats hide-version X X X X
2548stats http-request - X X X
2549stats realm X X X X
2550stats refresh X X X X
2551stats scope X X X X
2552stats show-desc X X X X
2553stats show-legends X X X X
2554stats show-node X X X X
2555stats uri X X X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002556-- keyword -------------------------- defaults - frontend - listen -- backend -
2557stick match - - X X
2558stick on - - X X
2559stick store-request - - X X
Willy Tarreaud8dc99f2011-07-01 11:33:25 +02002560stick store-response - - X X
Adam Spiers68af3c12017-04-06 16:31:39 +01002561stick-table - X X X
Willy Tarreau938c7fe2014-04-25 14:21:39 +02002562tcp-check connect - - X X
2563tcp-check expect - - X X
2564tcp-check send - - X X
2565tcp-check send-binary - - X X
Willy Tarreaue9656522010-08-17 15:40:09 +02002566tcp-request connection - X X -
2567tcp-request content - X X X
Willy Tarreaua56235c2010-09-14 11:31:36 +02002568tcp-request inspect-delay - X X X
Willy Tarreau4f614292016-10-21 17:49:36 +02002569tcp-request session - X X -
Emeric Brun0a3b67f2010-09-24 15:34:53 +02002570tcp-response content - - X X
2571tcp-response inspect-delay - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002572timeout check X - X X
2573timeout client X X X -
Willy Tarreau05cdd962014-05-10 14:30:07 +02002574timeout client-fin X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002575timeout clitimeout (deprecated) X X X -
2576timeout connect X - X X
2577timeout contimeout (deprecated) X - X X
2578timeout http-keep-alive X X X X
2579timeout http-request X X X X
2580timeout queue X - X X
2581timeout server X - X X
Willy Tarreau05cdd962014-05-10 14:30:07 +02002582timeout server-fin X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002583timeout srvtimeout (deprecated) X - X X
2584timeout tarpit X X X X
Willy Tarreauce887fd2012-05-12 12:50:00 +02002585timeout tunnel X - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002586transparent (deprecated) X - X X
William Lallemanda73203e2012-03-12 12:48:57 +01002587unique-id-format X X X -
2588unique-id-header X X X -
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002589use_backend - X X -
Willy Tarreau4a5cade2012-04-05 21:09:48 +02002590use-server - - X X
Willy Tarreau5c6f7b32010-02-26 13:34:29 +01002591------------------------------------+----------+----------+---------+---------
2592 keyword defaults frontend listen backend
Willy Tarreau6a06a402007-07-15 20:15:28 +02002593
Willy Tarreau0ba27502007-12-24 16:55:16 +01002594
Willy Tarreauc57f0e22009-05-10 13:12:33 +020025954.2. Alphabetically sorted keywords reference
2596---------------------------------------------
Willy Tarreau0ba27502007-12-24 16:55:16 +01002597
2598This section provides a description of each keyword and its usage.
2599
2600
2601acl <aclname> <criterion> [flags] [operator] <value> ...
2602 Declare or complete an access list.
2603 May be used in sections : defaults | frontend | listen | backend
2604 no | yes | yes | yes
2605 Example:
2606 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
2607 acl invalid_src src_port 0:1023
2608 acl local_dst hdr(host) -i localhost
2609
Willy Tarreauc57f0e22009-05-10 13:12:33 +02002610 See section 7 about ACL usage.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002611
2612
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002613backlog <conns>
2614 Give hints to the system about the approximate listen backlog desired size
2615 May be used in sections : defaults | frontend | listen | backend
2616 yes | yes | yes | no
2617 Arguments :
2618 <conns> is the number of pending connections. Depending on the operating
2619 system, it may represent the number of already acknowledged
Cyril Bontédc4d9032012-04-08 21:57:39 +02002620 connections, of non-acknowledged ones, or both.
Willy Tarreauc73ce2b2008-01-06 10:55:10 +01002621
2622 In order to protect against SYN flood attacks, one solution is to increase
2623 the system's SYN backlog size. Depending on the system, sometimes it is just
2624 tunable via a system parameter, sometimes it is not adjustable at all, and
2625 sometimes the system relies on hints given by the application at the time of
2626 the listen() syscall. By default, HAProxy passes the frontend's maxconn value
2627 to the listen() syscall. On systems which can make use of this value, it can
2628 sometimes be useful to be able to specify a different value, hence this
2629 backlog parameter.
2630
2631 On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is
2632 used as a hint and the system accepts up to the smallest greater power of
2633 two, and never more than some limits (usually 32768).
2634
2635 See also : "maxconn" and the target operating system's tuning guide.
2636
2637
Willy Tarreau0ba27502007-12-24 16:55:16 +01002638balance <algorithm> [ <arguments> ]
Willy Tarreau226071e2014-04-10 11:55:45 +02002639balance url_param <param> [check_post]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002640 Define the load balancing algorithm to be used in a backend.
2641 May be used in sections : defaults | frontend | listen | backend
2642 yes | no | yes | yes
2643 Arguments :
2644 <algorithm> is the algorithm used to select a server when doing load
2645 balancing. This only applies when no persistence information
2646 is available, or when a connection is redispatched to another
2647 server. <algorithm> may be one of the following :
2648
2649 roundrobin Each server is used in turns, according to their weights.
2650 This is the smoothest and fairest algorithm when the server's
2651 processing time remains equally distributed. This algorithm
2652 is dynamic, which means that server weights may be adjusted
Willy Tarreau9757a382009-10-03 12:56:50 +02002653 on the fly for slow starts for instance. It is limited by
Godbacha34bdc02013-07-22 07:44:53 +08002654 design to 4095 active servers per backend. Note that in some
Willy Tarreau9757a382009-10-03 12:56:50 +02002655 large farms, when a server becomes up after having been down
2656 for a very short time, it may sometimes take a few hundreds
2657 requests for it to be re-integrated into the farm and start
2658 receiving traffic. This is normal, though very rare. It is
2659 indicated here in case you would have the chance to observe
2660 it, so that you don't worry.
2661
2662 static-rr Each server is used in turns, according to their weights.
2663 This algorithm is as similar to roundrobin except that it is
2664 static, which means that changing a server's weight on the
2665 fly will have no effect. On the other hand, it has no design
2666 limitation on the number of servers, and when a server goes
2667 up, it is always immediately reintroduced into the farm, once
2668 the full map is recomputed. It also uses slightly less CPU to
2669 run (around -1%).
Willy Tarreau0ba27502007-12-24 16:55:16 +01002670
Willy Tarreau2d2a7f82008-03-17 12:07:56 +01002671 leastconn The server with the lowest number of connections receives the
2672 connection. Round-robin is performed within groups of servers
2673 of the same load to ensure that all servers will be used. Use
2674 of this algorithm is recommended where very long sessions are
2675 expected, such as LDAP, SQL, TSE, etc... but is not very well
2676 suited for protocols using short sessions such as HTTP. This
2677 algorithm is dynamic, which means that server weights may be
2678 adjusted on the fly for slow starts for instance.
2679
Willy Tarreauf09c6602012-02-13 17:12:08 +01002680 first The first server with available connection slots receives the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03002681 connection. The servers are chosen from the lowest numeric
Willy Tarreauf09c6602012-02-13 17:12:08 +01002682 identifier to the highest (see server parameter "id"), which
2683 defaults to the server's position in the farm. Once a server
Willy Tarreau64559c52012-04-07 09:08:45 +02002684 reaches its maxconn value, the next server is used. It does
Willy Tarreauf09c6602012-02-13 17:12:08 +01002685 not make sense to use this algorithm without setting maxconn.
2686 The purpose of this algorithm is to always use the smallest
2687 number of servers so that extra servers can be powered off
2688 during non-intensive hours. This algorithm ignores the server
2689 weight, and brings more benefit to long session such as RDP
Willy Tarreau64559c52012-04-07 09:08:45 +02002690 or IMAP than HTTP, though it can be useful there too. In
2691 order to use this algorithm efficiently, it is recommended
2692 that a cloud controller regularly checks server usage to turn
2693 them off when unused, and regularly checks backend queue to
2694 turn new servers on when the queue inflates. Alternatively,
2695 using "http-check send-state" may inform servers on the load.
Willy Tarreauf09c6602012-02-13 17:12:08 +01002696
Willy Tarreau0ba27502007-12-24 16:55:16 +01002697 source The source IP address is hashed and divided by the total
2698 weight of the running servers to designate which server will
2699 receive the request. This ensures that the same client IP
2700 address will always reach the same server as long as no
2701 server goes down or up. If the hash result changes due to the
2702 number of running servers changing, many clients will be
2703 directed to a different server. This algorithm is generally
2704 used in TCP mode where no cookie may be inserted. It may also
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002705 be used on the Internet to provide a best-effort stickiness
Willy Tarreau0ba27502007-12-24 16:55:16 +01002706 to clients which refuse session cookies. This algorithm is
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002707 static by default, which means that changing a server's
2708 weight on the fly will have no effect, but this can be
2709 changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002710
Oskar Stolc8dc41842012-05-19 10:19:54 +01002711 uri This algorithm hashes either the left part of the URI (before
2712 the question mark) or the whole URI (if the "whole" parameter
2713 is present) and divides the hash value by the total weight of
2714 the running servers. The result designates which server will
2715 receive the request. This ensures that the same URI will
2716 always be directed to the same server as long as no server
2717 goes up or down. This is used with proxy caches and
2718 anti-virus proxies in order to maximize the cache hit rate.
2719 Note that this algorithm may only be used in an HTTP backend.
2720 This algorithm is static by default, which means that
2721 changing a server's weight on the fly will have no effect,
2722 but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002723
Oskar Stolc8dc41842012-05-19 10:19:54 +01002724 This algorithm supports two optional parameters "len" and
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002725 "depth", both followed by a positive integer number. These
2726 options may be helpful when it is needed to balance servers
2727 based on the beginning of the URI only. The "len" parameter
2728 indicates that the algorithm should only consider that many
2729 characters at the beginning of the URI to compute the hash.
2730 Note that having "len" set to 1 rarely makes sense since most
2731 URIs start with a leading "/".
2732
2733 The "depth" parameter indicates the maximum directory depth
2734 to be used to compute the hash. One level is counted for each
2735 slash in the request. If both parameters are specified, the
2736 evaluation stops when either is reached.
2737
Willy Tarreau0ba27502007-12-24 16:55:16 +01002738 url_param The URL parameter specified in argument will be looked up in
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002739 the query string of each HTTP GET request.
2740
2741 If the modifier "check_post" is used, then an HTTP POST
Cyril Bontédc4d9032012-04-08 21:57:39 +02002742 request entity will be searched for the parameter argument,
2743 when it is not found in a query string after a question mark
Willy Tarreau226071e2014-04-10 11:55:45 +02002744 ('?') in the URL. The message body will only start to be
2745 analyzed once either the advertised amount of data has been
2746 received or the request buffer is full. In the unlikely event
2747 that chunked encoding is used, only the first chunk is
Cyril Bontédc4d9032012-04-08 21:57:39 +02002748 scanned. Parameter values separated by a chunk boundary, may
Willy Tarreau226071e2014-04-10 11:55:45 +02002749 be randomly balanced if at all. This keyword used to support
2750 an optional <max_wait> parameter which is now ignored.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002751
2752 If the parameter is found followed by an equal sign ('=') and
2753 a value, then the value is hashed and divided by the total
2754 weight of the running servers. The result designates which
2755 server will receive the request.
2756
2757 This is used to track user identifiers in requests and ensure
2758 that a same user ID will always be sent to the same server as
2759 long as no server goes up or down. If no value is found or if
2760 the parameter is not found, then a round robin algorithm is
2761 applied. Note that this algorithm may only be used in an HTTP
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002762 backend. This algorithm is static by default, which means
2763 that changing a server's weight on the fly will have no
2764 effect, but this can be changed using "hash-type".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002765
Cyril Bontédc4d9032012-04-08 21:57:39 +02002766 hdr(<name>) The HTTP header <name> will be looked up in each HTTP
2767 request. Just as with the equivalent ACL 'hdr()' function,
2768 the header name in parenthesis is not case sensitive. If the
2769 header is absent or if it does not contain any value, the
2770 roundrobin algorithm is applied instead.
Benoitaffb4812009-03-25 13:02:10 +01002771
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002772 An optional 'use_domain_only' parameter is available, for
Benoitaffb4812009-03-25 13:02:10 +01002773 reducing the hash algorithm to the main domain part with some
2774 specific headers such as 'Host'. For instance, in the Host
2775 value "haproxy.1wt.eu", only "1wt" will be considered.
2776
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002777 This algorithm is static by default, which means that
2778 changing a server's weight on the fly will have no effect,
2779 but this can be changed using "hash-type".
2780
Willy Tarreau21c741a2019-01-14 18:14:27 +01002781 random
2782 random(<draws>)
2783 A random number will be used as the key for the consistent
Willy Tarreau760e81d2018-05-03 07:20:40 +02002784 hashing function. This means that the servers' weights are
2785 respected, dynamic weight changes immediately take effect, as
2786 well as new server additions. Random load balancing can be
2787 useful with large farms or when servers are frequently added
Willy Tarreau21c741a2019-01-14 18:14:27 +01002788 or removed as it may avoid the hammering effect that could
2789 result from roundrobin or leastconn in this situation. The
2790 hash-balance-factor directive can be used to further improve
2791 fairness of the load balancing, especially in situations
2792 where servers show highly variable response times. When an
2793 argument <draws> is present, it must be an integer value one
2794 or greater, indicating the number of draws before selecting
2795 the least loaded of these servers. It was indeed demonstrated
2796 that picking the least loaded of two servers is enough to
2797 significantly improve the fairness of the algorithm, by
2798 always avoiding to pick the most loaded server within a farm
2799 and getting rid of any bias that could be induced by the
2800 unfair distribution of the consistent list. Higher values N
2801 will take away N-1 of the highest loaded servers at the
2802 expense of performance. With very high values, the algorithm
2803 will converge towards the leastconn's result but much slower.
2804 The default value is 2, which generally shows very good
2805 distribution and performance. This algorithm is also known as
2806 the Power of Two Random Choices and is described here :
2807 http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
Willy Tarreau760e81d2018-05-03 07:20:40 +02002808
Emeric Brun736aa232009-06-30 17:56:00 +02002809 rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02002810 rdp-cookie(<name>)
Emeric Brun736aa232009-06-30 17:56:00 +02002811 The RDP cookie <name> (or "mstshash" if omitted) will be
2812 looked up and hashed for each incoming TCP request. Just as
2813 with the equivalent ACL 'req_rdp_cookie()' function, the name
2814 is not case-sensitive. This mechanism is useful as a degraded
2815 persistence mode, as it makes it possible to always send the
2816 same user (or the same session ID) to the same server. If the
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002817 cookie is not found, the normal roundrobin algorithm is
Emeric Brun736aa232009-06-30 17:56:00 +02002818 used instead.
2819
2820 Note that for this to work, the frontend must ensure that an
2821 RDP cookie is already present in the request buffer. For this
2822 you must use 'tcp-request content accept' rule combined with
2823 a 'req_rdp_cookie_cnt' ACL.
2824
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02002825 This algorithm is static by default, which means that
2826 changing a server's weight on the fly will have no effect,
2827 but this can be changed using "hash-type".
2828
Cyril Bontédc4d9032012-04-08 21:57:39 +02002829 See also the rdp_cookie pattern fetch function.
Simon Hormanab814e02011-06-24 14:50:20 +09002830
Willy Tarreau0ba27502007-12-24 16:55:16 +01002831 <arguments> is an optional list of arguments which may be needed by some
Marek Majkowski9c30fc12008-04-27 23:25:55 +02002832 algorithms. Right now, only "url_param" and "uri" support an
2833 optional argument.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002834
Willy Tarreau3cd9af22009-03-15 14:06:41 +01002835 The load balancing algorithm of a backend is set to roundrobin when no other
2836 algorithm, mode nor option have been set. The algorithm may only be set once
2837 for each backend.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002838
Lukas Tribus80512b12018-10-27 20:07:40 +02002839 With authentication schemes that require the same connection like NTLM, URI
John Roesler27c754c2019-07-10 15:45:51 -05002840 based algorithms must not be used, as they would cause subsequent requests
Lukas Tribus80512b12018-10-27 20:07:40 +02002841 to be routed to different backend servers, breaking the invalid assumptions
2842 NTLM relies on.
2843
Willy Tarreau0ba27502007-12-24 16:55:16 +01002844 Examples :
2845 balance roundrobin
2846 balance url_param userid
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002847 balance url_param session_id check_post 64
Benoitaffb4812009-03-25 13:02:10 +01002848 balance hdr(User-Agent)
2849 balance hdr(host)
2850 balance hdr(Host) use_domain_only
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002851
2852 Note: the following caveats and limitations on using the "check_post"
2853 extension with "url_param" must be considered :
2854
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002855 - all POST requests are eligible for consideration, because there is no way
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002856 to determine if the parameters will be found in the body or entity which
2857 may contain binary data. Therefore another method may be required to
2858 restrict consideration of POST requests that have no URL parameters in
2859 the body. (see acl reqideny http_end)
2860
2861 - using a <max_wait> value larger than the request buffer size does not
2862 make sense and is useless. The buffer size is set at build time, and
2863 defaults to 16 kB.
2864
2865 - Content-Encoding is not supported, the parameter search will probably
2866 fail; and load balancing will fall back to Round Robin.
2867
2868 - Expect: 100-continue is not supported, load balancing will fall back to
2869 Round Robin.
2870
Lukas Tribus23953682017-04-28 13:24:30 +00002871 - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk.
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002872 If the entire parameter value is not present in the first chunk, the
2873 selection of server is undefined (actually, defined by how little
2874 actually appeared in the first chunk).
2875
2876 - This feature does not support generation of a 100, 411 or 501 response.
2877
2878 - In some cases, requesting "check_post" MAY attempt to scan the entire
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01002879 contents of a message body. Scanning normally terminates when linear
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02002880 white space or control characters are found, indicating the end of what
2881 might be a URL parameter list. This is probably not a concern with SGML
2882 type message bodies.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002883
Willy Tarreau294d0f02015-08-10 19:40:12 +02002884 See also : "dispatch", "cookie", "transparent", "hash-type" and "http_proxy".
Willy Tarreau0ba27502007-12-24 16:55:16 +01002885
2886
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002887bind [<address>]:<port_range> [, ...] [param*]
2888bind /<path> [, ...] [param*]
Willy Tarreau0ba27502007-12-24 16:55:16 +01002889 Define one or several listening addresses and/or ports in a frontend.
2890 May be used in sections : defaults | frontend | listen | backend
2891 no | yes | yes | no
2892 Arguments :
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002893 <address> is optional and can be a host name, an IPv4 address, an IPv6
2894 address, or '*'. It designates the address the frontend will
2895 listen on. If unset, all IPv4 addresses of the system will be
2896 listened on. The same will apply for '*' or the system's
David du Colombier9c938da2011-03-17 10:40:27 +01002897 special address "0.0.0.0". The IPv6 equivalent is '::'.
Willy Tarreau24709282013-03-10 21:32:12 +01002898 Optionally, an address family prefix may be used before the
2899 address to force the family regardless of the address format,
2900 which can be useful to specify a path to a unix socket with
2901 no slash ('/'). Currently supported prefixes are :
2902 - 'ipv4@' -> address is always IPv4
2903 - 'ipv6@' -> address is always IPv6
2904 - 'unix@' -> address is a path to a local unix socket
Willy Tarreau70f72e02014-07-08 00:37:50 +02002905 - 'abns@' -> address is in abstract namespace (Linux only).
2906 Note: since abstract sockets are not "rebindable", they
2907 do not cope well with multi-process mode during
2908 soft-restart, so it is better to avoid them if
2909 nbproc is greater than 1. The effect is that if the
2910 new process fails to start, only one of the old ones
2911 will be able to rebind to the socket.
Willy Tarreau40aa0702013-03-10 23:51:38 +01002912 - 'fd@<n>' -> use file descriptor <n> inherited from the
2913 parent. The fd must be bound and may or may not already
2914 be listening.
William Lallemand2fe7dd02018-09-11 16:51:29 +02002915 - 'sockpair@<n>'-> like fd@ but you must use the fd of a
2916 connected unix socket or of a socketpair. The bind waits
2917 to receive a FD over the unix socket and uses it as if it
2918 was the FD of an accept(). Should be used carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02002919 You may want to reference some environment variables in the
2920 address parameter, see section 2.3 about environment
2921 variables.
Willy Tarreaub1e52e82008-01-13 14:49:51 +01002922
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002923 <port_range> is either a unique TCP port, or a port range for which the
2924 proxy will accept connections for the IP address specified
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002925 above. The port is mandatory for TCP listeners. Note that in
2926 the case of an IPv6 address, the port is always the number
2927 after the last colon (':'). A range can either be :
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002928 - a numerical port (ex: '80')
2929 - a dash-delimited ports range explicitly stating the lower
2930 and upper bounds (ex: '2000-2100') which are included in
2931 the range.
2932
2933 Particular care must be taken against port ranges, because
2934 every <address:port> couple consumes one socket (= a file
2935 descriptor), so it's easy to consume lots of descriptors
2936 with a simple range, and to run out of sockets. Also, each
2937 <address:port> couple must be used only once among all
2938 instances running on a same system. Please note that binding
2939 to ports lower than 1024 generally require particular
Jamie Gloudon801a0a32012-08-25 00:18:33 -04002940 privileges to start the program, which are independent of
Willy Tarreauc5011ca2010-03-22 11:53:56 +01002941 the 'uid' parameter.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002942
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002943 <path> is a UNIX socket path beginning with a slash ('/'). This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01002944 alternative to the TCP listening port. HAProxy will then
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002945 receive UNIX connections on the socket located at this place.
2946 The path must begin with a slash and by default is absolute.
2947 It can be relative to the prefix defined by "unix-bind" in
2948 the global section. Note that the total length of the prefix
2949 followed by the socket path cannot exceed some system limits
2950 for UNIX sockets, which commonly are set to 107 characters.
2951
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002952 <param*> is a list of parameters common to all sockets declared on the
2953 same line. These numerous parameters depend on OS and build
2954 options and have a complete section dedicated to them. Please
2955 refer to section 5 to for more details.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002956
Willy Tarreau0ba27502007-12-24 16:55:16 +01002957 It is possible to specify a list of address:port combinations delimited by
2958 commas. The frontend will then listen on all of these addresses. There is no
2959 fixed limit to the number of addresses and ports which can be listened on in
2960 a frontend, as well as there is no limit to the number of "bind" statements
2961 in a frontend.
2962
2963 Example :
2964 listen http_proxy
2965 bind :80,:443
2966 bind 10.0.0.1:10080,10.0.0.1:10443
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002967 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy
Willy Tarreau0ba27502007-12-24 16:55:16 +01002968
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002969 listen http_https_proxy
2970 bind :80
Cyril Bonté0d44fc62012-10-09 22:45:33 +02002971 bind :443 ssl crt /etc/haproxy/site.pem
Willy Tarreaua0ee1d02012-09-10 09:01:23 +02002972
Willy Tarreau24709282013-03-10 21:32:12 +01002973 listen http_https_proxy_explicit
2974 bind ipv6@:80
2975 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem
2976 bind unix@ssl-frontend.sock user root mode 600 accept-proxy
2977
Willy Tarreaudad36a32013-03-11 01:20:04 +01002978 listen external_bind_app1
William Lallemandb2f07452015-05-12 14:27:13 +02002979 bind "fd@${FD_APP1}"
Willy Tarreaudad36a32013-03-11 01:20:04 +01002980
Willy Tarreau55dcaf62015-09-27 15:03:15 +02002981 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
2982 sun_path length is used for the address length. Some other programs
2983 such as socat use the string length only by default. Pass the option
2984 ",unix-tightsocklen=0" to any abstract socket definition in socat to
2985 make it compatible with HAProxy's.
2986
Willy Tarreauceb24bc2010-11-09 12:46:41 +01002987 See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol
Willy Tarreaub6205fd2012-09-24 12:27:33 +02002988 documentation, and section 5 about bind options.
Willy Tarreau0ba27502007-12-24 16:55:16 +01002989
2990
Christopher Fauletff4121f2017-11-22 16:38:49 +01002991bind-process [ all | odd | even | <process_num>[-[<process_num>]] ] ...
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01002992 Limit visibility of an instance to a certain set of processes numbers.
2993 May be used in sections : defaults | frontend | listen | backend
2994 yes | yes | yes | yes
2995 Arguments :
2996 all All process will see this instance. This is the default. It
2997 may be used to override a default value.
2998
Willy Tarreaua9db57e2013-01-18 11:29:29 +01002999 odd This instance will be enabled on processes 1,3,5,...63. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003000 option may be combined with other numbers.
3001
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003002 even This instance will be enabled on processes 2,4,6,...64. This
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003003 option may be combined with other numbers. Do not use it
3004 with less than 2 processes otherwise some instances might be
3005 missing from all processes.
3006
Christopher Fauletff4121f2017-11-22 16:38:49 +01003007 process_num The instance will be enabled on this process number or range,
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003008 whose values must all be between 1 and 32 or 64 depending on
Christopher Fauletff4121f2017-11-22 16:38:49 +01003009 the machine's word size. Ranges can be partially defined. The
3010 higher bound can be omitted. In such case, it is replaced by
3011 the corresponding maximum value. If a proxy is bound to
3012 process numbers greater than the configured global.nbproc, it
3013 will either be forced to process #1 if a single process was
Willy Tarreau102df612014-05-07 23:56:38 +02003014 specified, or to all processes otherwise.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003015
3016 This keyword limits binding of certain instances to certain processes. This
3017 is useful in order not to have too many processes listening to the same
3018 ports. For instance, on a dual-core machine, it might make sense to set
3019 'nbproc 2' in the global section, then distributes the listeners among 'odd'
3020 and 'even' instances.
3021
Willy Tarreaua9db57e2013-01-18 11:29:29 +01003022 At the moment, it is not possible to reference more than 32 or 64 processes
3023 using this keyword, but this should be more than enough for most setups.
3024 Please note that 'all' really means all processes regardless of the machine's
3025 word size, and is not limited to the first 32 or 64.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003026
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02003027 Each "bind" line may further be limited to a subset of the proxy's processes,
3028 please consult the "process" bind keyword in section 5.1.
3029
Willy Tarreaub369a042014-09-16 13:21:03 +02003030 When a frontend has no explicit "bind-process" line, it tries to bind to all
3031 the processes referenced by its "bind" lines. That means that frontends can
3032 easily adapt to their listeners' processes.
3033
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003034 If some backends are referenced by frontends bound to other processes, the
3035 backend automatically inherits the frontend's processes.
3036
3037 Example :
3038 listen app_ip1
3039 bind 10.0.0.1:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003040 bind-process odd
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003041
3042 listen app_ip2
3043 bind 10.0.0.2:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003044 bind-process even
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003045
3046 listen management
3047 bind 10.0.0.3:80
Willy Tarreaubfcd3112010-10-23 11:22:08 +02003048 bind-process 1 2 3 4
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003049
Willy Tarreau110ecc12012-11-15 17:50:01 +01003050 listen management
3051 bind 10.0.0.4:80
3052 bind-process 1-4
3053
Willy Tarreau6ae1ba62014-05-07 19:01:58 +02003054 See also : "nbproc" in global section, and "process" in section 5.1.
Willy Tarreau0b9c02c2009-02-04 22:05:05 +01003055
3056
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02003057block { if | unless } <condition> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01003058 Block a layer 7 request if/unless a condition is matched
3059 May be used in sections : defaults | frontend | listen | backend
3060 no | yes | yes | yes
3061
3062 The HTTP request will be blocked very early in the layer 7 processing
3063 if/unless <condition> is matched. A 403 error will be returned if the request
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003064 is blocked. The condition has to reference ACLs (see section 7). This is
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02003065 typically used to deny access to certain sensitive resources if some
Willy Tarreau0ba27502007-12-24 16:55:16 +01003066 conditions are met or not met. There is no fixed limit to the number of
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03003067 "block" statements per instance. To block connections at layer 4 (without
3068 sending a 403 error) see "tcp-request connection reject" and
3069 "tcp-request content reject" rules.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003070
Jarno Huuskonen8c8c3492016-12-28 18:50:29 +02003071 This form is deprecated, do not use it in any new configuration, use the new
3072 "http-request deny" instead.
3073
Willy Tarreau0ba27502007-12-24 16:55:16 +01003074 Example:
3075 acl invalid_src src 0.0.0.0/7 224.0.0.0/3
3076 acl invalid_src src_port 0:1023
3077 acl local_dst hdr(host) -i localhost
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +03003078 # block is deprecated. Use http-request deny instead:
3079 #block if invalid_src || local_dst
3080 http-request deny if invalid_src || local_dst
Willy Tarreau0ba27502007-12-24 16:55:16 +01003081
Jarno Huuskonen95b012b2017-04-06 13:59:14 +03003082 See also : section 7 about ACL usage, "http-request deny",
3083 "http-response deny", "tcp-request connection reject" and
3084 "tcp-request content reject".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003085
3086capture cookie <name> len <length>
3087 Capture and log a cookie in the request and in the response.
3088 May be used in sections : defaults | frontend | listen | backend
3089 no | yes | yes | no
3090 Arguments :
3091 <name> is the beginning of the name of the cookie to capture. In order
3092 to match the exact name, simply suffix the name with an equal
3093 sign ('='). The full name will appear in the logs, which is
3094 useful with application servers which adjust both the cookie name
Davor Ocelice9ed2812017-12-25 17:49:28 +01003095 and value (e.g. ASPSESSIONXXX).
Willy Tarreau0ba27502007-12-24 16:55:16 +01003096
3097 <length> is the maximum number of characters to report in the logs, which
3098 include the cookie name, the equal sign and the value, all in the
3099 standard "name=value" form. The string will be truncated on the
3100 right if it exceeds <length>.
3101
3102 Only the first cookie is captured. Both the "cookie" request headers and the
3103 "set-cookie" response headers are monitored. This is particularly useful to
3104 check for application bugs causing session crossing or stealing between
3105 users, because generally the user's cookies can only change on a login page.
3106
3107 When the cookie was not presented by the client, the associated log column
3108 will report "-". When a request does not cause a cookie to be assigned by the
3109 server, a "-" is reported in the response column.
3110
3111 The capture is performed in the frontend only because it is necessary that
3112 the log format does not change for a given frontend depending on the
3113 backends. This may change in the future. Note that there can be only one
Willy Tarreau193b8c62012-11-22 00:17:38 +01003114 "capture cookie" statement in a frontend. The maximum capture length is set
3115 by the global "tune.http.cookielen" setting and defaults to 63 characters. It
3116 is not possible to specify a capture in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003117
3118 Example:
3119 capture cookie ASPSESSION len 32
3120
3121 See also : "capture request header", "capture response header" as well as
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003122 section 8 about logging.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003123
3124
3125capture request header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01003126 Capture and log the last occurrence of the specified request header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003127 May be used in sections : defaults | frontend | listen | backend
3128 no | yes | yes | no
3129 Arguments :
3130 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003131 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01003132 appear in the requests, with the first letter of each word in
3133 upper case. The header name will not appear in the logs, only the
3134 value is reported, but the position in the logs is respected.
3135
3136 <length> is the maximum number of characters to extract from the value and
3137 report in the logs. The string will be truncated on the right if
3138 it exceeds <length>.
3139
Willy Tarreau4460d032012-11-21 23:37:37 +01003140 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01003141 value will be added to the logs between braces ('{}'). If multiple headers
3142 are captured, they will be delimited by a vertical bar ('|') and will appear
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003143 in the same order they were declared in the configuration. Non-existent
3144 headers will be logged just as an empty string. Common uses for request
3145 header captures include the "Host" field in virtual hosting environments, the
3146 "Content-length" when uploads are supported, "User-agent" to quickly
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003147 differentiate between real users and robots, and "X-Forwarded-For" in proxied
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003148 environments to find where the request came from.
3149
3150 Note that when capturing headers such as "User-agent", some spaces may be
3151 logged, making the log analysis more difficult. Thus be careful about what
3152 you log if you know your log parser is not smart enough to rely on the
3153 braces.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003154
Willy Tarreau0900abb2012-11-22 00:21:46 +01003155 There is no limit to the number of captured request headers nor to their
3156 length, though it is wise to keep them low to limit memory usage per session.
3157 In order to keep log format consistent for a same frontend, header captures
3158 can only be declared in a frontend. It is not possible to specify a capture
3159 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003160
3161 Example:
3162 capture request header Host len 15
3163 capture request header X-Forwarded-For len 15
Cyril Bontéd1b0f7c2015-10-26 22:37:39 +01003164 capture request header Referer len 15
Willy Tarreau0ba27502007-12-24 16:55:16 +01003165
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003166 See also : "capture cookie", "capture response header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01003167 about logging.
3168
3169
3170capture response header <name> len <length>
Willy Tarreau4460d032012-11-21 23:37:37 +01003171 Capture and log the last occurrence of the specified response header.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003172 May be used in sections : defaults | frontend | listen | backend
3173 no | yes | yes | no
3174 Arguments :
3175 <name> is the name of the header to capture. The header names are not
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003176 case-sensitive, but it is a common practice to write them as they
Willy Tarreau0ba27502007-12-24 16:55:16 +01003177 appear in the response, with the first letter of each word in
3178 upper case. The header name will not appear in the logs, only the
3179 value is reported, but the position in the logs is respected.
3180
3181 <length> is the maximum number of characters to extract from the value and
3182 report in the logs. The string will be truncated on the right if
3183 it exceeds <length>.
3184
Willy Tarreau4460d032012-11-21 23:37:37 +01003185 The complete value of the last occurrence of the header is captured. The
Willy Tarreau0ba27502007-12-24 16:55:16 +01003186 result will be added to the logs between braces ('{}') after the captured
3187 request headers. If multiple headers are captured, they will be delimited by
3188 a vertical bar ('|') and will appear in the same order they were declared in
Willy Tarreaucc6c8912009-02-22 10:53:55 +01003189 the configuration. Non-existent headers will be logged just as an empty
3190 string. Common uses for response header captures include the "Content-length"
3191 header which indicates how many bytes are expected to be returned, the
3192 "Location" header to track redirections.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003193
Willy Tarreau0900abb2012-11-22 00:21:46 +01003194 There is no limit to the number of captured response headers nor to their
3195 length, though it is wise to keep them low to limit memory usage per session.
3196 In order to keep log format consistent for a same frontend, header captures
3197 can only be declared in a frontend. It is not possible to specify a capture
3198 in a "defaults" section.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003199
3200 Example:
3201 capture response header Content-length len 9
3202 capture response header Location len 15
3203
Willy Tarreauc57f0e22009-05-10 13:12:33 +02003204 See also : "capture cookie", "capture request header" as well as section 8
Willy Tarreau0ba27502007-12-24 16:55:16 +01003205 about logging.
3206
3207
Cyril Bontéf0c60612010-02-06 14:44:47 +01003208clitimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01003209 Set the maximum inactivity time on the client side.
3210 May be used in sections : defaults | frontend | listen | backend
3211 yes | yes | yes | no
3212 Arguments :
3213 <timeout> is the timeout value is specified in milliseconds by default, but
3214 can be in any other unit if the number is suffixed by the unit,
3215 as explained at the top of this document.
3216
3217 The inactivity timeout applies when the client is expected to acknowledge or
3218 send data. In HTTP mode, this timeout is particularly important to consider
3219 during the first phase, when the client sends the request, and during the
3220 response while it is reading data sent by the server. The value is specified
3221 in milliseconds by default, but can be in any other unit if the number is
3222 suffixed by the unit, as specified at the top of this document. In TCP mode
3223 (and to a lesser extent, in HTTP mode), it is highly recommended that the
3224 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003225 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +01003226 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +01003227 (e.g. 4 or 5 seconds).
Willy Tarreau0ba27502007-12-24 16:55:16 +01003228
3229 This parameter is specific to frontends, but can be specified once for all in
3230 "defaults" sections. This is in fact one of the easiest solutions not to
3231 forget about it. An unspecified timeout results in an infinite timeout, which
3232 is not recommended. Such a usage is accepted and works but reports a warning
3233 during startup because it may results in accumulation of expired sessions in
3234 the system if the system's timeouts are not configured either.
3235
3236 This parameter is provided for compatibility but is currently deprecated.
3237 Please use "timeout client" instead.
3238
Willy Tarreau036fae02008-01-06 13:24:40 +01003239 See also : "timeout client", "timeout http-request", "timeout server", and
3240 "srvtimeout".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003241
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003242compression algo <algorithm> ...
3243compression type <mime type> ...
Willy Tarreau70737d12012-10-27 00:34:28 +02003244compression offload
William Lallemand82fe75c2012-10-23 10:25:10 +02003245 Enable HTTP compression.
3246 May be used in sections : defaults | frontend | listen | backend
3247 yes | yes | yes | yes
3248 Arguments :
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003249 algo is followed by the list of supported compression algorithms.
3250 type is followed by the list of MIME types that will be compressed.
3251 offload makes haproxy work as a compression offloader only (see notes).
3252
3253 The currently supported algorithms are :
Willy Tarreauc91840a2015-03-28 17:00:39 +01003254 identity this is mostly for debugging, and it was useful for developing
3255 the compression feature. Identity does not apply any change on
3256 data.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003257
Willy Tarreauc91840a2015-03-28 17:00:39 +01003258 gzip applies gzip compression. This setting is only available when
Baptiste Assmannf085d632015-12-21 17:57:32 +01003259 support for zlib or libslz was built in.
Willy Tarreauc91840a2015-03-28 17:00:39 +01003260
3261 deflate same as "gzip", but with deflate algorithm and zlib format.
3262 Note that this algorithm has ambiguous support on many
3263 browsers and no support at all from recent ones. It is
3264 strongly recommended not to use it for anything else than
3265 experimentation. This setting is only available when support
Baptiste Assmannf085d632015-12-21 17:57:32 +01003266 for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003267
Willy Tarreauc91840a2015-03-28 17:00:39 +01003268 raw-deflate same as "deflate" without the zlib wrapper, and used as an
3269 alternative when the browser wants "deflate". All major
3270 browsers understand it and despite violating the standards,
3271 it is known to work better than "deflate", at least on MSIE
3272 and some versions of Safari. Do not use it in conjunction
3273 with "deflate", use either one or the other since both react
3274 to the same Accept-Encoding token. This setting is only
Baptiste Assmannf085d632015-12-21 17:57:32 +01003275 available when support for zlib or libslz was built in.
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003276
Dmitry Sivachenko87c208b2012-11-22 20:03:26 +04003277 Compression will be activated depending on the Accept-Encoding request
Cyril Bonté316a8cf2012-11-11 13:38:27 +01003278 header. With identity, it does not take care of that header.
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04003279 If backend servers support HTTP compression, these directives
3280 will be no-op: haproxy will see the compressed response and will not
3281 compress again. If backend servers do not support HTTP compression and
3282 there is Accept-Encoding header in request, haproxy will compress the
3283 matching response.
Willy Tarreau70737d12012-10-27 00:34:28 +02003284
3285 The "offload" setting makes haproxy remove the Accept-Encoding header to
3286 prevent backend servers from compressing responses. It is strongly
3287 recommended not to do this because this means that all the compression work
3288 will be done on the single point where haproxy is located. However in some
3289 deployment scenarios, haproxy may be installed in front of a buggy gateway
Dmitry Sivachenkoc9f3b452012-11-28 17:47:11 +04003290 with broken HTTP compression implementation which can't be turned off.
3291 In that case haproxy can be used to prevent that gateway from emitting
3292 invalid payloads. In this case, simply removing the header in the
3293 configuration does not work because it applies before the header is parsed,
3294 so that prevents haproxy from compressing. The "offload" setting should
Willy Tarreauffea9fd2014-07-12 16:37:02 +02003295 then be used for such scenarios. Note: for now, the "offload" setting is
3296 ignored when set in a defaults section.
William Lallemand82fe75c2012-10-23 10:25:10 +02003297
William Lallemand05097442012-11-20 12:14:28 +01003298 Compression is disabled when:
Baptiste Assmann650d53d2013-01-05 15:44:44 +01003299 * the request does not advertise a supported compression algorithm in the
3300 "Accept-Encoding" header
3301 * the response message is not HTTP/1.1
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01003302 * HTTP status code is not one of 200, 201, 202, or 203
Baptiste Assmann650d53d2013-01-05 15:44:44 +01003303 * response contain neither a "Content-Length" header nor a
3304 "Transfer-Encoding" whose last value is "chunked"
3305 * response contains a "Content-Type" header whose first value starts with
3306 "multipart"
3307 * the response contains the "no-transform" value in the "Cache-control"
3308 header
3309 * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7
3310 and later
3311 * The response contains a "Content-Encoding" header, indicating that the
3312 response is already compressed (see compression offload)
Tim Duesterhusbb48c9a2019-01-30 23:46:04 +01003313 * The response contains an invalid "ETag" header or multiple ETag headers
William Lallemand05097442012-11-20 12:14:28 +01003314
Tim Duesterhusb229f012019-01-29 16:38:56 +01003315 Note: The compression does not emit the Warning header.
William Lallemand05097442012-11-20 12:14:28 +01003316
William Lallemand82fe75c2012-10-23 10:25:10 +02003317 Examples :
3318 compression algo gzip
3319 compression type text/html text/plain
Willy Tarreau0ba27502007-12-24 16:55:16 +01003320
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003321
Cyril Bontéf0c60612010-02-06 14:44:47 +01003322contimeout <timeout> (deprecated)
Willy Tarreau0ba27502007-12-24 16:55:16 +01003323 Set the maximum time to wait for a connection attempt to a server to succeed.
3324 May be used in sections : defaults | frontend | listen | backend
3325 yes | no | yes | yes
3326 Arguments :
3327 <timeout> is the timeout value is specified in milliseconds by default, but
3328 can be in any other unit if the number is suffixed by the unit,
3329 as explained at the top of this document.
3330
3331 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003332 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +01003333 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +01003334 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003335 connect timeout also presets the queue timeout to the same value if this one
3336 has not been specified. Historically, the contimeout was also used to set the
3337 tarpit timeout in a listen section, which is not possible in a pure frontend.
3338
3339 This parameter is specific to backends, but can be specified once for all in
3340 "defaults" sections. This is in fact one of the easiest solutions not to
3341 forget about it. An unspecified timeout results in an infinite timeout, which
3342 is not recommended. Such a usage is accepted and works but reports a warning
3343 during startup because it may results in accumulation of failed sessions in
3344 the system if the system's timeouts are not configured either.
3345
3346 This parameter is provided for backwards compatibility but is currently
3347 deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit"
3348 instead.
3349
3350 See also : "timeout connect", "timeout queue", "timeout tarpit",
3351 "timeout server", "contimeout".
3352
3353
Willy Tarreau55165fe2009-05-10 12:02:55 +02003354cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ]
Willy Tarreau4992dd22012-05-31 21:02:17 +02003355 [ postonly ] [ preserve ] [ httponly ] [ secure ]
3356 [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ]
Christopher Fauletdb2cdbb2020-01-21 11:06:48 +01003357 [ dynamic ] [ attr <value> ]*
Willy Tarreau0ba27502007-12-24 16:55:16 +01003358 Enable cookie-based persistence in a backend.
3359 May be used in sections : defaults | frontend | listen | backend
3360 yes | no | yes | yes
3361 Arguments :
3362 <name> is the name of the cookie which will be monitored, modified or
3363 inserted in order to bring persistence. This cookie is sent to
3364 the client via a "Set-Cookie" header in the response, and is
3365 brought back by the client in a "Cookie" header in all requests.
3366 Special care should be taken to choose a name which does not
3367 conflict with any likely application cookie. Also, if the same
Davor Ocelice9ed2812017-12-25 17:49:28 +01003368 backends are subject to be used by the same clients (e.g.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003369 HTTP/HTTPS), care should be taken to use different cookie names
3370 between all backends if persistence between them is not desired.
3371
3372 rewrite This keyword indicates that the cookie will be provided by the
3373 server and that haproxy will have to modify its value to set the
3374 server's identifier in it. This mode is handy when the management
3375 of complex combinations of "Set-cookie" and "Cache-control"
3376 headers is left to the application. The application can then
3377 decide whether or not it is appropriate to emit a persistence
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003378 cookie. Since all responses should be monitored, this mode
3379 doesn't work in HTTP tunnel mode. Unless the application
Davor Ocelice9ed2812017-12-25 17:49:28 +01003380 behavior is very complex and/or broken, it is advised not to
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003381 start with this mode for new deployments. This keyword is
3382 incompatible with "insert" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003383
3384 insert This keyword indicates that the persistence cookie will have to
Willy Tarreaua79094d2010-08-31 22:54:15 +02003385 be inserted by haproxy in server responses if the client did not
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003386
Willy Tarreaua79094d2010-08-31 22:54:15 +02003387 already have a cookie that would have permitted it to access this
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003388 server. When used without the "preserve" option, if the server
Michael Prokop4438c602019-05-24 10:25:45 +02003389 emits a cookie with the same name, it will be removed before
Davor Ocelice9ed2812017-12-25 17:49:28 +01003390 processing. For this reason, this mode can be used to upgrade
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003391 existing configurations running in the "rewrite" mode. The cookie
3392 will only be a session cookie and will not be stored on the
3393 client's disk. By default, unless the "indirect" option is added,
3394 the server will see the cookies emitted by the client. Due to
3395 caching effects, it is generally wise to add the "nocache" or
3396 "postonly" keywords (see below). The "insert" keyword is not
3397 compatible with "rewrite" and "prefix".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003398
3399 prefix This keyword indicates that instead of relying on a dedicated
3400 cookie for the persistence, an existing one will be completed.
3401 This may be needed in some specific environments where the client
3402 does not support more than one single cookie and the application
3403 already needs it. In this case, whenever the server sets a cookie
3404 named <name>, it will be prefixed with the server's identifier
3405 and a delimiter. The prefix will be removed from all client
3406 requests so that the server still finds the cookie it emitted.
3407 Since all requests and responses are subject to being modified,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01003408 this mode doesn't work with tunnel mode. The "prefix" keyword is
Willy Tarreau37229df2011-10-17 12:24:55 +02003409 not compatible with "rewrite" and "insert". Note: it is highly
3410 recommended not to use "indirect" with "prefix", otherwise server
3411 cookie updates would not be sent to clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003412
Willy Tarreaua79094d2010-08-31 22:54:15 +02003413 indirect When this option is specified, no cookie will be emitted to a
3414 client which already has a valid one for the server which has
3415 processed the request. If the server sets such a cookie itself,
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003416 it will be removed, unless the "preserve" option is also set. In
3417 "insert" mode, this will additionally remove cookies from the
3418 requests transmitted to the server, making the persistence
3419 mechanism totally transparent from an application point of view.
Willy Tarreau37229df2011-10-17 12:24:55 +02003420 Note: it is highly recommended not to use "indirect" with
3421 "prefix", otherwise server cookie updates would not be sent to
3422 clients.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003423
3424 nocache This option is recommended in conjunction with the insert mode
3425 when there is a cache between the client and HAProxy, as it
3426 ensures that a cacheable response will be tagged non-cacheable if
3427 a cookie needs to be inserted. This is important because if all
3428 persistence cookies are added on a cacheable home page for
3429 instance, then all customers will then fetch the page from an
3430 outer cache and will all share the same persistence cookie,
3431 leading to one server receiving much more traffic than others.
3432 See also the "insert" and "postonly" options.
3433
3434 postonly This option ensures that cookie insertion will only be performed
3435 on responses to POST requests. It is an alternative to the
3436 "nocache" option, because POST responses are not cacheable, so
3437 this ensures that the persistence cookie will never get cached.
3438 Since most sites do not need any sort of persistence before the
3439 first POST which generally is a login request, this is a very
3440 efficient method to optimize caching without risking to find a
3441 persistence cookie in the cache.
3442 See also the "insert" and "nocache" options.
3443
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003444 preserve This option may only be used with "insert" and/or "indirect". It
3445 allows the server to emit the persistence cookie itself. In this
3446 case, if a cookie is found in the response, haproxy will leave it
3447 untouched. This is useful in order to end persistence after a
3448 logout request for instance. For this, the server just has to
Davor Ocelice9ed2812017-12-25 17:49:28 +01003449 emit a cookie with an invalid value (e.g. empty) or with a date in
Willy Tarreauba4c5be2010-10-23 12:46:42 +02003450 the past. By combining this mechanism with the "disable-on-404"
3451 check option, it is possible to perform a completely graceful
3452 shutdown because users will definitely leave the server after
3453 they logout.
3454
Willy Tarreau4992dd22012-05-31 21:02:17 +02003455 httponly This option tells haproxy to add an "HttpOnly" cookie attribute
3456 when a cookie is inserted. This attribute is used so that a
3457 user agent doesn't share the cookie with non-HTTP components.
3458 Please check RFC6265 for more information on this attribute.
3459
3460 secure This option tells haproxy to add a "Secure" cookie attribute when
3461 a cookie is inserted. This attribute is used so that a user agent
3462 never emits this cookie over non-secure channels, which means
3463 that a cookie learned with this flag will be presented only over
3464 SSL/TLS connections. Please check RFC6265 for more information on
3465 this attribute.
3466
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003467 domain This option allows to specify the domain at which a cookie is
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003468 inserted. It requires exactly one parameter: a valid domain
Willy Tarreau68a897b2009-12-03 23:28:34 +01003469 name. If the domain begins with a dot, the browser is allowed to
3470 use it for any host ending with that name. It is also possible to
3471 specify several domain names by invoking this option multiple
3472 times. Some browsers might have small limits on the number of
3473 domains, so be careful when doing that. For the record, sending
3474 10 domains to MSIE 6 or Firefox 2 works as expected.
Krzysztof Piotr Oledzkiefe3b6f2008-05-23 23:49:32 +02003475
Willy Tarreau996a92c2010-10-13 19:30:47 +02003476 maxidle This option allows inserted cookies to be ignored after some idle
3477 time. It only works with insert-mode cookies. When a cookie is
3478 sent to the client, the date this cookie was emitted is sent too.
3479 Upon further presentations of this cookie, if the date is older
3480 than the delay indicated by the parameter (in seconds), it will
3481 be ignored. Otherwise, it will be refreshed if needed when the
3482 response is sent to the client. This is particularly useful to
3483 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003484 too long on the same server (e.g. after a farm size change). When
Willy Tarreau996a92c2010-10-13 19:30:47 +02003485 this option is set and a cookie has no date, it is always
3486 accepted, but gets refreshed in the response. This maintains the
3487 ability for admins to access their sites. Cookies that have a
3488 date in the future further than 24 hours are ignored. Doing so
3489 lets admins fix timezone issues without risking kicking users off
3490 the site.
3491
3492 maxlife This option allows inserted cookies to be ignored after some life
3493 time, whether they're in use or not. It only works with insert
3494 mode cookies. When a cookie is first sent to the client, the date
3495 this cookie was emitted is sent too. Upon further presentations
3496 of this cookie, if the date is older than the delay indicated by
3497 the parameter (in seconds), it will be ignored. If the cookie in
3498 the request has no date, it is accepted and a date will be set.
3499 Cookies that have a date in the future further than 24 hours are
3500 ignored. Doing so lets admins fix timezone issues without risking
3501 kicking users off the site. Contrary to maxidle, this value is
3502 not refreshed, only the first visit date counts. Both maxidle and
3503 maxlife may be used at the time. This is particularly useful to
3504 prevent users who never close their browsers from remaining for
Davor Ocelice9ed2812017-12-25 17:49:28 +01003505 too long on the same server (e.g. after a farm size change). This
Willy Tarreau996a92c2010-10-13 19:30:47 +02003506 is stronger than the maxidle method in that it forces a
3507 redispatch after some absolute delay.
3508
Olivier Houchard4e694042017-03-14 20:01:29 +01003509 dynamic Activate dynamic cookies. When used, a session cookie is
3510 dynamically created for each server, based on the IP and port
3511 of the server, and a secret key, specified in the
3512 "dynamic-cookie-key" backend directive.
3513 The cookie will be regenerated each time the IP address change,
3514 and is only generated for IPv4/IPv6.
3515
Christopher Fauletdb2cdbb2020-01-21 11:06:48 +01003516 attr This option tells haproxy to add an extra attribute when a
3517 cookie is inserted. The attribute value can contain any
3518 characters except control ones or ";". This option may be
3519 repeated.
3520
Willy Tarreau0ba27502007-12-24 16:55:16 +01003521 There can be only one persistence cookie per HTTP backend, and it can be
3522 declared in a defaults section. The value of the cookie will be the value
3523 indicated after the "cookie" keyword in a "server" statement. If no cookie
3524 is declared for a given server, the cookie is not set.
Willy Tarreau6a06a402007-07-15 20:15:28 +02003525
Willy Tarreau0ba27502007-12-24 16:55:16 +01003526 Examples :
3527 cookie JSESSIONID prefix
3528 cookie SRV insert indirect nocache
3529 cookie SRV insert postonly indirect
Willy Tarreau996a92c2010-10-13 19:30:47 +02003530 cookie SRV insert indirect nocache maxidle 30m maxlife 8h
Willy Tarreau0ba27502007-12-24 16:55:16 +01003531
Willy Tarreau294d0f02015-08-10 19:40:12 +02003532 See also : "balance source", "capture cookie", "server" and "ignore-persist".
Willy Tarreau0ba27502007-12-24 16:55:16 +01003533
Willy Tarreau983e01e2010-01-11 18:42:06 +01003534
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003535declare capture [ request | response ] len <length>
3536 Declares a capture slot.
3537 May be used in sections : defaults | frontend | listen | backend
3538 no | yes | yes | no
3539 Arguments:
3540 <length> is the length allowed for the capture.
3541
3542 This declaration is only available in the frontend or listen section, but the
3543 reserved slot can be used in the backends. The "request" keyword allocates a
3544 capture slot for use in the request, and "response" allocates a capture slot
3545 for use in the response.
3546
3547 See also: "capture-req", "capture-res" (sample converters),
Baptiste Assmann5ac425c2015-10-21 23:13:46 +02003548 "capture.req.hdr", "capture.res.hdr" (sample fetches),
Thierry FOURNIERa0a1b752015-05-26 17:44:32 +02003549 "http-request capture" and "http-response capture".
3550
3551
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003552default-server [param*]
3553 Change default options for a server in a backend
3554 May be used in sections : defaults | frontend | listen | backend
3555 yes | no | yes | yes
3556 Arguments:
Willy Tarreau983e01e2010-01-11 18:42:06 +01003557 <param*> is a list of parameters for this server. The "default-server"
3558 keyword accepts an important number of options and has a complete
3559 section dedicated to it. Please refer to section 5 for more
3560 details.
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003561
Willy Tarreau983e01e2010-01-11 18:42:06 +01003562 Example :
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +01003563 default-server inter 1000 weight 13
3564
3565 See also: "server" and section 5 about server options
Willy Tarreau0ba27502007-12-24 16:55:16 +01003566
Willy Tarreau983e01e2010-01-11 18:42:06 +01003567
Willy Tarreau0ba27502007-12-24 16:55:16 +01003568default_backend <backend>
3569 Specify the backend to use when no "use_backend" rule has been matched.
3570 May be used in sections : defaults | frontend | listen | backend
3571 yes | yes | yes | no
3572 Arguments :
3573 <backend> is the name of the backend to use.
3574
3575 When doing content-switching between frontend and backends using the
3576 "use_backend" keyword, it is often useful to indicate which backend will be
3577 used when no rule has matched. It generally is the dynamic backend which
3578 will catch all undetermined requests.
3579
Willy Tarreau0ba27502007-12-24 16:55:16 +01003580 Example :
3581
3582 use_backend dynamic if url_dyn
3583 use_backend static if url_css url_img extension_img
3584 default_backend dynamic
3585
Willy Tarreau98d04852015-05-26 12:18:29 +02003586 See also : "use_backend"
Willy Tarreau2769aa02007-12-27 18:26:09 +01003587
Willy Tarreau0ba27502007-12-24 16:55:16 +01003588
Baptiste Assmann27f51342013-10-09 06:51:49 +02003589description <string>
3590 Describe a listen, frontend or backend.
3591 May be used in sections : defaults | frontend | listen | backend
3592 no | yes | yes | yes
3593 Arguments : string
3594
3595 Allows to add a sentence to describe the related object in the HAProxy HTML
3596 stats page. The description will be printed on the right of the object name
3597 it describes.
3598 No need to backslash spaces in the <string> arguments.
3599
3600
Willy Tarreau0ba27502007-12-24 16:55:16 +01003601disabled
3602 Disable a proxy, frontend or backend.
3603 May be used in sections : defaults | frontend | listen | backend
3604 yes | yes | yes | yes
3605 Arguments : none
3606
3607 The "disabled" keyword is used to disable an instance, mainly in order to
3608 liberate a listening port or to temporarily disable a service. The instance
3609 will still be created and its configuration will be checked, but it will be
3610 created in the "stopped" state and will appear as such in the statistics. It
3611 will not receive any traffic nor will it send any health-checks or logs. It
3612 is possible to disable many instances at once by adding the "disabled"
3613 keyword in a "defaults" section.
3614
3615 See also : "enabled"
3616
3617
Willy Tarreau5ce94572010-06-07 14:35:41 +02003618dispatch <address>:<port>
3619 Set a default server address
3620 May be used in sections : defaults | frontend | listen | backend
3621 no | no | yes | yes
Cyril Bonté108cf6e2012-04-21 23:30:29 +02003622 Arguments :
Willy Tarreau5ce94572010-06-07 14:35:41 +02003623
3624 <address> is the IPv4 address of the default server. Alternatively, a
3625 resolvable hostname is supported, but this name will be resolved
3626 during start-up.
3627
3628 <ports> is a mandatory port specification. All connections will be sent
3629 to this port, and it is not permitted to use port offsets as is
3630 possible with normal servers.
3631
Willy Tarreau787aed52011-04-15 06:45:37 +02003632 The "dispatch" keyword designates a default server for use when no other
Willy Tarreau5ce94572010-06-07 14:35:41 +02003633 server can take the connection. In the past it was used to forward non
3634 persistent connections to an auxiliary load balancer. Due to its simple
3635 syntax, it has also been used for simple TCP relays. It is recommended not to
3636 use it for more clarity, and to use the "server" directive instead.
3637
3638 See also : "server"
3639
Olivier Houchard4e694042017-03-14 20:01:29 +01003640
3641dynamic-cookie-key <string>
3642 Set the dynamic cookie secret key for a backend.
3643 May be used in sections : defaults | frontend | listen | backend
3644 yes | no | yes | yes
3645 Arguments : The secret key to be used.
3646
3647 When dynamic cookies are enabled (see the "dynamic" directive for cookie),
Davor Ocelice9ed2812017-12-25 17:49:28 +01003648 a dynamic cookie is created for each server (unless one is explicitly
Olivier Houchard4e694042017-03-14 20:01:29 +01003649 specified on the "server" line), using a hash of the IP address of the
3650 server, the TCP port, and the secret key.
Davor Ocelice9ed2812017-12-25 17:49:28 +01003651 That way, we can ensure session persistence across multiple load-balancers,
Olivier Houchard4e694042017-03-14 20:01:29 +01003652 even if servers are dynamically added or removed.
Willy Tarreau5ce94572010-06-07 14:35:41 +02003653
Willy Tarreau0ba27502007-12-24 16:55:16 +01003654enabled
3655 Enable a proxy, frontend or backend.
3656 May be used in sections : defaults | frontend | listen | backend
3657 yes | yes | yes | yes
3658 Arguments : none
3659
3660 The "enabled" keyword is used to explicitly enable an instance, when the
3661 defaults has been set to "disabled". This is very rarely used.
3662
3663 See also : "disabled"
3664
3665
3666errorfile <code> <file>
3667 Return a file contents instead of errors generated by HAProxy
3668 May be used in sections : defaults | frontend | listen | backend
3669 yes | yes | yes | yes
3670 Arguments :
3671 <code> is the HTTP status code. Currently, HAProxy is capable of
Florian Tham9f3bda02020-01-08 13:35:30 +01003672 generating codes 200, 400, 403, 404, 405, 408, 410, 425, 429, 500,
3673 502, 503, and 504.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003674
3675 <file> designates a file containing the full HTTP response. It is
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003676 recommended to follow the common practice of appending ".http" to
Willy Tarreau0ba27502007-12-24 16:55:16 +01003677 the filename so that people do not confuse the response with HTML
Willy Tarreau59140a22009-02-22 12:02:30 +01003678 error pages, and to use absolute paths, since files are read
3679 before any chroot is performed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01003680
3681 It is important to understand that this keyword is not meant to rewrite
3682 errors returned by the server, but errors detected and returned by HAProxy.
3683 This is why the list of supported errors is limited to a small set.
3684
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003685 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3686
Willy Tarreau0ba27502007-12-24 16:55:16 +01003687 The files are returned verbatim on the TCP socket. This allows any trick such
3688 as redirections to another URL or site, as well as tricks to clean cookies,
3689 force enable or disable caching, etc... The package provides default error
3690 files returning the same contents as default errors.
3691
Willy Tarreau59140a22009-02-22 12:02:30 +01003692 The files should not exceed the configured buffer size (BUFSIZE), which
3693 generally is 8 or 16 kB, otherwise they will be truncated. It is also wise
Davor Ocelice9ed2812017-12-25 17:49:28 +01003694 not to put any reference to local contents (e.g. images) in order to avoid
Willy Tarreau59140a22009-02-22 12:02:30 +01003695 loops between the client and HAProxy when all servers are down, causing an
3696 error to be returned instead of an image. For better HTTP compliance, it is
3697 recommended that all header lines end with CR-LF and not LF alone.
3698
Willy Tarreau0ba27502007-12-24 16:55:16 +01003699 The files are read at the same time as the configuration and kept in memory.
3700 For this reason, the errors continue to be returned even when the process is
3701 chrooted, and no file change is considered while the process is running. A
Willy Tarreauc27debf2008-01-06 08:57:02 +01003702 simple method for developing those files consists in associating them to the
Willy Tarreau0ba27502007-12-24 16:55:16 +01003703 403 status code and interrogating a blocked URL.
3704
3705 See also : "errorloc", "errorloc302", "errorloc303"
3706
Willy Tarreau59140a22009-02-22 12:02:30 +01003707 Example :
3708 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
Willy Tarreau989222a2016-01-15 10:26:26 +01003709 errorfile 408 /dev/null # work around Chrome pre-connect bug
Willy Tarreau59140a22009-02-22 12:02:30 +01003710 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
3711 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
3712
Willy Tarreau2769aa02007-12-27 18:26:09 +01003713
3714errorloc <code> <url>
3715errorloc302 <code> <url>
3716 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3717 May be used in sections : defaults | frontend | listen | backend
3718 yes | yes | yes | yes
3719 Arguments :
3720 <code> is the HTTP status code. Currently, HAProxy is capable of
Florian Tham9f3bda02020-01-08 13:35:30 +01003721 generating codes 200, 400, 403, 404, 405, 408, 410, 425, 429, 500,
3722 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003723
3724 <url> it is the exact contents of the "Location" header. It may contain
3725 either a relative URI to an error page hosted on the same site,
3726 or an absolute URI designating an error page on another site.
3727 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01003728 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01003729
3730 It is important to understand that this keyword is not meant to rewrite
3731 errors returned by the server, but errors detected and returned by HAProxy.
3732 This is why the list of supported errors is limited to a small set.
3733
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003734 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3735
Willy Tarreau2769aa02007-12-27 18:26:09 +01003736 Note that both keyword return the HTTP 302 status code, which tells the
3737 client to fetch the designated URL using the same HTTP method. This can be
3738 quite problematic in case of non-GET methods such as POST, because the URL
3739 sent to the client might not be allowed for something other than GET. To
Willy Tarreau989222a2016-01-15 10:26:26 +01003740 work around this problem, please use "errorloc303" which send the HTTP 303
Willy Tarreau2769aa02007-12-27 18:26:09 +01003741 status code, indicating to the client that the URL must be fetched with a GET
3742 request.
3743
3744 See also : "errorfile", "errorloc303"
3745
3746
3747errorloc303 <code> <url>
3748 Return an HTTP redirection to a URL instead of errors generated by HAProxy
3749 May be used in sections : defaults | frontend | listen | backend
3750 yes | yes | yes | yes
3751 Arguments :
3752 <code> is the HTTP status code. Currently, HAProxy is capable of
Florian Tham9f3bda02020-01-08 13:35:30 +01003753 generating codes 200, 400, 403, 404, 405, 408, 410, 425, 429, 500,
3754 502, 503, and 504.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003755
3756 <url> it is the exact contents of the "Location" header. It may contain
3757 either a relative URI to an error page hosted on the same site,
3758 or an absolute URI designating an error page on another site.
3759 Special care should be given to relative URIs to avoid redirect
Davor Ocelice9ed2812017-12-25 17:49:28 +01003760 loops if the URI itself may generate the same error (e.g. 500).
Willy Tarreau2769aa02007-12-27 18:26:09 +01003761
3762 It is important to understand that this keyword is not meant to rewrite
3763 errors returned by the server, but errors detected and returned by HAProxy.
3764 This is why the list of supported errors is limited to a small set.
3765
Willy Tarreauae94d4d2011-05-11 16:28:49 +02003766 Code 200 is emitted in response to requests matching a "monitor-uri" rule.
3767
Willy Tarreau2769aa02007-12-27 18:26:09 +01003768 Note that both keyword return the HTTP 303 status code, which tells the
3769 client to fetch the designated URL using the same HTTP GET method. This
3770 solves the usual problems associated with "errorloc" and the 302 code. It is
3771 possible that some very old browsers designed before HTTP/1.1 do not support
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01003772 it, but no such problem has been reported till now.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003773
3774 See also : "errorfile", "errorloc", "errorloc302"
3775
3776
Simon Horman51a1cf62015-02-03 13:00:44 +09003777email-alert from <emailaddr>
3778 Declare the from email address to be used in both the envelope and header
Davor Ocelice9ed2812017-12-25 17:49:28 +01003779 of email alerts. This is the address that email alerts are sent from.
Simon Horman51a1cf62015-02-03 13:00:44 +09003780 May be used in sections: defaults | frontend | listen | backend
3781 yes | yes | yes | yes
3782
3783 Arguments :
3784
3785 <emailaddr> is the from email address to use when sending email alerts
3786
3787 Also requires "email-alert mailers" and "email-alert to" to be set
3788 and if so sending email alerts is enabled for the proxy.
3789
Simon Horman64e34162015-02-06 11:11:57 +09003790 See also : "email-alert level", "email-alert mailers",
Cyril Bonté307ee1e2015-09-28 23:16:06 +02003791 "email-alert myhostname", "email-alert to", section 3.6 about
3792 mailers.
Simon Horman64e34162015-02-06 11:11:57 +09003793
3794
3795email-alert level <level>
3796 Declare the maximum log level of messages for which email alerts will be
3797 sent. This acts as a filter on the sending of email alerts.
3798 May be used in sections: defaults | frontend | listen | backend
3799 yes | yes | yes | yes
3800
3801 Arguments :
3802
3803 <level> One of the 8 syslog levels:
3804 emerg alert crit err warning notice info debug
3805 The above syslog levels are ordered from lowest to highest.
3806
3807 By default level is alert
3808
3809 Also requires "email-alert from", "email-alert mailers" and
3810 "email-alert to" to be set and if so sending email alerts is enabled
3811 for the proxy.
3812
Simon Horman1421e212015-04-30 13:10:35 +09003813 Alerts are sent when :
3814
3815 * An un-paused server is marked as down and <level> is alert or lower
3816 * A paused server is marked as down and <level> is notice or lower
3817 * A server is marked as up or enters the drain state and <level>
3818 is notice or lower
3819 * "option log-health-checks" is enabled, <level> is info or lower,
3820 and a health check status update occurs
3821
Simon Horman64e34162015-02-06 11:11:57 +09003822 See also : "email-alert from", "email-alert mailers",
3823 "email-alert myhostname", "email-alert to",
Simon Horman51a1cf62015-02-03 13:00:44 +09003824 section 3.6 about mailers.
3825
3826
3827email-alert mailers <mailersect>
3828 Declare the mailers to be used when sending email alerts
3829 May be used in sections: defaults | frontend | listen | backend
3830 yes | yes | yes | yes
3831
3832 Arguments :
3833
3834 <mailersect> is the name of the mailers section to send email alerts.
3835
3836 Also requires "email-alert from" and "email-alert to" to be set
3837 and if so sending email alerts is enabled for the proxy.
3838
Simon Horman64e34162015-02-06 11:11:57 +09003839 See also : "email-alert from", "email-alert level", "email-alert myhostname",
3840 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003841
3842
3843email-alert myhostname <hostname>
3844 Declare the to hostname address to be used when communicating with
3845 mailers.
3846 May be used in sections: defaults | frontend | listen | backend
3847 yes | yes | yes | yes
3848
3849 Arguments :
3850
Baptiste Assmann738bad92015-12-21 15:27:53 +01003851 <hostname> is the hostname to use when communicating with mailers
Simon Horman51a1cf62015-02-03 13:00:44 +09003852
3853 By default the systems hostname is used.
3854
3855 Also requires "email-alert from", "email-alert mailers" and
3856 "email-alert to" to be set and if so sending email alerts is enabled
3857 for the proxy.
3858
Simon Horman64e34162015-02-06 11:11:57 +09003859 See also : "email-alert from", "email-alert level", "email-alert mailers",
3860 "email-alert to", section 3.6 about mailers.
Simon Horman51a1cf62015-02-03 13:00:44 +09003861
3862
3863email-alert to <emailaddr>
Davor Ocelice9ed2812017-12-25 17:49:28 +01003864 Declare both the recipient address in the envelope and to address in the
Simon Horman51a1cf62015-02-03 13:00:44 +09003865 header of email alerts. This is the address that email alerts are sent to.
3866 May be used in sections: defaults | frontend | listen | backend
3867 yes | yes | yes | yes
3868
3869 Arguments :
3870
3871 <emailaddr> is the to email address to use when sending email alerts
3872
3873 Also requires "email-alert mailers" and "email-alert to" to be set
3874 and if so sending email alerts is enabled for the proxy.
3875
Simon Horman64e34162015-02-06 11:11:57 +09003876 See also : "email-alert from", "email-alert level", "email-alert mailers",
Simon Horman51a1cf62015-02-03 13:00:44 +09003877 "email-alert myhostname", section 3.6 about mailers.
3878
3879
Willy Tarreau4de91492010-01-22 19:10:05 +01003880force-persist { if | unless } <condition>
3881 Declare a condition to force persistence on down servers
3882 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01003883 no | no | yes | yes
Willy Tarreau4de91492010-01-22 19:10:05 +01003884
3885 By default, requests are not dispatched to down servers. It is possible to
3886 force this using "option persist", but it is unconditional and redispatches
3887 to a valid server if "option redispatch" is set. That leaves with very little
3888 possibilities to force some requests to reach a server which is artificially
3889 marked down for maintenance operations.
3890
3891 The "force-persist" statement allows one to declare various ACL-based
3892 conditions which, when met, will cause a request to ignore the down status of
3893 a server and still try to connect to it. That makes it possible to start a
3894 server, still replying an error to the health checks, and run a specially
3895 configured browser to test the service. Among the handy methods, one could
3896 use a specific source IP address, or a specific cookie. The cookie also has
3897 the advantage that it can easily be added/removed on the browser from a test
3898 page. Once the service is validated, it is then possible to open the service
3899 to the world by returning a valid response to health checks.
3900
3901 The forced persistence is enabled when an "if" condition is met, or unless an
3902 "unless" condition is met. The final redispatch is always disabled when this
3903 is used.
3904
Cyril Bonté0d4bf012010-04-25 23:21:46 +02003905 See also : "option redispatch", "ignore-persist", "persist",
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +02003906 and section 7 about ACL usage.
Willy Tarreau4de91492010-01-22 19:10:05 +01003907
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003908
3909filter <name> [param*]
3910 Add the filter <name> in the filter list attached to the proxy.
3911 May be used in sections : defaults | frontend | listen | backend
3912 no | yes | yes | yes
3913 Arguments :
3914 <name> is the name of the filter. Officially supported filters are
3915 referenced in section 9.
3916
Tim Düsterhus4896c442016-11-29 02:15:19 +01003917 <param*> is a list of parameters accepted by the filter <name>. The
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003918 parsing of these parameters are the responsibility of the
Tim Düsterhus4896c442016-11-29 02:15:19 +01003919 filter. Please refer to the documentation of the corresponding
3920 filter (section 9) for all details on the supported parameters.
Christopher Fauletc3fe5332016-04-07 15:30:10 +02003921
3922 Multiple occurrences of the filter line can be used for the same proxy. The
3923 same filter can be referenced many times if needed.
3924
3925 Example:
3926 listen
3927 bind *:80
3928
3929 filter trace name BEFORE-HTTP-COMP
3930 filter compression
3931 filter trace name AFTER-HTTP-COMP
3932
3933 compression algo gzip
3934 compression offload
3935
3936 server srv1 192.168.0.1:80
3937
3938 See also : section 9.
3939
Willy Tarreau4de91492010-01-22 19:10:05 +01003940
Willy Tarreau2769aa02007-12-27 18:26:09 +01003941fullconn <conns>
3942 Specify at what backend load the servers will reach their maxconn
3943 May be used in sections : defaults | frontend | listen | backend
3944 yes | no | yes | yes
3945 Arguments :
3946 <conns> is the number of connections on the backend which will make the
3947 servers use the maximal number of connections.
3948
Willy Tarreau198a7442008-01-17 12:05:32 +01003949 When a server has a "maxconn" parameter specified, it means that its number
Willy Tarreau2769aa02007-12-27 18:26:09 +01003950 of concurrent connections will never go higher. Additionally, if it has a
Willy Tarreau198a7442008-01-17 12:05:32 +01003951 "minconn" parameter, it indicates a dynamic limit following the backend's
Willy Tarreau2769aa02007-12-27 18:26:09 +01003952 load. The server will then always accept at least <minconn> connections,
3953 never more than <maxconn>, and the limit will be on the ramp between both
3954 values when the backend has less than <conns> concurrent connections. This
3955 makes it possible to limit the load on the servers during normal loads, but
3956 push it further for important loads without overloading the servers during
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003957 exceptional loads.
Willy Tarreau2769aa02007-12-27 18:26:09 +01003958
Willy Tarreaufbb78422011-06-05 15:38:35 +02003959 Since it's hard to get this value right, haproxy automatically sets it to
3960 10% of the sum of the maxconns of all frontends that may branch to this
Bertrand Jacquin702d44f2013-11-19 11:43:06 +01003961 backend (based on "use_backend" and "default_backend" rules). That way it's
3962 safe to leave it unset. However, "use_backend" involving dynamic names are
3963 not counted since there is no way to know if they could match or not.
Willy Tarreaufbb78422011-06-05 15:38:35 +02003964
Willy Tarreau2769aa02007-12-27 18:26:09 +01003965 Example :
3966 # The servers will accept between 100 and 1000 concurrent connections each
3967 # and the maximum of 1000 will be reached when the backend reaches 10000
3968 # connections.
3969 backend dynamic
3970 fullconn 10000
3971 server srv1 dyn1:80 minconn 100 maxconn 1000
3972 server srv2 dyn2:80 minconn 100 maxconn 1000
3973
3974 See also : "maxconn", "server"
3975
3976
3977grace <time>
3978 Maintain a proxy operational for some time after a soft stop
3979 May be used in sections : defaults | frontend | listen | backend
Cyril Bonté99ed3272010-01-24 23:29:44 +01003980 yes | yes | yes | yes
Willy Tarreau2769aa02007-12-27 18:26:09 +01003981 Arguments :
3982 <time> is the time (by default in milliseconds) for which the instance
3983 will remain operational with the frontend sockets still listening
3984 when a soft-stop is received via the SIGUSR1 signal.
3985
3986 This may be used to ensure that the services disappear in a certain order.
3987 This was designed so that frontends which are dedicated to monitoring by an
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01003988 external equipment fail immediately while other ones remain up for the time
Willy Tarreau2769aa02007-12-27 18:26:09 +01003989 needed by the equipment to detect the failure.
3990
3991 Note that currently, there is very little benefit in using this parameter,
3992 and it may in fact complicate the soft-reconfiguration process more than
3993 simplify it.
3994
Willy Tarreau0ba27502007-12-24 16:55:16 +01003995
Andrew Rodland17be45e2016-10-25 17:04:12 -04003996hash-balance-factor <factor>
3997 Specify the balancing factor for bounded-load consistent hashing
3998 May be used in sections : defaults | frontend | listen | backend
3999 yes | no | no | yes
4000 Arguments :
4001 <factor> is the control for the maximum number of concurrent requests to
4002 send to a server, expressed as a percentage of the average number
Frédéric Lécaille93d33162019-03-06 09:35:59 +01004003 of concurrent requests across all of the active servers.
Andrew Rodland17be45e2016-10-25 17:04:12 -04004004
4005 Specifying a "hash-balance-factor" for a server with "hash-type consistent"
4006 enables an algorithm that prevents any one server from getting too many
4007 requests at once, even if some hash buckets receive many more requests than
4008 others. Setting <factor> to 0 (the default) disables the feature. Otherwise,
4009 <factor> is a percentage greater than 100. For example, if <factor> is 150,
4010 then no server will be allowed to have a load more than 1.5 times the average.
4011 If server weights are used, they will be respected.
4012
4013 If the first-choice server is disqualified, the algorithm will choose another
4014 server based on the request hash, until a server with additional capacity is
4015 found. A higher <factor> allows more imbalance between the servers, while a
4016 lower <factor> means that more servers will be checked on average, affecting
4017 performance. Reasonable values are from 125 to 200.
4018
Willy Tarreau760e81d2018-05-03 07:20:40 +02004019 This setting is also used by "balance random" which internally relies on the
4020 consistent hashing mechanism.
4021
Andrew Rodland17be45e2016-10-25 17:04:12 -04004022 See also : "balance" and "hash-type".
4023
4024
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004025hash-type <method> <function> <modifier>
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004026 Specify a method to use for mapping hashes to servers
4027 May be used in sections : defaults | frontend | listen | backend
4028 yes | no | yes | yes
4029 Arguments :
Bhaskar98634f02013-10-29 23:30:51 -04004030 <method> is the method used to select a server from the hash computed by
4031 the <function> :
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004032
Bhaskar98634f02013-10-29 23:30:51 -04004033 map-based the hash table is a static array containing all alive servers.
4034 The hashes will be very smooth, will consider weights, but
4035 will be static in that weight changes while a server is up
4036 will be ignored. This means that there will be no slow start.
4037 Also, since a server is selected by its position in the array,
4038 most mappings are changed when the server count changes. This
4039 means that when a server goes up or down, or when a server is
4040 added to a farm, most connections will be redistributed to
4041 different servers. This can be inconvenient with caches for
4042 instance.
Willy Tarreau798a39c2010-11-24 15:04:29 +01004043
Bhaskar98634f02013-10-29 23:30:51 -04004044 consistent the hash table is a tree filled with many occurrences of each
4045 server. The hash key is looked up in the tree and the closest
4046 server is chosen. This hash is dynamic, it supports changing
4047 weights while the servers are up, so it is compatible with the
4048 slow start feature. It has the advantage that when a server
4049 goes up or down, only its associations are moved. When a
4050 server is added to the farm, only a few part of the mappings
4051 are redistributed, making it an ideal method for caches.
4052 However, due to its principle, the distribution will never be
4053 very smooth and it may sometimes be necessary to adjust a
4054 server's weight or its ID to get a more balanced distribution.
4055 In order to get the same distribution on multiple load
4056 balancers, it is important that all servers have the exact
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004057 same IDs. Note: consistent hash uses sdbm and avalanche if no
4058 hash function is specified.
Bhaskar98634f02013-10-29 23:30:51 -04004059
4060 <function> is the hash function to be used :
4061
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03004062 sdbm this function was created initially for sdbm (a public-domain
Bhaskar98634f02013-10-29 23:30:51 -04004063 reimplementation of ndbm) database library. It was found to do
4064 well in scrambling bits, causing better distribution of the keys
4065 and fewer splits. It also happens to be a good general hashing
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004066 function with good distribution, unless the total server weight
4067 is a multiple of 64, in which case applying the avalanche
4068 modifier may help.
Bhaskar98634f02013-10-29 23:30:51 -04004069
4070 djb2 this function was first proposed by Dan Bernstein many years ago
4071 on comp.lang.c. Studies have shown that for certain workload this
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004072 function provides a better distribution than sdbm. It generally
4073 works well with text-based inputs though it can perform extremely
4074 poorly with numeric-only input or when the total server weight is
4075 a multiple of 33, unless the avalanche modifier is also used.
4076
Willy Tarreaua0f42712013-11-14 14:30:35 +01004077 wt6 this function was designed for haproxy while testing other
4078 functions in the past. It is not as smooth as the other ones, but
4079 is much less sensible to the input data set or to the number of
4080 servers. It can make sense as an alternative to sdbm+avalanche or
4081 djb2+avalanche for consistent hashing or when hashing on numeric
4082 data such as a source IP address or a visitor identifier in a URL
4083 parameter.
4084
Willy Tarreau324f07f2015-01-20 19:44:50 +01004085 crc32 this is the most common CRC32 implementation as used in Ethernet,
4086 gzip, PNG, etc. It is slower than the other ones but may provide
4087 a better distribution or less predictable results especially when
4088 used on strings.
4089
Bhaskar Maddalab6c0ac92013-11-05 11:54:02 -05004090 <modifier> indicates an optional method applied after hashing the key :
4091
4092 avalanche This directive indicates that the result from the hash
4093 function above should not be used in its raw form but that
4094 a 4-byte full avalanche hash must be applied first. The
4095 purpose of this step is to mix the resulting bits from the
4096 previous hash in order to avoid any undesired effect when
4097 the input contains some limited values or when the number of
4098 servers is a multiple of one of the hash's components (64
4099 for SDBM, 33 for DJB2). Enabling avalanche tends to make the
4100 result less predictable, but it's also not as smooth as when
4101 using the original function. Some testing might be needed
4102 with some workloads. This hash is one of the many proposed
4103 by Bob Jenkins.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004104
Bhaskar98634f02013-10-29 23:30:51 -04004105 The default hash type is "map-based" and is recommended for most usages. The
4106 default function is "sdbm", the selection of a function should be based on
4107 the range of the values being hashed.
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004108
Andrew Rodland17be45e2016-10-25 17:04:12 -04004109 See also : "balance", "hash-balance-factor", "server"
Willy Tarreau6b2e11b2009-10-01 07:52:15 +02004110
4111
Willy Tarreau0ba27502007-12-24 16:55:16 +01004112http-check disable-on-404
4113 Enable a maintenance mode upon HTTP/404 response to health-checks
4114 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau2769aa02007-12-27 18:26:09 +01004115 yes | no | yes | yes
Willy Tarreau0ba27502007-12-24 16:55:16 +01004116 Arguments : none
4117
4118 When this option is set, a server which returns an HTTP code 404 will be
4119 excluded from further load-balancing, but will still receive persistent
4120 connections. This provides a very convenient method for Web administrators
4121 to perform a graceful shutdown of their servers. It is also important to note
4122 that a server which is detected as failed while it was in this mode will not
4123 generate an alert, just a notice. If the server responds 2xx or 3xx again, it
4124 will immediately be reinserted into the farm. The status on the stats page
4125 reports "NOLB" for a server in this mode. It is important to note that this
Willy Tarreaubd741542010-03-16 18:46:54 +01004126 option only works in conjunction with the "httpchk" option. If this option
4127 is used with "http-check expect", then it has precedence over it so that 404
4128 responses will still be considered as soft-stop.
4129
4130 See also : "option httpchk", "http-check expect"
4131
4132
4133http-check expect [!] <match> <pattern>
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004134 Make HTTP health checks consider response contents or specific status codes
Willy Tarreaubd741542010-03-16 18:46:54 +01004135 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau1ee51a62011-08-19 20:04:17 +02004136 yes | no | yes | yes
Willy Tarreaubd741542010-03-16 18:46:54 +01004137 Arguments :
4138 <match> is a keyword indicating how to look for a specific pattern in the
4139 response. The keyword may be one of "status", "rstatus",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004140 "string", or "rstring". The keyword may be preceded by an
Willy Tarreaubd741542010-03-16 18:46:54 +01004141 exclamation mark ("!") to negate the match. Spaces are allowed
4142 between the exclamation mark and the keyword. See below for more
4143 details on the supported keywords.
4144
4145 <pattern> is the pattern to look for. It may be a string or a regular
4146 expression. If the pattern contains spaces, they must be escaped
4147 with the usual backslash ('\').
4148
4149 By default, "option httpchk" considers that response statuses 2xx and 3xx
4150 are valid, and that others are invalid. When "http-check expect" is used,
4151 it defines what is considered valid or invalid. Only one "http-check"
4152 statement is supported in a backend. If a server fails to respond or times
4153 out, the check obviously fails. The available matches are :
4154
4155 status <string> : test the exact string match for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004156 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004157 response's status code is exactly this string. If the
4158 "status" keyword is prefixed with "!", then the response
4159 will be considered invalid if the status code matches.
4160
4161 rstatus <regex> : test a regular expression for the HTTP status code.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004162 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004163 response's status code matches the expression. If the
4164 "rstatus" keyword is prefixed with "!", then the response
4165 will be considered invalid if the status code matches.
4166 This is mostly used to check for multiple codes.
4167
4168 string <string> : test the exact string match in the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004169 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004170 response's body contains this exact string. If the
4171 "string" keyword is prefixed with "!", then the response
4172 will be considered invalid if the body contains this
4173 string. This can be used to look for a mandatory word at
4174 the end of a dynamic page, or to detect a failure when a
Davor Ocelice9ed2812017-12-25 17:49:28 +01004175 specific error appears on the check page (e.g. a stack
Willy Tarreaubd741542010-03-16 18:46:54 +01004176 trace).
4177
4178 rstring <regex> : test a regular expression on the HTTP response body.
Jamie Gloudonaaa21002012-08-25 00:18:33 -04004179 A health check response will be considered valid if the
Willy Tarreaubd741542010-03-16 18:46:54 +01004180 response's body matches this expression. If the "rstring"
4181 keyword is prefixed with "!", then the response will be
4182 considered invalid if the body matches the expression.
4183 This can be used to look for a mandatory word at the end
4184 of a dynamic page, or to detect a failure when a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01004185 error appears on the check page (e.g. a stack trace).
Willy Tarreaubd741542010-03-16 18:46:54 +01004186
4187 It is important to note that the responses will be limited to a certain size
4188 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
4189 Thus, too large responses may not contain the mandatory pattern when using
4190 "string" or "rstring". If a large response is absolutely required, it is
4191 possible to change the default max size by setting the global variable.
4192 However, it is worth keeping in mind that parsing very large responses can
4193 waste some CPU cycles, especially when regular expressions are used, and that
4194 it is always better to focus the checks on smaller resources.
4195
Cyril Bonté32602d22015-01-30 00:07:07 +01004196 Also "http-check expect" doesn't support HTTP keep-alive. Keep in mind that it
4197 will automatically append a "Connection: close" header, meaning that this
4198 header should not be present in the request provided by "option httpchk".
4199
Willy Tarreaubd741542010-03-16 18:46:54 +01004200 Last, if "http-check expect" is combined with "http-check disable-on-404",
4201 then this last one has precedence when the server responds with 404.
4202
4203 Examples :
4204 # only accept status 200 as valid
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01004205 http-check expect status 200
Willy Tarreaubd741542010-03-16 18:46:54 +01004206
4207 # consider SQL errors as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01004208 http-check expect ! string SQL\ Error
Willy Tarreaubd741542010-03-16 18:46:54 +01004209
4210 # consider status 5xx only as errors
Willy Tarreau8f2a1e72011-01-06 16:36:10 +01004211 http-check expect ! rstatus ^5
Willy Tarreaubd741542010-03-16 18:46:54 +01004212
4213 # check that we have a correct hexadecimal tag before /html
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03004214 http-check expect rstring <!--tag:[0-9a-f]*--></html>
Willy Tarreau0ba27502007-12-24 16:55:16 +01004215
Willy Tarreaubd741542010-03-16 18:46:54 +01004216 See also : "option httpchk", "http-check disable-on-404"
Willy Tarreau2769aa02007-12-27 18:26:09 +01004217
4218
Christopher Fauletf304ad32020-04-09 08:44:06 +02004219http-check send [hdr <name> <value>]* [body <string>]
4220 Add a possible list of headers and/or a body to the request sent during HTTP
4221 health checks.
4222 May be used in sections : defaults | frontend | listen | backend
4223 yes | no | yes | yes
4224 Arguments :
4225 hdr <name> <value> adds the HTTP header field whose name is specified in
4226 <name> and whose value is defined by <value> to the
4227 request sent during HTTP health checks.
4228
4229 body <string> add the body defined by <string> to the request sent
4230 sent during HTTP health checks. If defined, the
4231 "Content-Length" header is thus automatically added
4232 to the request.
4233
4234 In addition to the request line defined by the "option httpchk" directive,
4235 this one is the valid way to add some headers and optionally a body to the
4236 request sent during HTTP health checks. If a body is defined, the associate
4237 "Content-Length" header is automatically added. The old trick consisting to
4238 add headers after the version string on the "option httpchk" line is now
4239 deprecated. Note also the "Connection: close" header is still added if a
4240 "http-check expect" direcive is defined independently of this directive, just
4241 like the state header if the directive "http-check send-state" is defined.
4242
4243 See also : "option httpchk", "http-check send-state" and "http-check expect"
4244
4245
Willy Tarreauef781042010-01-27 11:53:01 +01004246http-check send-state
4247 Enable emission of a state header with HTTP health checks
4248 May be used in sections : defaults | frontend | listen | backend
4249 yes | no | yes | yes
4250 Arguments : none
4251
4252 When this option is set, haproxy will systematically send a special header
4253 "X-Haproxy-Server-State" with a list of parameters indicating to each server
4254 how they are seen by haproxy. This can be used for instance when a server is
4255 manipulated without access to haproxy and the operator needs to know whether
4256 haproxy still sees it up or not, or if the server is the last one in a farm.
4257
4258 The header is composed of fields delimited by semi-colons, the first of which
4259 is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid
4260 checks on the total number before transition, just as appears in the stats
4261 interface. Next headers are in the form "<variable>=<value>", indicating in
4262 no specific order some values available in the stats interface :
Joseph Lynch514061c2015-01-15 17:52:59 -08004263 - a variable "address", containing the address of the backend server.
4264 This corresponds to the <address> field in the server declaration. For
4265 unix domain sockets, it will read "unix".
4266
4267 - a variable "port", containing the port of the backend server. This
4268 corresponds to the <port> field in the server declaration. For unix
4269 domain sockets, it will read "unix".
4270
Willy Tarreauef781042010-01-27 11:53:01 +01004271 - a variable "name", containing the name of the backend followed by a slash
4272 ("/") then the name of the server. This can be used when a server is
4273 checked in multiple backends.
4274
4275 - a variable "node" containing the name of the haproxy node, as set in the
4276 global "node" variable, otherwise the system's hostname if unspecified.
4277
4278 - a variable "weight" indicating the weight of the server, a slash ("/")
4279 and the total weight of the farm (just counting usable servers). This
4280 helps to know if other servers are available to handle the load when this
4281 one fails.
4282
4283 - a variable "scur" indicating the current number of concurrent connections
4284 on the server, followed by a slash ("/") then the total number of
4285 connections on all servers of the same backend.
4286
4287 - a variable "qcur" indicating the current number of requests in the
4288 server's queue.
4289
4290 Example of a header received by the application server :
4291 >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \
4292 scur=13/22; qcur=0
4293
4294 See also : "option httpchk", "http-check disable-on-404"
4295
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004296
4297http-request <action> [options...] [ { if | unless } <condition> ]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004298 Access control for Layer 7 requests
4299
4300 May be used in sections: defaults | frontend | listen | backend
4301 no | yes | yes | yes
4302
Willy Tarreau20b0de52012-12-24 15:45:22 +01004303 The http-request statement defines a set of rules which apply to layer 7
4304 processing. The rules are evaluated in their declaration order when they are
4305 met in a frontend, listen or backend section. Any rule may optionally be
4306 followed by an ACL-based condition, in which case it will only be evaluated
4307 if the condition is true.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004308
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004309 The first keyword is the rule's action. The supported actions are described
4310 below.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004311
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004312 There is no limit to the number of http-request statements per instance.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004313
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004314 It is important to know that http-request rules are processed very early in
4315 the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
4316 or "reqadd" rules. That way, headers added by "add-header"/"set-header" are
4317 visible by almost all further ACL rules.
Willy Tarreau53275e82017-11-24 07:52:01 +01004318
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004319 Using "reqadd"/"reqdel"/"reqrep" to manipulate request headers is discouraged
4320 in newer versions (>= 1.5). But if you need to use regular expression to
4321 delete headers, you can still use "reqdel". Also please use
4322 "http-request deny/allow/tarpit" instead of "reqdeny"/"reqpass"/"reqtarpit".
Willy Tarreauccbcc372012-12-27 12:37:57 +01004323
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004324 Example:
4325 acl nagios src 192.168.129.3
4326 acl local_net src 192.168.0.0/16
4327 acl auth_ok http_auth(L1)
Willy Tarreau20b0de52012-12-24 15:45:22 +01004328
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004329 http-request allow if nagios
4330 http-request allow if local_net auth_ok
4331 http-request auth realm Gimme if local_net auth_ok
4332 http-request deny
Willy Tarreau81499eb2012-12-27 12:19:02 +01004333
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004334 Example:
4335 acl key req.hdr(X-Add-Acl-Key) -m found
4336 acl add path /addacl
4337 acl del path /delacl
Willy Tarreau20b0de52012-12-24 15:45:22 +01004338
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004339 acl myhost hdr(Host) -f myhost.lst
Willy Tarreau20b0de52012-12-24 15:45:22 +01004340
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004341 http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
4342 http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02004343
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004344 Example:
4345 acl value req.hdr(X-Value) -m found
4346 acl setmap path /setmap
4347 acl delmap path /delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06004348
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004349 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06004350
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004351 http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
4352 http-request del-map(map.lst) %[src] if delmap
Sasha Pachev218f0642014-06-16 12:05:59 -06004353
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004354 See also : "stats http-request", section 3.4 about userlists and section 7
4355 about ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06004356
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004357http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004358
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004359 This is used to add a new entry into an ACL. The ACL must be loaded from a
4360 file (even a dummy empty file). The file name of the ACL to be updated is
4361 passed between parentheses. It takes one argument: <key fmt>, which follows
4362 log-format rules, to collect content of the new entry. It performs a lookup
4363 in the ACL before insertion, to avoid duplicated (or more) values. This
4364 lookup is done by a linear search and can be expensive with large lists!
4365 It is the equivalent of the "add acl" command from the stats socket, but can
4366 be triggered by an HTTP request.
Sasha Pachev218f0642014-06-16 12:05:59 -06004367
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004368http-request add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004369
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004370 This appends an HTTP header field whose name is specified in <name> and
4371 whose value is defined by <fmt> which follows the log-format rules (see
4372 Custom Log Format in section 8.2.4). This is particularly useful to pass
4373 connection-specific information to the server (e.g. the client's SSL
4374 certificate), or to combine several headers into one. This rule is not
4375 final, so it is possible to add other similar rules. Note that header
4376 addition is performed immediately, so one rule might reuse the resulting
4377 header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06004378
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004379http-request allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004380
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004381 This stops the evaluation of the rules and lets the request pass the check.
4382 No further "http-request" rules are evaluated.
Sasha Pachev218f0642014-06-16 12:05:59 -06004383
Sasha Pachev218f0642014-06-16 12:05:59 -06004384
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004385http-request auth [realm <realm>] [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004386
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004387 This stops the evaluation of the rules and immediately responds with an
4388 HTTP 401 or 407 error code to invite the user to present a valid user name
4389 and password. No further "http-request" rules are evaluated. An optional
4390 "realm" parameter is supported, it sets the authentication realm that is
4391 returned with the response (typically the application's name).
Sasha Pachev218f0642014-06-16 12:05:59 -06004392
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004393 Example:
4394 acl auth_ok http_auth_group(L1) G1
4395 http-request auth unless auth_ok
Sasha Pachev218f0642014-06-16 12:05:59 -06004396
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02004397http-request cache-use <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06004398
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004399 See section 10.2 about cache setup.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004400
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004401http-request capture <sample> [ len <length> | id <id> ]
4402 [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004403
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004404 This captures sample expression <sample> from the request buffer, and
4405 converts it to a string of at most <len> characters. The resulting string is
4406 stored into the next request "capture" slot, so it will possibly appear next
4407 to some captured HTTP headers. It will then automatically appear in the logs,
4408 and it will be possible to extract it using sample fetch rules to feed it
4409 into headers or anything. The length should be limited given that this size
4410 will be allocated for each capture during the whole session life.
4411 Please check section 7.3 (Fetching samples) and "capture request header" for
4412 more information.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004413
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004414 If the keyword "id" is used instead of "len", the action tries to store the
4415 captured string in a previously declared capture slot. This is useful to run
4416 captures in backends. The slot id can be declared by a previous directive
Baptiste Assmann63b220d2020-01-16 14:34:22 +01004417 "http-request capture" or with the "declare capture" keyword.
4418
4419 When using this action in a backend, double check that the relevant
4420 frontend(s) have the required capture slots otherwise, this rule will be
4421 ignored at run time. This can't be detected at configuration parsing time
4422 due to HAProxy's ability to dynamically resolve backend name at runtime.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004423
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004424http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004425
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004426 This is used to delete an entry from an ACL. The ACL must be loaded from a
4427 file (even a dummy empty file). The file name of the ACL to be updated is
4428 passed between parentheses. It takes one argument: <key fmt>, which follows
4429 log-format rules, to collect content of the entry to delete.
4430 It is the equivalent of the "del acl" command from the stats socket, but can
4431 be triggered by an HTTP request.
Willy Tarreaua0dc23f2015-01-22 20:46:11 +01004432
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004433http-request del-header <name> [ { if | unless } <condition> ]
Willy Tarreauf4c43c12013-06-11 17:01:13 +02004434
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004435 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau9a355ec2013-06-11 17:45:46 +02004436
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004437http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau42cf39e2013-06-11 18:51:32 +02004438
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004439 This is used to delete an entry from a MAP. The MAP must be loaded from a
4440 file (even a dummy empty file). The file name of the MAP to be updated is
4441 passed between parentheses. It takes one argument: <key fmt>, which follows
4442 log-format rules, to collect content of the entry to delete.
4443 It takes one argument: "file name" It is the equivalent of the "del map"
4444 command from the stats socket, but can be triggered by an HTTP request.
Willy Tarreau51347ed2013-06-11 19:34:13 +02004445
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004446http-request deny [deny_status <status>] [ { if | unless } <condition> ]
Patrick Hemmer268a7072018-05-11 12:52:31 -04004447
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004448 This stops the evaluation of the rules and immediately rejects the request
4449 and emits an HTTP 403 error, or optionally the status code specified as an
4450 argument to "deny_status". The list of permitted status codes is limited to
4451 those that can be overridden by the "errorfile" directive.
4452 No further "http-request" rules are evaluated.
Patrick Hemmer268a7072018-05-11 12:52:31 -04004453
Olivier Houchard602bf7d2019-05-10 13:59:15 +02004454http-request disable-l7-retry [ { if | unless } <condition> ]
4455 This disables any attempt to retry the request if it fails for any other
4456 reason than a connection failure. This can be useful for example to make
4457 sure POST requests aren't retried on failure.
4458
Baptiste Assmann333939c2019-01-21 08:34:50 +01004459http-request do-resolve(<var>,<resolvers>,[ipv4,ipv6]) <expr> :
4460
4461 This action performs a DNS resolution of the output of <expr> and stores
4462 the result in the variable <var>. It uses the DNS resolvers section
4463 pointed by <resolvers>.
4464 It is possible to choose a resolution preference using the optional
4465 arguments 'ipv4' or 'ipv6'.
4466 When performing the DNS resolution, the client side connection is on
4467 pause waiting till the end of the resolution.
4468 If an IP address can be found, it is stored into <var>. If any kind of
4469 error occurs, then <var> is not set.
4470 One can use this action to discover a server IP address at run time and
4471 based on information found in the request (IE a Host header).
4472 If this action is used to find the server's IP address (using the
4473 "set-dst" action), then the server IP address in the backend must be set
4474 to 0.0.0.0.
4475
4476 Example:
4477 resolvers mydns
4478 nameserver local 127.0.0.53:53
4479 nameserver google 8.8.8.8:53
4480 timeout retry 1s
4481 hold valid 10s
4482 hold nx 3s
4483 hold other 3s
4484 hold obsolete 0s
4485 accepted_payload_size 8192
4486
4487 frontend fe
4488 bind 10.42.0.1:80
4489 http-request do-resolve(txn.myip,mydns,ipv4) hdr(Host),lower
4490 http-request capture var(txn.myip) len 40
4491
4492 # return 503 when the variable is not set,
4493 # which mean DNS resolution error
4494 use_backend b_503 unless { var(txn.myip) -m found }
4495
4496 default_backend be
4497
4498 backend b_503
4499 # dummy backend used to return 503.
4500 # one can use the errorfile directive to send a nice
4501 # 503 error page to end users
4502
4503 backend be
4504 # rule to prevent HAProxy from reconnecting to services
4505 # on the local network (forged DNS name used to scan the network)
4506 http-request deny if { var(txn.myip) -m ip 127.0.0.0/8 10.0.0.0/8 }
4507 http-request set-dst var(txn.myip)
4508 server clear 0.0.0.0:0
4509
4510 NOTE: Don't forget to set the "protection" rules to ensure HAProxy won't
4511 be used to scan the network or worst won't loop over itself...
4512
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01004513http-request early-hint <name> <fmt> [ { if | unless } <condition> ]
4514
4515 This is used to build an HTTP 103 Early Hints response prior to any other one.
4516 This appends an HTTP header field to this response whose name is specified in
4517 <name> and whose value is defined by <fmt> which follows the log-format rules
4518 (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 +01004519 to the client some Link headers to preload resources required to render the
4520 HTML documents.
Frédéric Lécaille06f5b642018-11-12 11:01:10 +01004521
4522 See RFC 8297 for more information.
4523
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004524http-request redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004525
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004526 This performs an HTTP redirection based on a redirect rule. This is exactly
4527 the same as the "redirect" statement except that it inserts a redirect rule
4528 which can be processed in the middle of other "http-request" rules and that
4529 these rules use the "log-format" strings. See the "redirect" keyword for the
4530 rule's syntax.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004531
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004532http-request reject [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004533
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004534 This stops the evaluation of the rules and immediately closes the connection
4535 without sending any response. It acts similarly to the
4536 "tcp-request content reject" rules. It can be useful to force an immediate
4537 connection closure on HTTP/2 connections.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004538
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004539http-request replace-header <name> <match-regex> <replace-fmt>
4540 [ { if | unless } <condition> ]
Willy Tarreaua9083d02015-05-08 15:27:59 +02004541
Ilya Shipitsin5c836fd2020-02-29 12:34:59 +05004542 This matches the value of all occurrences of header field <name> against
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004543 <match-regex>. Matching is performed case-sensitively. Matching values are
4544 completely replaced by <replace-fmt>. Format characters are allowed in
4545 <replace-fmt> and work like <fmt> arguments in "http-request add-header".
4546 Standard back-references using the backslash ('\') followed by a number are
4547 supported.
Thierry FOURNIER82bf70d2015-05-26 17:58:29 +02004548
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004549 This action acts on whole header lines, regardless of the number of values
4550 they may contain. Thus it is well-suited to process headers naturally
4551 containing commas in their value, such as If-Modified-Since. Headers that
4552 contain a comma-separated list of values, such as Accept, should be processed
4553 using "http-request replace-value".
William Lallemand86d0df02017-11-24 21:36:45 +01004554
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004555 Example:
4556 http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
4557
4558 # applied to:
4559 Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
4560
4561 # outputs:
4562 Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
4563
4564 # assuming the backend IP is 192.168.1.20
Willy Tarreau09448f72014-06-25 18:12:15 +02004565
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004566 http-request replace-header User-Agent curl foo
4567
4568 # applied to:
4569 User-Agent: curl/7.47.0
Willy Tarreau09448f72014-06-25 18:12:15 +02004570
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004571 # outputs:
4572 User-Agent: foo
Willy Tarreau09448f72014-06-25 18:12:15 +02004573
Willy Tarreaudfc85772019-12-17 06:52:51 +01004574http-request replace-path <match-regex> <replace-fmt>
4575 [ { if | unless } <condition> ]
4576
4577 This works like "replace-header" except that it works on the request's path
4578 component instead of a header. The path component starts at the first '/'
4579 after an optional scheme+authority. It does contain the query string if any
4580 is present. The replacement does not modify the scheme nor authority.
4581
4582 It is worth noting that regular expressions may be more expensive to evaluate
4583 than certain ACLs, so rare replacements may benefit from a condition to avoid
4584 performing the evaluation at all if it does not match.
4585
4586 Example:
4587 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
4588 http-request replace-path (.*) /foo\1
4589
4590 # suffix /foo : turn /bar?q=1 into /bar/foo?q=1 :
4591 http-request replace-path ([^?]*)(\?(.*))? \1/foo\2
4592
4593 # strip /foo : turn /foo/bar?q=1 into /bar?q=1
4594 http-request replace-path /foo/(.*) /\1
4595 # or more efficient if only some requests match :
4596 http-request replace-path /foo/(.*) /\1 if { url_beg /foo/ }
4597
Willy Tarreau33810222019-06-12 17:44:02 +02004598http-request replace-uri <match-regex> <replace-fmt>
4599 [ { if | unless } <condition> ]
4600
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004601 This works like "replace-header" except that it works on the request's URI part
4602 instead of a header. The URI part may contain an optional scheme, authority or
4603 query string. These are considered to be part of the value that is matched
4604 against.
4605
4606 It is worth noting that regular expressions may be more expensive to evaluate
4607 than certain ACLs, so rare replacements may benefit from a condition to avoid
4608 performing the evaluation at all if it does not match.
Willy Tarreau33810222019-06-12 17:44:02 +02004609
Willy Tarreaud41821d2019-12-17 06:51:20 +01004610 IMPORTANT NOTE: historically in HTTP/1.x, the vast majority of requests sent
4611 by browsers use the "origin form", which differs from the "absolute form" in
4612 that they do not contain a scheme nor authority in the URI portion. Mostly
4613 only requests sent to proxies, those forged by hand and some emitted by
4614 certain applications use the absolute form. As such, "replace-uri" usually
4615 works fine most of the time in HTTP/1.x with rules starting with a "/". But
4616 with HTTP/2, clients are encouraged to send absolute URIs only, which look
4617 like the ones HTTP/1 clients use to talk to proxies. Such partial replace-uri
4618 rules may then fail in HTTP/2 when they work in HTTP/1. Either the rules need
Willy Tarreaudfc85772019-12-17 06:52:51 +01004619 to be adapted to optionally match a scheme and authority, or replace-path
4620 should be used.
Willy Tarreau33810222019-06-12 17:44:02 +02004621
Willy Tarreaud41821d2019-12-17 06:51:20 +01004622 Example:
4623 # rewrite all "http" absolute requests to "https":
4624 http-request replace-uri ^http://(.*) https://\1
Willy Tarreau33810222019-06-12 17:44:02 +02004625
Willy Tarreaud41821d2019-12-17 06:51:20 +01004626 # prefix /foo : turn /bar?q=1 into /foo/bar?q=1 :
4627 http-request replace-uri ([^/:]*://[^/]*)?(.*) \1/foo\2
Willy Tarreau33810222019-06-12 17:44:02 +02004628
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004629http-request replace-value <name> <match-regex> <replace-fmt>
4630 [ { if | unless } <condition> ]
Willy Tarreau09448f72014-06-25 18:12:15 +02004631
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004632 This works like "replace-header" except that it matches the regex against
4633 every comma-delimited value of the header field <name> instead of the
4634 entire header. This is suited for all headers which are allowed to carry
4635 more than one value. An example could be the Accept header.
Willy Tarreau09448f72014-06-25 18:12:15 +02004636
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004637 Example:
4638 http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
Thierry FOURNIER236657b2015-08-19 08:25:14 +02004639
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004640 # applied to:
4641 X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02004642
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01004643 # outputs:
4644 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 +01004645
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004646http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
4647http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004648
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004649 This actions increments the GPC0 or GPC1 counter according with the sticky
4650 counter designated by <sc-id>. If an error occurs, this action silently fails
4651 and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004652
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004653http-request sc-set-gpt0(<sc-id>) <int> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004654
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004655 This action sets the GPT0 tag according to the sticky counter designated by
4656 <sc-id> and the value of <int>. The expected result is a boolean. If an error
4657 occurs, this action silently fails and the actions evaluation continues.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004658
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004659http-request set-dst <expr> [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02004660
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004661 This is used to set the destination IP address to the value of specified
4662 expression. Useful when a proxy in front of HAProxy rewrites destination IP,
4663 but provides the correct IP in a HTTP header; or you want to mask the IP for
4664 privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
4665 server address in the backend.
Christopher Faulet85d79c92016-11-09 16:54:56 +01004666
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004667 Arguments:
4668 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4669 by some converters.
Christopher Faulet85d79c92016-11-09 16:54:56 +01004670
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004671 Example:
4672 http-request set-dst hdr(x-dst)
4673 http-request set-dst dst,ipmask(24)
Christopher Faulet85d79c92016-11-09 16:54:56 +01004674
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004675 When possible, set-dst preserves the original destination port as long as the
4676 address family allows it, otherwise the destination port is set to 0.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004677
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004678http-request set-dst-port <expr> [ { if | unless } <condition> ]
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004679
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004680 This is used to set the destination port address to the value of specified
4681 expression. If you want to connect to the new address/port, use '0.0.0.0:0'
4682 as a server address in the backend.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004683
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004684 Arguments:
4685 <expr> Is a standard HAProxy expression formed by a sample-fetch
4686 followed by some converters.
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004687
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004688 Example:
4689 http-request set-dst-port hdr(x-port)
4690 http-request set-dst-port int(4000)
Adis Nezirovic2fbcafc2015-07-06 15:44:30 +02004691
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004692 When possible, set-dst-port preserves the original destination address as
4693 long as the address family supports a port, otherwise it forces the
4694 destination address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +02004695
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004696http-request set-header <name> <fmt> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02004697
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004698 This does the same as "http-request add-header" except that the header name
4699 is first removed if it existed. This is useful when passing security
4700 information to the server, where the header must not be manipulated by
4701 external users. Note that the new value is computed before the removal so it
4702 is possible to concatenate a value to an existing header.
William Lallemand44be6402016-05-25 01:51:35 +02004703
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004704 Example:
4705 http-request set-header X-Haproxy-Current-Date %T
4706 http-request set-header X-SSL %[ssl_fc]
4707 http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
4708 http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
4709 http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
4710 http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
4711 http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
4712 http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
4713 http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
William Lallemand44be6402016-05-25 01:51:35 +02004714
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004715http-request set-log-level <level> [ { if | unless } <condition> ]
William Lallemand44be6402016-05-25 01:51:35 +02004716
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004717 This is used to change the log level of the current request when a certain
4718 condition is met. Valid levels are the 8 syslog levels (see the "log"
4719 keyword) plus the special level "silent" which disables logging for this
4720 request. This rule is not final so the last matching rule wins. This rule
4721 can be useful to disable health checks coming from another equipment.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004722
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004723http-request set-map(<file-name>) <key fmt> <value fmt>
4724 [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004725
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004726 This is used to add a new entry into a MAP. The MAP must be loaded from a
4727 file (even a dummy empty file). The file name of the MAP to be updated is
4728 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
4729 log-format rules, used to collect MAP key, and <value fmt>, which follows
4730 log-format rules, used to collect content for the new entry.
4731 It performs a lookup in the MAP before insertion, to avoid duplicated (or
4732 more) values. This lookup is done by a linear search and can be expensive
4733 with large lists! It is the equivalent of the "set map" command from the
4734 stats socket, but can be triggered by an HTTP request.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004735
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004736http-request set-mark <mark> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004737
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004738 This is used to set the Netfilter MARK on all packets sent to the client to
4739 the value passed in <mark> on platforms which support it. This value is an
4740 unsigned 32 bit value which can be matched by netfilter and by the routing
4741 table. It can be expressed both in decimal or hexadecimal format (prefixed by
4742 "0x"). This can be useful to force certain packets to take a different route
4743 (for example a cheaper network path for bulk downloads). This works on Linux
4744 kernels 2.6.32 and above and requires admin privileges.
Willy Tarreau00005ce2016-10-21 15:07:45 +02004745
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004746http-request set-method <fmt> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004747
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004748 This rewrites the request method with the result of the evaluation of format
4749 string <fmt>. There should be very few valid reasons for having to do so as
4750 this is more likely to break something than to fix it.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004751
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004752http-request set-nice <nice> [ { if | unless } <condition> ]
William Lallemand13e9b0c2016-05-25 02:34:07 +02004753
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004754 This sets the "nice" factor of the current request being processed. It only
4755 has effect against the other requests being processed at the same time.
4756 The default value is 0, unless altered by the "nice" setting on the "bind"
4757 line. The accepted range is -1024..1024. The higher the value, the nicest
4758 the request will be. Lower values will make the request more important than
4759 other ones. This can be useful to improve the speed of some requests, or
4760 lower the priority of non-important requests. Using this setting without
4761 prior experimentation can cause some major slowdown.
William Lallemand13e9b0c2016-05-25 02:34:07 +02004762
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004763http-request set-path <fmt> [ { if | unless } <condition> ]
Willy Tarreau00005ce2016-10-21 15:07:45 +02004764
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004765 This rewrites the request path with the result of the evaluation of format
4766 string <fmt>. The query string, if any, is left intact. If a scheme and
4767 authority is found before the path, they are left intact as well. If the
4768 request doesn't have a path ("*"), this one is replaced with the format.
4769 This can be used to prepend a directory component in front of a path for
4770 example. See also "http-request set-query" and "http-request set-uri".
Willy Tarreau2d392c22015-08-24 01:43:45 +02004771
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004772 Example :
4773 # prepend the host name before the path
4774 http-request set-path /%[hdr(host)]%[path]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004775
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004776http-request set-priority-class <expr> [ { if | unless } <condition> ]
Olivier Houchardccaa7de2017-10-02 11:51:03 +02004777
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004778 This is used to set the queue priority class of the current request.
4779 The value must be a sample expression which converts to an integer in the
4780 range -2047..2047. Results outside this range will be truncated.
4781 The priority class determines the order in which queued requests are
4782 processed. Lower values have higher priority.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004783
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004784http-request set-priority-offset <expr> [ { if | unless } <condition> ]
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004785
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004786 This is used to set the queue priority timestamp offset of the current
4787 request. The value must be a sample expression which converts to an integer
4788 in the range -524287..524287. Results outside this range will be truncated.
4789 When a request is queued, it is ordered first by the priority class, then by
4790 the current timestamp adjusted by the given offset in milliseconds. Lower
4791 values have higher priority.
4792 Note that the resulting timestamp is is only tracked with enough precision
4793 for 524,287ms (8m44s287ms). If the request is queued long enough to where the
4794 adjusted timestamp exceeds this value, it will be misidentified as highest
4795 priority. Thus it is important to set "timeout queue" to a value, where when
4796 combined with the offset, does not exceed this limit.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02004797
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004798http-request set-query <fmt> [ { if | unless } <condition> ]
Willy Tarreau20b0de52012-12-24 15:45:22 +01004799
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004800 This rewrites the request's query string which appears after the first
4801 question mark ("?") with the result of the evaluation of format string <fmt>.
4802 The part prior to the question mark is left intact. If the request doesn't
4803 contain a question mark and the new value is not empty, then one is added at
4804 the end of the URI, followed by the new value. If a question mark was
4805 present, it will never be removed even if the value is empty. This can be
4806 used to add or remove parameters from the query string.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08004807
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004808 See also "http-request set-query" and "http-request set-uri".
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004809
4810 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004811 # replace "%3D" with "=" in the query string
4812 http-request set-query %[query,regsub(%3D,=,g)]
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004813
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004814http-request set-src <expr> [ { if | unless } <condition> ]
4815 This is used to set the source IP address to the value of specified
4816 expression. Useful when a proxy in front of HAProxy rewrites source IP, but
4817 provides the correct IP in a HTTP header; or you want to mask source IP for
Olivier Doucet46c517f2020-04-21 09:32:56 +02004818 privacy. All subsequent calls to "src" fetch will return this value
4819 (see example).
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004820
4821 Arguments :
4822 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4823 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004824
Olivier Doucet46c517f2020-04-21 09:32:56 +02004825 See also "option forwardfor".
4826
Cyril Bonté78caf842010-03-10 22:41:43 +01004827 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004828 http-request set-src hdr(x-forwarded-for)
4829 http-request set-src src,ipmask(24)
4830
Olivier Doucet46c517f2020-04-21 09:32:56 +02004831 # After the masking this will track connections
4832 # based on the IP address with the last byte zeroed out.
4833 http-request track-sc0 src
4834
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004835 When possible, set-src preserves the original source port as long as the
4836 address family allows it, otherwise the source port is set to 0.
4837
4838http-request set-src-port <expr> [ { if | unless } <condition> ]
4839
4840 This is used to set the source port address to the value of specified
4841 expression.
4842
4843 Arguments:
4844 <expr> Is a standard HAProxy expression formed by a sample-fetch followed
4845 by some converters.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +01004846
Willy Tarreau20b0de52012-12-24 15:45:22 +01004847 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004848 http-request set-src-port hdr(x-port)
4849 http-request set-src-port int(4000)
4850
4851 When possible, set-src-port preserves the original source address as long as
4852 the address family supports a port, otherwise it forces the source address to
4853 IPv4 "0.0.0.0" before rewriting the port.
4854
4855http-request set-tos <tos> [ { if | unless } <condition> ]
4856
4857 This is used to set the TOS or DSCP field value of packets sent to the client
4858 to the value passed in <tos> on platforms which support this. This value
4859 represents the whole 8 bits of the IP TOS field, and can be expressed both in
4860 decimal or hexadecimal format (prefixed by "0x"). Note that only the 6 higher
4861 bits are used in DSCP or TOS, and the two lower bits are always 0. This can
4862 be used to adjust some routing behavior on border routers based on some
4863 information from the request.
4864
4865 See RFC 2474, 2597, 3260 and 4594 for more information.
4866
4867http-request set-uri <fmt> [ { if | unless } <condition> ]
4868
4869 This rewrites the request URI with the result of the evaluation of format
4870 string <fmt>. The scheme, authority, path and query string are all replaced
4871 at once. This can be used to rewrite hosts in front of proxies, or to
4872 perform complex modifications to the URI such as moving parts between the
4873 path and the query string.
4874 See also "http-request set-path" and "http-request set-query".
4875
4876http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ]
4877
4878 This is used to set the contents of a variable. The variable is declared
4879 inline.
4880
4881 Arguments:
4882 <var-name> The name of the variable starts with an indication about its
4883 scope. The scopes allowed are:
4884 "proc" : the variable is shared with the whole process
4885 "sess" : the variable is shared with the whole session
4886 "txn" : the variable is shared with the transaction
4887 (request and response)
4888 "req" : the variable is shared only during request
4889 processing
4890 "res" : the variable is shared only during response
4891 processing
4892 This prefix is followed by a name. The separator is a '.'.
4893 The name may only contain characters 'a-z', 'A-Z', '0-9'
4894 and '_'.
4895
4896 <expr> Is a standard HAProxy expression formed by a sample-fetch
4897 followed by some converters.
Willy Tarreau20b0de52012-12-24 15:45:22 +01004898
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004899 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004900 http-request set-var(req.my_var) req.fhdr(user-agent),lower
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004901
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004902http-request send-spoe-group <engine-name> <group-name>
4903 [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004904
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02004905 This action is used to trigger sending of a group of SPOE messages. To do so,
4906 the SPOE engine used to send messages must be defined, as well as the SPOE
4907 group to send. Of course, the SPOE engine must refer to an existing SPOE
4908 filter. If not engine name is provided on the SPOE filter line, the SPOE
4909 agent name must be used.
4910
4911 Arguments:
4912 <engine-name> The SPOE engine name.
4913
4914 <group-name> The SPOE group name as specified in the engine
4915 configuration.
4916
4917http-request silent-drop [ { if | unless } <condition> ]
4918
4919 This stops the evaluation of the rules and makes the client-facing connection
4920 suddenly disappear using a system-dependent way that tries to prevent the
4921 client from being notified. The effect it then that the client still sees an
4922 established connection while there's none on HAProxy. The purpose is to
4923 achieve a comparable effect to "tarpit" except that it doesn't use any local
4924 resource at all on the machine running HAProxy. It can resist much higher
4925 loads than "tarpit", and slow down stronger attackers. It is important to
4926 understand the impact of using this mechanism. All stateful equipment placed
4927 between the client and HAProxy (firewalls, proxies, load balancers) will also
4928 keep the established connection for a long time and may suffer from this
4929 action.
4930 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
4931 option is used to block the emission of a TCP reset. On other systems, the
4932 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
4933 router, though it's still delivered to local networks. Do not use it unless
4934 you fully understand how it works.
4935
4936http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
4937
4938 This stops the evaluation of the rules and immediately blocks the request
4939 without responding for a delay specified by "timeout tarpit" or
4940 "timeout connect" if the former is not set. After that delay, if the client
4941 is still connected, an HTTP error 500 (or optionally the status code
4942 specified as an argument to "deny_status") is returned so that the client
4943 does not suspect it has been tarpitted. Logs will report the flags "PT".
4944 The goal of the tarpit rule is to slow down robots during an attack when
4945 they're limited on the number of concurrent requests. It can be very
4946 efficient against very dumb robots, and will significantly reduce the load
4947 on firewalls compared to a "deny" rule. But when facing "correctly"
4948 developed robots, it can make things worse by forcing haproxy and the front
4949 firewall to support insane number of concurrent connections.
4950 See also the "silent-drop" action.
4951
4952http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
4953http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
4954http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
4955
4956 This enables tracking of sticky counters from current request. These rules do
4957 not stop evaluation and do not change default action. The number of counters
4958 that may be simultaneously tracked by the same connection is set in
4959 MAX_SESS_STKCTR at build time (reported in haproxy -vv) which defaults to 3,
4960 so the track-sc number is between 0 and (MAX_SESS_STCKTR-1). The first
4961 "track-sc0" rule executed enables tracking of the counters of the specified
4962 table as the first set. The first "track-sc1" rule executed enables tracking
4963 of the counters of the specified table as the second set. The first
4964 "track-sc2" rule executed enables tracking of the counters of the specified
4965 table as the third set. It is a recommended practice to use the first set of
4966 counters for the per-frontend counters and the second set for the per-backend
4967 ones. But this is just a guideline, all may be used everywhere.
4968
4969 Arguments :
4970 <key> is mandatory, and is a sample expression rule as described in
4971 section 7.3. It describes what elements of the incoming request or
4972 connection will be analyzed, extracted, combined, and used to
4973 select which table entry to update the counters.
4974
4975 <table> is an optional table to be used instead of the default one, which
4976 is the stick-table declared in the current proxy. All the counters
4977 for the matches and updates for the key will then be performed in
4978 that table until the session ends.
4979
4980 Once a "track-sc*" rule is executed, the key is looked up in the table and if
4981 it is not found, an entry is allocated for it. Then a pointer to that entry
4982 is kept during all the session's life, and this entry's counters are updated
4983 as often as possible, every time the session's counters are updated, and also
4984 systematically when the session ends. Counters are only updated for events
4985 that happen after the tracking has been started. As an exception, connection
4986 counters and request counters are systematically updated so that they reflect
4987 useful information.
4988
4989 If the entry tracks concurrent connection counters, one connection is counted
4990 for as long as the entry is tracked, and the entry will not expire during
4991 that time. Tracking counters also provides a performance advantage over just
4992 checking the keys, because only one table lookup is performed for all ACL
4993 checks that make use of it.
4994
4995http-request unset-var(<var-name>) [ { if | unless } <condition> ]
4996
4997 This is used to unset a variable. See above for details about <var-name>.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02004998
4999 Example:
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005000 http-request unset-var(req.my_var)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005001
Christopher Faulet6bd406e2019-11-22 15:34:17 +01005002http-request use-service <service-name> [ { if | unless } <condition> ]
5003
5004 This directive executes the configured HTTP service to reply to the request
5005 and stops the evaluation of the rules. An HTTP service may choose to reply by
5006 sending any valid HTTP response or it may immediately close the connection
5007 without sending any response. Outside natives services, for instance the
5008 Prometheus exporter, it is possible to write your own services in Lua. No
5009 further "http-request" rules are evaluated.
5010
5011 Arguments :
5012 <service-name> is mandatory. It is the service to call
5013
5014 Example:
5015 http-request use-service prometheus-exporter if { path /metrics }
5016
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005017http-request wait-for-handshake [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005018
Cyril Bontéc6ad23b2018-10-17 00:14:50 +02005019 This will delay the processing of the request until the SSL handshake
5020 happened. This is mostly useful to delay processing early data until we're
5021 sure they are valid.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005022
Willy Tarreauef781042010-01-27 11:53:01 +01005023
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005024http-response <action> <options...> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005025 Access control for Layer 7 responses
5026
5027 May be used in sections: defaults | frontend | listen | backend
5028 no | yes | yes | yes
5029
5030 The http-response statement defines a set of rules which apply to layer 7
5031 processing. The rules are evaluated in their declaration order when they are
5032 met in a frontend, listen or backend section. Any rule may optionally be
5033 followed by an ACL-based condition, in which case it will only be evaluated
5034 if the condition is true. Since these rules apply on responses, the backend
5035 rules are applied first, followed by the frontend's rules.
5036
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005037 The first keyword is the rule's action. The supported actions are described
5038 below.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005039
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005040 There is no limit to the number of http-response statements per instance.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005041
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005042 It is important to know that http-response rules are processed very early in
5043 the HTTP processing, before "rspdel" or "rsprep" or "rspadd" rules. That way,
5044 headers added by "add-header"/"set-header" are visible by almost all further
5045 ACL rules.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005046
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005047 Using "rspadd"/"rspdel"/"rsprep" to manipulate request headers is discouraged
5048 in newer versions (>= 1.5). But if you need to use regular expression to
5049 delete headers, you can still use "rspdel". Also please use
5050 "http-response deny" instead of "rspdeny".
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005051
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005052 Example:
5053 acl key_acl res.hdr(X-Acl-Key) -m found
Thierry FOURNIERdad3d1d2014-04-22 18:07:25 +02005054
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005055 acl myhost hdr(Host) -f myhost.lst
Sasha Pachev218f0642014-06-16 12:05:59 -06005056
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005057 http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
5058 http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl
Sasha Pachev218f0642014-06-16 12:05:59 -06005059
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005060 Example:
5061 acl value res.hdr(X-Value) -m found
Sasha Pachev218f0642014-06-16 12:05:59 -06005062
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005063 use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
Sasha Pachev218f0642014-06-16 12:05:59 -06005064
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005065 http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value
5066 http-response del-map(map.lst) %[src] if ! value
Sasha Pachev218f0642014-06-16 12:05:59 -06005067
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005068 See also : "http-request", section 3.4 about userlists and section 7 about
5069 ACL usage.
Sasha Pachev218f0642014-06-16 12:05:59 -06005070
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005071http-response add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005072
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005073 This is used to add a new entry into an ACL. The ACL must be loaded from a
5074 file (even a dummy empty file). The file name of the ACL to be updated is
5075 passed between parentheses. It takes one argument: <key fmt>, which follows
5076 log-format rules, to collect content of the new entry. It performs a lookup
5077 in the ACL before insertion, to avoid duplicated (or more) values.
5078 This lookup is done by a linear search and can be expensive with large lists!
5079 It is the equivalent of the "add acl" command from the stats socket, but can
5080 be triggered by an HTTP response.
Sasha Pachev218f0642014-06-16 12:05:59 -06005081
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005082http-response add-header <name> <fmt> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005083
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005084 This appends an HTTP header field whose name is specified in <name> and whose
5085 value is defined by <fmt> which follows the log-format rules (see Custom Log
5086 Format in section 8.2.4). This may be used to send a cookie to a client for
5087 example, or to pass some internal information.
5088 This rule is not final, so it is possible to add other similar rules.
5089 Note that header addition is performed immediately, so one rule might reuse
5090 the resulting header from a previous rule.
Sasha Pachev218f0642014-06-16 12:05:59 -06005091
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005092http-response allow [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005093
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005094 This stops the evaluation of the rules and lets the response pass the check.
5095 No further "http-response" rules are evaluated for the current section.
Sasha Pachev218f0642014-06-16 12:05:59 -06005096
Jarno Huuskonen251a6b72019-01-04 14:05:02 +02005097http-response cache-store <name> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005098
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005099 See section 10.2 about cache setup.
Sasha Pachev218f0642014-06-16 12:05:59 -06005100
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005101http-response capture <sample> id <id> [ { if | unless } <condition> ]
Sasha Pachev218f0642014-06-16 12:05:59 -06005102
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005103 This captures sample expression <sample> from the response buffer, and
5104 converts it to a string. The resulting string is stored into the next request
5105 "capture" slot, so it will possibly appear next to some captured HTTP
5106 headers. It will then automatically appear in the logs, and it will be
5107 possible to extract it using sample fetch rules to feed it into headers or
5108 anything. Please check section 7.3 (Fetching samples) and
5109 "capture response header" for more information.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02005110
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005111 The keyword "id" is the id of the capture slot which is used for storing the
5112 string. The capture slot must be defined in an associated frontend.
5113 This is useful to run captures in backends. The slot id can be declared by a
5114 previous directive "http-response capture" or with the "declare capture"
5115 keyword.
Baptiste Assmann63b220d2020-01-16 14:34:22 +01005116
5117 When using this action in a backend, double check that the relevant
5118 frontend(s) have the required capture slots otherwise, this rule will be
5119 ignored at run time. This can't be detected at configuration parsing time
5120 due to HAProxy's ability to dynamically resolve backend name at runtime.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02005121
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005122http-response del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02005123
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005124 This is used to delete an entry from an ACL. The ACL must be loaded from a
5125 file (even a dummy empty file). The file name of the ACL to be updated is
5126 passed between parentheses. It takes one argument: <key fmt>, which follows
5127 log-format rules, to collect content of the entry to delete.
5128 It is the equivalent of the "del acl" command from the stats socket, but can
5129 be triggered by an HTTP response.
Willy Tarreauf4c43c12013-06-11 17:01:13 +02005130
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005131http-response del-header <name> [ { if | unless } <condition> ]
Willy Tarreau9a355ec2013-06-11 17:45:46 +02005132
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005133 This removes all HTTP header fields whose name is specified in <name>.
Willy Tarreau42cf39e2013-06-11 18:51:32 +02005134
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005135http-response del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
Willy Tarreau51347ed2013-06-11 19:34:13 +02005136
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005137 This is used to delete an entry from a MAP. The MAP must be loaded from a
5138 file (even a dummy empty file). The file name of the MAP to be updated is
5139 passed between parentheses. It takes one argument: <key fmt>, which follows
5140 log-format rules, to collect content of the entry to delete.
5141 It takes one argument: "file name" It is the equivalent of the "del map"
5142 command from the stats socket, but can be triggered by an HTTP response.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005143
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005144http-response deny [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005145
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005146 This stops the evaluation of the rules and immediately rejects the response
5147 and emits an HTTP 502 error. No further "http-response" rules are evaluated.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005148
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005149http-response redirect <rule> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005150
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005151 This performs an HTTP redirection based on a redirect rule.
5152 This supports a format string similarly to "http-request redirect" rules,
5153 with the exception that only the "location" type of redirect is possible on
5154 the response. See the "redirect" keyword for the rule's syntax. When a
5155 redirect rule is applied during a response, connections to the server are
5156 closed so that no data can be forwarded from the server to the client.
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02005157
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005158http-response replace-header <name> <regex-match> <replace-fmt>
5159 [ { if | unless } <condition> ]
Thierry FOURNIERe80fada2015-05-26 18:06:31 +02005160
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01005161 This works like "http-request replace-header" except that it works on the
5162 server's response instead of the client's request.
William Lallemand86d0df02017-11-24 21:36:45 +01005163
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005164 Example:
5165 http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2
Willy Tarreau51d861a2015-05-22 17:30:48 +02005166
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005167 # applied to:
5168 Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005169
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005170 # outputs:
5171 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 +02005172
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005173 # assuming the backend IP is 192.168.1.20.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005174
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005175http-response replace-value <name> <regex-match> <replace-fmt>
5176 [ { if | unless } <condition> ]
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005177
Tim Duesterhus2f7045c2019-10-29 00:05:13 +01005178 This works like "http-response replace-value" except that it works on the
5179 server's response instead of the client's request.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +02005180
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005181 Example:
5182 http-response replace-value Cache-control ^public$ private
Christopher Faulet85d79c92016-11-09 16:54:56 +01005183
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005184 # applied to:
5185 Cache-Control: max-age=3600, public
Christopher Faulet85d79c92016-11-09 16:54:56 +01005186
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005187 # outputs:
5188 Cache-Control: max-age=3600, private
Christopher Faulet85d79c92016-11-09 16:54:56 +01005189
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005190http-response sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
5191http-response sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
Ruoshan Huange4edc6b2016-07-14 15:07:45 +08005192
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005193 This action increments the GPC0 or GPC1 counter according with the sticky
5194 counter designated by <sc-id>. If an error occurs, this action silently fails
5195 and the actions evaluation continues.
Thierry FOURNIER236657b2015-08-19 08:25:14 +02005196
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005197http-response sc-set-gpt0(<sc-id>) <int> [ { if | unless } <condition> ]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +02005198
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005199 This action sets the GPT0 tag according to the sticky counter designated by
5200 <sc-id> and the value of <int>. The expected result is a boolean. If an error
5201 occurs, this action silently fails and the actions evaluation continues.
Frédéric Lécaille6778b272018-01-29 15:22:53 +01005202
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005203http-response send-spoe-group [ { if | unless } <condition> ]
Willy Tarreau2d392c22015-08-24 01:43:45 +02005204
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005205 This action is used to trigger sending of a group of SPOE messages. To do so,
5206 the SPOE engine used to send messages must be defined, as well as the SPOE
5207 group to send. Of course, the SPOE engine must refer to an existing SPOE
5208 filter. If not engine name is provided on the SPOE filter line, the SPOE
5209 agent name must be used.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005210
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005211 Arguments:
5212 <engine-name> The SPOE engine name.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005213
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005214 <group-name> The SPOE group name as specified in the engine
5215 configuration.
Christopher Faulet76c09ef2017-09-21 11:03:52 +02005216
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005217http-response set-header <name> <fmt> [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005218
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005219 This does the same as "add-header" except that the header name is first
5220 removed if it existed. This is useful when passing security information to
5221 the server, where the header must not be manipulated by external users.
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005222
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005223http-response set-log-level <level> [ { if | unless } <condition> ]
5224
5225 This is used to change the log level of the current request when a certain
5226 condition is met. Valid levels are the 8 syslog levels (see the "log"
5227 keyword) plus the special level "silent" which disables logging for this
5228 request. This rule is not final so the last matching rule wins. This rule can
5229 be useful to disable health checks coming from another equipment.
5230
5231http-response set-map(<file-name>) <key fmt> <value fmt>
5232
5233 This is used to add a new entry into a MAP. The MAP must be loaded from a
5234 file (even a dummy empty file). The file name of the MAP to be updated is
5235 passed between parentheses. It takes 2 arguments: <key fmt>, which follows
5236 log-format rules, used to collect MAP key, and <value fmt>, which follows
5237 log-format rules, used to collect content for the new entry. It performs a
5238 lookup in the MAP before insertion, to avoid duplicated (or more) values.
5239 This lookup is done by a linear search and can be expensive with large lists!
5240 It is the equivalent of the "set map" command from the stats socket, but can
5241 be triggered by an HTTP response.
5242
5243http-response set-mark <mark> [ { if | unless } <condition> ]
5244
5245 This is used to set the Netfilter MARK on all packets sent to the client to
5246 the value passed in <mark> on platforms which support it. This value is an
5247 unsigned 32 bit value which can be matched by netfilter and by the routing
5248 table. It can be expressed both in decimal or hexadecimal format (prefixed
5249 by "0x"). This can be useful to force certain packets to take a different
5250 route (for example a cheaper network path for bulk downloads). This works on
5251 Linux kernels 2.6.32 and above and requires admin privileges.
5252
5253http-response set-nice <nice> [ { if | unless } <condition> ]
5254
5255 This sets the "nice" factor of the current request being processed.
5256 It only has effect against the other requests being processed at the same
5257 time. The default value is 0, unless altered by the "nice" setting on the
5258 "bind" line. The accepted range is -1024..1024. The higher the value, the
5259 nicest the request will be. Lower values will make the request more important
5260 than other ones. This can be useful to improve the speed of some requests, or
5261 lower the priority of non-important requests. Using this setting without
5262 prior experimentation can cause some major slowdown.
5263
5264http-response set-status <status> [reason <str>]
5265 [ { if | unless } <condition> ]
5266
5267 This replaces the response status code with <status> which must be an integer
5268 between 100 and 999. Optionally, a custom reason text can be provided defined
5269 by <str>, or the default reason for the specified code will be used as a
5270 fallback.
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08005271
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005272 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005273 # return "431 Request Header Fields Too Large"
5274 http-response set-status 431
5275 # return "503 Slow Down", custom reason
5276 http-response set-status 503 reason "Slow Down".
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005277
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005278http-response set-tos <tos> [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005279
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005280 This is used to set the TOS or DSCP field value of packets sent to the client
5281 to the value passed in <tos> on platforms which support this.
5282 This value represents the whole 8 bits of the IP TOS field, and can be
5283 expressed both in decimal or hexadecimal format (prefixed by "0x"). Note that
5284 only the 6 higher bits are used in DSCP or TOS, and the two lower bits are
5285 always 0. This can be used to adjust some routing behavior on border routers
5286 based on some information from the request.
5287
5288 See RFC 2474, 2597, 3260 and 4594 for more information.
5289
5290http-response set-var(<var-name>) <expr> [ { if | unless } <condition> ]
5291
5292 This is used to set the contents of a variable. The variable is declared
5293 inline.
5294
5295 Arguments:
5296 <var-name> The name of the variable starts with an indication about its
5297 scope. The scopes allowed are:
5298 "proc" : the variable is shared with the whole process
5299 "sess" : the variable is shared with the whole session
5300 "txn" : the variable is shared with the transaction
5301 (request and response)
5302 "req" : the variable is shared only during request
5303 processing
5304 "res" : the variable is shared only during response
5305 processing
5306 This prefix is followed by a name. The separator is a '.'.
5307 The name may only contain characters 'a-z', 'A-Z', '0-9', '.'
5308 and '_'.
5309
5310 <expr> Is a standard HAProxy expression formed by a sample-fetch
5311 followed by some converters.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005312
5313 Example:
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005314 http-response set-var(sess.last_redir) res.hdr(location)
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005315
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005316http-response silent-drop [ { if | unless } <condition> ]
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005317
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005318 This stops the evaluation of the rules and makes the client-facing connection
5319 suddenly disappear using a system-dependent way that tries to prevent the
5320 client from being notified. The effect it then that the client still sees an
5321 established connection while there's none on HAProxy. The purpose is to
5322 achieve a comparable effect to "tarpit" except that it doesn't use any local
5323 resource at all on the machine running HAProxy. It can resist much higher
5324 loads than "tarpit", and slow down stronger attackers. It is important to
5325 understand the impact of using this mechanism. All stateful equipment placed
5326 between the client and HAProxy (firewalls, proxies, load balancers) will also
5327 keep the established connection for a long time and may suffer from this
5328 action.
5329 On modern Linux systems running with enough privileges, the TCP_REPAIR socket
5330 option is used to block the emission of a TCP reset. On other systems, the
5331 socket's TTL is reduced to 1 so that the TCP reset doesn't pass the first
5332 router, though it's still delivered to local networks. Do not use it unless
5333 you fully understand how it works.
Baptiste Assmannfabcbe02014-04-24 22:16:59 +02005334
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005335http-response track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
5336http-response track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
5337http-response track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
Willy Tarreaue365c0b2013-06-11 16:06:12 +02005338
Cyril Bonté6c81d5f2018-10-17 00:14:51 +02005339 This enables tracking of sticky counters from current response. Please refer
5340 to "http-request track-sc" for a complete description. The only difference
5341 from "http-request track-sc" is the <key> sample expression can only make use
5342 of samples in response (e.g. res.*, status etc.) and samples below Layer 6
5343 (e.g. SSL-related samples, see section 7.3.4). If the sample is not
5344 supported, haproxy will fail and warn while parsing the config.
5345
5346http-response unset-var(<var-name>) [ { if | unless } <condition> ]
5347
5348 This is used to unset a variable. See "http-response set-var" for details
5349 about <var-name>.
5350
5351 Example:
5352 http-response unset-var(sess.last_redir)
5353
Baptiste Assmann5ecb77f2013-10-06 23:24:13 +02005354
Willy Tarreau30631952015-08-06 15:05:24 +02005355http-reuse { never | safe | aggressive | always }
5356 Declare how idle HTTP connections may be shared between requests
5357
5358 May be used in sections: defaults | frontend | listen | backend
5359 yes | no | yes | yes
5360
5361 By default, a connection established between haproxy and the backend server
Olivier Houchard86006a52018-12-14 19:37:49 +01005362 which is considered safe for reuse is moved back to the server's idle
5363 connections pool so that any other request can make use of it. This is the
5364 "safe" strategy below.
Willy Tarreau30631952015-08-06 15:05:24 +02005365
5366 The argument indicates the desired connection reuse strategy :
5367
Olivier Houchard86006a52018-12-14 19:37:49 +01005368 - "never" : idle connections are never shared between sessions. This mode
5369 may be enforced to cancel a different strategy inherited from
5370 a defaults section or for troubleshooting. For example, if an
5371 old bogus application considers that multiple requests over
5372 the same connection come from the same client and it is not
5373 possible to fix the application, it may be desirable to
5374 disable connection sharing in a single backend. An example of
5375 such an application could be an old haproxy using cookie
5376 insertion in tunnel mode and not checking any request past the
5377 first one.
Willy Tarreau30631952015-08-06 15:05:24 +02005378
Olivier Houchard86006a52018-12-14 19:37:49 +01005379 - "safe" : this is the default and the recommended strategy. The first
5380 request of a session is always sent over its own connection,
5381 and only subsequent requests may be dispatched over other
5382 existing connections. This ensures that in case the server
5383 closes the connection when the request is being sent, the
5384 browser can decide to silently retry it. Since it is exactly
5385 equivalent to regular keep-alive, there should be no side
5386 effects.
Willy Tarreau30631952015-08-06 15:05:24 +02005387
5388 - "aggressive" : this mode may be useful in webservices environments where
5389 all servers are not necessarily known and where it would be
5390 appreciable to deliver most first requests over existing
5391 connections. In this case, first requests are only delivered
5392 over existing connections that have been reused at least once,
5393 proving that the server correctly supports connection reuse.
5394 It should only be used when it's sure that the client can
5395 retry a failed request once in a while and where the benefit
Michael Prokop4438c602019-05-24 10:25:45 +02005396 of aggressive connection reuse significantly outweighs the
Willy Tarreau30631952015-08-06 15:05:24 +02005397 downsides of rare connection failures.
5398
5399 - "always" : this mode is only recommended when the path to the server is
5400 known for never breaking existing connections quickly after
5401 releasing them. It allows the first request of a session to be
5402 sent to an existing connection. This can provide a significant
5403 performance increase over the "safe" strategy when the backend
5404 is a cache farm, since such components tend to show a
Davor Ocelice9ed2812017-12-25 17:49:28 +01005405 consistent behavior and will benefit from the connection
Willy Tarreau30631952015-08-06 15:05:24 +02005406 sharing. It is recommended that the "http-keep-alive" timeout
5407 remains low in this mode so that no dead connections remain
5408 usable. In most cases, this will lead to the same performance
5409 gains as "aggressive" but with more risks. It should only be
5410 used when it improves the situation over "aggressive".
5411
5412 When http connection sharing is enabled, a great care is taken to respect the
Davor Ocelice9ed2812017-12-25 17:49:28 +01005413 connection properties and compatibility. Specifically :
5414 - connections made with "usesrc" followed by a client-dependent value
5415 ("client", "clientip", "hdr_ip") are marked private and never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02005416
5417 - connections sent to a server with a TLS SNI extension are marked private
Davor Ocelice9ed2812017-12-25 17:49:28 +01005418 and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02005419
Lukas Tribusfd9b68c2018-10-27 20:06:59 +02005420 - connections with certain bogus authentication schemes (relying on the
5421 connection) like NTLM are detected, marked private and are never shared;
Willy Tarreau30631952015-08-06 15:05:24 +02005422
Lukas Tribus79a56932019-11-06 11:50:25 +01005423 A connection pool is involved and configurable with "pool-max-conn".
Willy Tarreau30631952015-08-06 15:05:24 +02005424
5425 Note: connection reuse improves the accuracy of the "server maxconn" setting,
5426 because almost no new connection will be established while idle connections
5427 remain available. This is particularly true with the "always" strategy.
5428
5429 See also : "option http-keep-alive", "server maxconn"
5430
5431
Mark Lamourinec2247f02012-01-04 13:02:01 -05005432http-send-name-header [<header>]
5433 Add the server name to a request. Use the header string given by <header>
Mark Lamourinec2247f02012-01-04 13:02:01 -05005434 May be used in sections: defaults | frontend | listen | backend
5435 yes | no | yes | yes
Mark Lamourinec2247f02012-01-04 13:02:01 -05005436 Arguments :
Mark Lamourinec2247f02012-01-04 13:02:01 -05005437 <header> The header string to use to send the server name
5438
Willy Tarreaue0e32792019-10-07 14:58:02 +02005439 The "http-send-name-header" statement causes the header field named <header>
5440 to be set to the name of the target server at the moment the request is about
5441 to be sent on the wire. Any existing occurrences of this header are removed.
5442 Upon retries and redispatches, the header field is updated to always reflect
5443 the server being attempted to connect to. Given that this header is modified
5444 very late in the connection setup, it may have unexpected effects on already
5445 modified headers. For example using it with transport-level header such as
5446 connection, content-length, transfer-encoding and so on will likely result in
5447 invalid requests being sent to the server. Additionally it has been reported
5448 that this directive is currently being used as a way to overwrite the Host
5449 header field in outgoing requests; while this trick has been known to work
5450 as a side effect of the feature for some time, it is not officially supported
5451 and might possibly not work anymore in a future version depending on the
5452 technical difficulties this feature induces. A long-term solution instead
5453 consists in fixing the application which required this trick so that it binds
5454 to the correct host name.
Mark Lamourinec2247f02012-01-04 13:02:01 -05005455
5456 See also : "server"
5457
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01005458id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +02005459 Set a persistent ID to a proxy.
5460 May be used in sections : defaults | frontend | listen | backend
5461 no | yes | yes | yes
5462 Arguments : none
5463
5464 Set a persistent ID for the proxy. This ID must be unique and positive.
5465 An unused ID will automatically be assigned if unset. The first assigned
5466 value will be 1. This ID is currently only returned in statistics.
Krzysztof Piotr Oledzkif58a9622008-02-23 01:19:10 +01005467
5468
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005469ignore-persist { if | unless } <condition>
5470 Declare a condition to ignore persistence
5471 May be used in sections: defaults | frontend | listen | backend
Cyril Bonté4288c5a2018-03-12 22:02:59 +01005472 no | no | yes | yes
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005473
5474 By default, when cookie persistence is enabled, every requests containing
5475 the cookie are unconditionally persistent (assuming the target server is up
5476 and running).
5477
5478 The "ignore-persist" statement allows one to declare various ACL-based
5479 conditions which, when met, will cause a request to ignore persistence.
5480 This is sometimes useful to load balance requests for static files, which
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03005481 often don't require persistence. This can also be used to fully disable
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005482 persistence for a specific User-Agent (for example, some web crawler bots).
5483
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005484 The persistence is ignored when an "if" condition is met, or unless an
5485 "unless" condition is met.
5486
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03005487 Example:
5488 acl url_static path_beg /static /images /img /css
5489 acl url_static path_end .gif .png .jpg .css .js
5490 ignore-persist if url_static
5491
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005492 See also : "force-persist", "cookie", and section 7 about ACL usage.
5493
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005494load-server-state-from-file { global | local | none }
5495 Allow seamless reload of HAProxy
5496 May be used in sections: defaults | frontend | listen | backend
5497 yes | no | yes | yes
5498
5499 This directive points HAProxy to a file where server state from previous
5500 running process has been saved. That way, when starting up, before handling
5501 traffic, the new process can apply old states to servers exactly has if no
Davor Ocelice9ed2812017-12-25 17:49:28 +01005502 reload occurred. The purpose of the "load-server-state-from-file" directive is
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005503 to tell haproxy which file to use. For now, only 2 arguments to either prevent
5504 loading state or load states from a file containing all backends and servers.
5505 The state file can be generated by running the command "show servers state"
5506 over the stats socket and redirect output.
5507
Davor Ocelice9ed2812017-12-25 17:49:28 +01005508 The format of the file is versioned and is very specific. To understand it,
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005509 please read the documentation of the "show servers state" command (chapter
Willy Tarreau1af20c72017-06-23 16:01:14 +02005510 9.3 of Management Guide).
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005511
5512 Arguments:
5513 global load the content of the file pointed by the global directive
5514 named "server-state-file".
5515
5516 local load the content of the file pointed by the directive
5517 "server-state-file-name" if set. If not set, then the backend
5518 name is used as a file name.
5519
5520 none don't load any stat for this backend
5521
5522 Notes:
Willy Tarreaue5a60682016-11-09 14:54:53 +01005523 - server's IP address is preserved across reloads by default, but the
5524 order can be changed thanks to the server's "init-addr" setting. This
5525 means that an IP address change performed on the CLI at run time will
Davor Ocelice9ed2812017-12-25 17:49:28 +01005526 be preserved, and that any change to the local resolver (e.g. /etc/hosts)
Willy Tarreaue5a60682016-11-09 14:54:53 +01005527 will possibly not have any effect if the state file is in use.
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005528
5529 - server's weight is applied from previous running process unless it has
5530 has changed between previous and new configuration files.
5531
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005532 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005533
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005534 global
5535 stats socket /tmp/socket
5536 server-state-file /tmp/server_state
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005537
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005538 defaults
5539 load-server-state-from-file global
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005540
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005541 backend bk
5542 server s1 127.0.0.1:22 check weight 11
5543 server s2 127.0.0.1:22 check weight 12
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005544
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005545
5546 Then one can run :
5547
5548 socat /tmp/socket - <<< "show servers state" > /tmp/server_state
5549
5550 Content of the file /tmp/server_state would be like this:
5551
5552 1
5553 # <field names skipped for the doc example>
5554 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
5555 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
5556
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005557 Example: Minimal configuration
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005558
5559 global
5560 stats socket /tmp/socket
5561 server-state-base /etc/haproxy/states
5562
5563 defaults
5564 load-server-state-from-file local
5565
5566 backend bk
5567 server s1 127.0.0.1:22 check weight 11
5568 server s2 127.0.0.1:22 check weight 12
5569
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02005570
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02005571 Then one can run :
5572
5573 socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk
5574
5575 Content of the file /etc/haproxy/states/bk would be like this:
5576
5577 1
5578 # <field names skipped for the doc example>
5579 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0
5580 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0
5581
5582 See also: "server-state-file", "server-state-file-name", and
5583 "show servers state"
5584
Cyril Bonté0d4bf012010-04-25 23:21:46 +02005585
Willy Tarreau2769aa02007-12-27 18:26:09 +01005586log global
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02005587log <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>]
5588 <facility> [<level> [<minlevel>]]
William Lallemand0f99e342011-10-12 17:50:54 +02005589no log
Willy Tarreau2769aa02007-12-27 18:26:09 +01005590 Enable per-instance logging of events and traffic.
5591 May be used in sections : defaults | frontend | listen | backend
5592 yes | yes | yes | yes
William Lallemand0f99e342011-10-12 17:50:54 +02005593
5594 Prefix :
5595 no should be used when the logger list must be flushed. For example,
5596 if you don't want to inherit from the default logger list. This
5597 prefix does not allow arguments.
5598
Willy Tarreau2769aa02007-12-27 18:26:09 +01005599 Arguments :
5600 global should be used when the instance's logging parameters are the
5601 same as the global ones. This is the most common usage. "global"
5602 replaces <address>, <facility> and <level> with those of the log
5603 entries found in the "global" section. Only one "log global"
5604 statement may be used per instance, and this form takes no other
5605 parameter.
5606
5607 <address> indicates where to send the logs. It takes the same format as
5608 for the "global" section's logs, and can be one of :
5609
5610 - An IPv4 address optionally followed by a colon (':') and a UDP
5611 port. If no port is specified, 514 is used by default (the
5612 standard syslog port).
5613
David du Colombier24bb5f52011-03-17 10:40:23 +01005614 - An IPv6 address followed by a colon (':') and optionally a UDP
5615 port. If no port is specified, 514 is used by default (the
5616 standard syslog port).
5617
Willy Tarreau2769aa02007-12-27 18:26:09 +01005618 - A filesystem path to a UNIX domain socket, keeping in mind
5619 considerations for chroot (be sure the path is accessible
5620 inside the chroot) and uid/gid (be sure the path is
Davor Ocelice9ed2812017-12-25 17:49:28 +01005621 appropriately writable).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005622
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01005623 - A file descriptor number in the form "fd@<number>", which may
5624 point to a pipe, terminal, or socket. In this case unbuffered
5625 logs are used and one writev() call per log is performed. This
5626 is a bit expensive but acceptable for most workloads. Messages
5627 sent this way will not be truncated but may be dropped, in
5628 which case the DroppedLogs counter will be incremented. The
5629 writev() call is atomic even on pipes for messages up to
5630 PIPE_BUF size, which POSIX recommends to be at least 512 and
5631 which is 4096 bytes on most modern operating systems. Any
5632 larger message may be interleaved with messages from other
5633 processes. Exceptionally for debugging purposes the file
5634 descriptor may also be directed to a file, but doing so will
5635 significantly slow haproxy down as non-blocking calls will be
5636 ignored. Also there will be no way to purge nor rotate this
5637 file without restarting the process. Note that the configured
5638 syslog format is preserved, so the output is suitable for use
Willy Tarreauc1b06452018-11-12 11:57:56 +01005639 with a TCP syslog server. See also the "short" and "raw"
5640 formats below.
Willy Tarreau5a32ecc2018-11-12 07:34:59 +01005641
5642 - "stdout" / "stderr", which are respectively aliases for "fd@1"
5643 and "fd@2", see above.
5644
5645 You may want to reference some environment variables in the
5646 address parameter, see section 2.3 about environment variables.
Willy Tarreaudad36a32013-03-11 01:20:04 +01005647
Willy Tarreau18324f52014-06-27 18:10:07 +02005648 <length> is an optional maximum line length. Log lines larger than this
5649 value will be truncated before being sent. The reason is that
5650 syslog servers act differently on log line length. All servers
5651 support the default value of 1024, but some servers simply drop
5652 larger lines while others do log them. If a server supports long
5653 lines, it may make sense to set this value here in order to avoid
5654 truncating long lines. Similarly, if a server drops long lines,
5655 it is preferable to truncate them before sending them. Accepted
5656 values are 80 to 65535 inclusive. The default value of 1024 is
5657 generally fine for all standard usages. Some specific cases of
Davor Ocelice9ed2812017-12-25 17:49:28 +01005658 long captures or JSON-formatted logs may require larger values.
Willy Tarreau18324f52014-06-27 18:10:07 +02005659
Frédéric Lécailled690dfa2019-04-25 10:52:17 +02005660 <ranges> A list of comma-separated ranges to identify the logs to sample.
5661 This is used to balance the load of the logs to send to the log
5662 server. The limits of the ranges cannot be null. They are numbered
5663 from 1. The size or period (in number of logs) of the sample must
5664 be set with <sample_size> parameter.
5665
5666 <sample_size>
5667 The size of the sample in number of logs to consider when balancing
5668 their logging loads. It is used to balance the load of the logs to
5669 send to the syslog server. This size must be greater or equal to the
5670 maximum of the high limits of the ranges.
5671 (see also <ranges> parameter).
5672
Willy Tarreauadb345d2018-11-12 07:56:13 +01005673 <format> is the log format used when generating syslog messages. It may be
5674 one of the following :
5675
5676 rfc3164 The RFC3164 syslog message format. This is the default.
5677 (https://tools.ietf.org/html/rfc3164)
5678
5679 rfc5424 The RFC5424 syslog message format.
5680 (https://tools.ietf.org/html/rfc5424)
5681
Willy Tarreaue8746a02018-11-12 08:45:00 +01005682 short A message containing only a level between angle brackets such as
5683 '<3>', followed by the text. The PID, date, time, process name
5684 and system name are omitted. This is designed to be used with a
5685 local log server. This format is compatible with what the
5686 systemd logger consumes.
5687
Willy Tarreauc1b06452018-11-12 11:57:56 +01005688 raw A message containing only the text. The level, PID, date, time,
5689 process name and system name are omitted. This is designed to
5690 be used in containers or during development, where the severity
5691 only depends on the file descriptor used (stdout/stderr).
5692
Willy Tarreau2769aa02007-12-27 18:26:09 +01005693 <facility> must be one of the 24 standard syslog facilities :
5694
Willy Tarreaue8746a02018-11-12 08:45:00 +01005695 kern user mail daemon auth syslog lpr news
5696 uucp cron auth2 ftp ntp audit alert cron2
5697 local0 local1 local2 local3 local4 local5 local6 local7
5698
Willy Tarreauc1b06452018-11-12 11:57:56 +01005699 Note that the facility is ignored for the "short" and "raw"
5700 formats, but still required as a positional field. It is
5701 recommended to use "daemon" in this case to make it clear that
5702 it's only supposed to be used locally.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005703
5704 <level> is optional and can be specified to filter outgoing messages. By
5705 default, all messages are sent. If a level is specified, only
5706 messages with a severity at least as important as this level
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005707 will be sent. An optional minimum level can be specified. If it
5708 is set, logs emitted with a more severe level than this one will
5709 be capped to this level. This is used to avoid sending "emerg"
5710 messages on all terminals on some default syslog configurations.
5711 Eight levels are known :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005712
5713 emerg alert crit err warning notice info debug
5714
William Lallemand0f99e342011-10-12 17:50:54 +02005715 It is important to keep in mind that it is the frontend which decides what to
5716 log from a connection, and that in case of content switching, the log entries
5717 from the backend will be ignored. Connections are logged at level "info".
Willy Tarreaucc6c8912009-02-22 10:53:55 +01005718
5719 However, backend log declaration define how and where servers status changes
5720 will be logged. Level "notice" will be used to indicate a server going up,
5721 "warning" will be used for termination signals and definitive service
5722 termination, and "alert" will be used for when a server goes down.
5723
5724 Note : According to RFC3164, messages are truncated to 1024 bytes before
5725 being emitted.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005726
5727 Example :
5728 log global
Willy Tarreauc1b06452018-11-12 11:57:56 +01005729 log stdout format short daemon # send log to systemd
5730 log stdout format raw daemon # send everything to stdout
5731 log stderr format raw daemon notice # send important events to stderr
Willy Tarreauf7edefa2009-05-10 17:20:05 +02005732 log 127.0.0.1:514 local0 notice # only send important events
5733 log 127.0.0.1:514 local0 notice notice # same but limit output level
William Lallemandb2f07452015-05-12 14:27:13 +02005734 log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
Willy Tarreaudad36a32013-03-11 01:20:04 +01005735
Willy Tarreau2769aa02007-12-27 18:26:09 +01005736
William Lallemand48940402012-01-30 16:47:22 +01005737log-format <string>
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005738 Specifies the log format string to use for traffic logs
5739 May be used in sections: defaults | frontend | listen | backend
5740 yes | yes | yes | no
William Lallemand48940402012-01-30 16:47:22 +01005741
Willy Tarreaufb4e7ea2015-01-07 14:55:17 +01005742 This directive specifies the log format string that will be used for all logs
5743 resulting from traffic passing through the frontend using this line. If the
5744 directive is used in a defaults section, all subsequent frontends will use
5745 the same log format. Please see section 8.2.4 which covers the log format
5746 string in depth.
William Lallemand48940402012-01-30 16:47:22 +01005747
Guillaume de Lafond29f45602017-03-31 19:52:15 +02005748 "log-format" directive overrides previous "option tcplog", "log-format" and
5749 "option httplog" directives.
5750
Dragan Dosen7ad31542015-09-28 17:16:47 +02005751log-format-sd <string>
5752 Specifies the RFC5424 structured-data log format string
5753 May be used in sections: defaults | frontend | listen | backend
5754 yes | yes | yes | no
5755
5756 This directive specifies the RFC5424 structured-data log format string that
5757 will be used for all logs resulting from traffic passing through the frontend
5758 using this line. If the directive is used in a defaults section, all
5759 subsequent frontends will use the same log format. Please see section 8.2.4
5760 which covers the log format string in depth.
5761
5762 See https://tools.ietf.org/html/rfc5424#section-6.3 for more information
5763 about the RFC5424 structured-data part.
5764
5765 Note : This log format string will be used only for loggers that have set
5766 log format to "rfc5424".
5767
5768 Example :
5769 log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"]
5770
5771
Willy Tarreau094af4e2015-01-07 15:03:42 +01005772log-tag <string>
5773 Specifies the log tag to use for all outgoing logs
5774 May be used in sections: defaults | frontend | listen | backend
5775 yes | yes | yes | yes
5776
5777 Sets the tag field in the syslog header to this string. It defaults to the
5778 log-tag set in the global section, otherwise the program name as launched
5779 from the command line, which usually is "haproxy". Sometimes it can be useful
5780 to differentiate between multiple processes running on the same host, or to
5781 differentiate customer instances running in the same process. In the backend,
5782 logs about servers up/down will use this tag. As a hint, it can be convenient
5783 to set a log-tag related to a hosted customer in a defaults section then put
5784 all the frontends and backends for that customer, then start another customer
5785 in a new defaults section. See also the global "log-tag" directive.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005786
Willy Tarreauc35362a2014-04-25 13:58:37 +02005787max-keep-alive-queue <value>
5788 Set the maximum server queue size for maintaining keep-alive connections
5789 May be used in sections: defaults | frontend | listen | backend
5790 yes | no | yes | yes
5791
5792 HTTP keep-alive tries to reuse the same server connection whenever possible,
5793 but sometimes it can be counter-productive, for example if a server has a lot
5794 of connections while other ones are idle. This is especially true for static
5795 servers.
5796
5797 The purpose of this setting is to set a threshold on the number of queued
5798 connections at which haproxy stops trying to reuse the same server and prefers
5799 to find another one. The default value, -1, means there is no limit. A value
5800 of zero means that keep-alive requests will never be queued. For very close
5801 servers which can be reached with a low latency and which are not sensible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01005802 breaking keep-alive, a low value is recommended (e.g. local static server can
Willy Tarreauc35362a2014-04-25 13:58:37 +02005803 use a value of 10 or less). For remote servers suffering from a high latency,
5804 higher values might be needed to cover for the latency and/or the cost of
5805 picking a different server.
5806
5807 Note that this has no impact on responses which are maintained to the same
5808 server consecutively to a 401 response. They will still go to the same server
5809 even if they have to be queued.
5810
5811 See also : "option http-server-close", "option prefer-last-server", server
5812 "maxconn" and cookie persistence.
5813
Olivier Houcharda4d4fdf2018-12-14 19:27:06 +01005814max-session-srv-conns <nb>
5815 Set the maximum number of outgoing connections we can keep idling for a given
5816 client session. The default is 5 (it precisely equals MAX_SRV_LIST which is
5817 defined at build time).
Willy Tarreauc35362a2014-04-25 13:58:37 +02005818
Willy Tarreau2769aa02007-12-27 18:26:09 +01005819maxconn <conns>
5820 Fix the maximum number of concurrent connections on a frontend
5821 May be used in sections : defaults | frontend | listen | backend
5822 yes | yes | yes | no
5823 Arguments :
5824 <conns> is the maximum number of concurrent connections the frontend will
5825 accept to serve. Excess connections will be queued by the system
5826 in the socket's listen queue and will be served once a connection
5827 closes.
5828
5829 If the system supports it, it can be useful on big sites to raise this limit
5830 very high so that haproxy manages connection queues, instead of leaving the
5831 clients with unanswered connection attempts. This value should not exceed the
5832 global maxconn. Also, keep in mind that a connection contains two buffers
Baptiste Assmann79fb45d2016-03-06 23:34:31 +01005833 of tune.bufsize (16kB by default) each, as well as some other data resulting
5834 in about 33 kB of RAM being consumed per established connection. That means
5835 that a medium system equipped with 1GB of RAM can withstand around
5836 20000-25000 concurrent connections if properly tuned.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005837
5838 Also, when <conns> is set to large values, it is possible that the servers
5839 are not sized to accept such loads, and for this reason it is generally wise
5840 to assign them some reasonable connection limits.
5841
Willy Tarreauc8d5b952019-02-27 17:25:52 +01005842 When this value is set to zero, which is the default, the global "maxconn"
5843 value is used.
Vincent Bernat6341be52012-06-27 17:18:30 +02005844
Willy Tarreau2769aa02007-12-27 18:26:09 +01005845 See also : "server", global section's "maxconn", "fullconn"
5846
5847
5848mode { tcp|http|health }
5849 Set the running mode or protocol of the instance
5850 May be used in sections : defaults | frontend | listen | backend
5851 yes | yes | yes | yes
5852 Arguments :
5853 tcp The instance will work in pure TCP mode. A full-duplex connection
5854 will be established between clients and servers, and no layer 7
5855 examination will be performed. This is the default mode. It
5856 should be used for SSL, SSH, SMTP, ...
5857
5858 http The instance will work in HTTP mode. The client request will be
5859 analyzed in depth before connecting to any server. Any request
5860 which is not RFC-compliant will be rejected. Layer 7 filtering,
5861 processing and switching will be possible. This is the mode which
5862 brings HAProxy most of its value.
5863
5864 health The instance will work in "health" mode. It will just reply "OK"
Willy Tarreau82569f92012-09-27 23:48:56 +02005865 to incoming connections and close the connection. Alternatively,
5866 If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent
5867 instead. Nothing will be logged in either case. This mode is used
5868 to reply to external components health checks. This mode is
5869 deprecated and should not be used anymore as it is possible to do
5870 the same and even better by combining TCP or HTTP modes with the
5871 "monitor" keyword.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005872
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005873 When doing content switching, it is mandatory that the frontend and the
5874 backend are in the same mode (generally HTTP), otherwise the configuration
5875 will be refused.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005876
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005877 Example :
Willy Tarreau2769aa02007-12-27 18:26:09 +01005878 defaults http_instances
5879 mode http
5880
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005881 See also : "monitor", "monitor-net"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005882
Willy Tarreau0ba27502007-12-24 16:55:16 +01005883
Cyril Bontéf0c60612010-02-06 14:44:47 +01005884monitor fail { if | unless } <condition>
Willy Tarreau2769aa02007-12-27 18:26:09 +01005885 Add a condition to report a failure to a monitor HTTP request.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005886 May be used in sections : defaults | frontend | listen | backend
5887 no | yes | yes | no
Willy Tarreau0ba27502007-12-24 16:55:16 +01005888 Arguments :
5889 if <cond> the monitor request will fail if the condition is satisfied,
5890 and will succeed otherwise. The condition should describe a
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005891 combined test which must induce a failure if all conditions
Willy Tarreau0ba27502007-12-24 16:55:16 +01005892 are met, for instance a low number of servers both in a
5893 backend and its backup.
5894
5895 unless <cond> the monitor request will succeed only if the condition is
5896 satisfied, and will fail otherwise. Such a condition may be
5897 based on a test on the presence of a minimum number of active
5898 servers in a list of backends.
5899
5900 This statement adds a condition which can force the response to a monitor
5901 request to report a failure. By default, when an external component queries
5902 the URI dedicated to monitoring, a 200 response is returned. When one of the
5903 conditions above is met, haproxy will return 503 instead of 200. This is
5904 very useful to report a site failure to an external component which may base
5905 routing advertisements between multiple sites on the availability reported by
5906 haproxy. In this case, one would rely on an ACL involving the "nbsrv"
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005907 criterion. Note that "monitor fail" only works in HTTP mode. Both status
5908 messages may be tweaked using "errorfile" or "errorloc" if needed.
Willy Tarreau0ba27502007-12-24 16:55:16 +01005909
5910 Example:
5911 frontend www
Willy Tarreau2769aa02007-12-27 18:26:09 +01005912 mode http
Willy Tarreau0ba27502007-12-24 16:55:16 +01005913 acl site_dead nbsrv(dynamic) lt 2
5914 acl site_dead nbsrv(static) lt 2
5915 monitor-uri /site_alive
5916 monitor fail if site_dead
5917
Willy Tarreauae94d4d2011-05-11 16:28:49 +02005918 See also : "monitor-net", "monitor-uri", "errorfile", "errorloc"
Willy Tarreau2769aa02007-12-27 18:26:09 +01005919
5920
5921monitor-net <source>
5922 Declare a source network which is limited to monitor requests
5923 May be used in sections : defaults | frontend | listen | backend
5924 yes | yes | yes | no
5925 Arguments :
5926 <source> is the source IPv4 address or network which will only be able to
5927 get monitor responses to any request. It can be either an IPv4
5928 address, a host name, or an address followed by a slash ('/')
5929 followed by a mask.
5930
5931 In TCP mode, any connection coming from a source matching <source> will cause
5932 the connection to be immediately closed without any log. This allows another
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01005933 equipment to probe the port and verify that it is still listening, without
Willy Tarreau2769aa02007-12-27 18:26:09 +01005934 forwarding the connection to a remote server.
5935
5936 In HTTP mode, a connection coming from a source matching <source> will be
5937 accepted, the following response will be sent without waiting for a request,
5938 then the connection will be closed : "HTTP/1.0 200 OK". This is normally
5939 enough for any front-end HTTP probe to detect that the service is UP and
Willy Tarreau82569f92012-09-27 23:48:56 +02005940 running without forwarding the request to a backend server. Note that this
5941 response is sent in raw format, without any transformation. This is important
5942 as it means that it will not be SSL-encrypted on SSL listeners.
Willy Tarreau2769aa02007-12-27 18:26:09 +01005943
Willy Tarreau82569f92012-09-27 23:48:56 +02005944 Monitor requests are processed very early, just after tcp-request connection
5945 ACLs which are the only ones able to block them. These connections are short
5946 lived and never wait for any data from the client. They cannot be logged, and
5947 it is the intended purpose. They are only used to report HAProxy's health to
5948 an upper component, nothing more. Please note that "monitor fail" rules do
5949 not apply to connections intercepted by "monitor-net".
Willy Tarreau2769aa02007-12-27 18:26:09 +01005950
Willy Tarreau95cd2832010-03-04 23:36:33 +01005951 Last, please note that only one "monitor-net" statement can be specified in
5952 a frontend. If more than one is found, only the last one will be considered.
Cyril Bonté108cf6e2012-04-21 23:30:29 +02005953
Willy Tarreau2769aa02007-12-27 18:26:09 +01005954 Example :
5955 # addresses .252 and .253 are just probing us.
5956 frontend www
5957 monitor-net 192.168.0.252/31
5958
5959 See also : "monitor fail", "monitor-uri"
5960
5961
5962monitor-uri <uri>
5963 Intercept a URI used by external components' monitor requests
5964 May be used in sections : defaults | frontend | listen | backend
5965 yes | yes | yes | no
5966 Arguments :
5967 <uri> is the exact URI which we want to intercept to return HAProxy's
5968 health status instead of forwarding the request.
5969
5970 When an HTTP request referencing <uri> will be received on a frontend,
5971 HAProxy will not forward it nor log it, but instead will return either
5972 "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
5973 conditions defined with "monitor fail". This is normally enough for any
5974 front-end HTTP probe to detect that the service is UP and running without
5975 forwarding the request to a backend server. Note that the HTTP method, the
5976 version and all headers are ignored, but the request must at least be valid
5977 at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
5978
Willy Tarreau721d8e02017-12-01 18:25:08 +01005979 Monitor requests are processed very early, just after the request is parsed
5980 and even before any "http-request" or "block" rulesets. The only rulesets
5981 applied before are the tcp-request ones. They cannot be logged either, and it
5982 is the intended purpose. They are only used to report HAProxy's health to an
5983 upper component, nothing more. However, it is possible to add any number of
5984 conditions using "monitor fail" and ACLs so that the result can be adjusted
5985 to whatever check can be imagined (most often the number of available servers
5986 in a backend).
Willy Tarreau2769aa02007-12-27 18:26:09 +01005987
5988 Example :
5989 # Use /haproxy_test to report haproxy's status
5990 frontend www
5991 mode http
5992 monitor-uri /haproxy_test
5993
5994 See also : "monitor fail", "monitor-net"
5995
Willy Tarreau0ba27502007-12-24 16:55:16 +01005996
Willy Tarreaubf1f8162007-12-28 17:42:56 +01005997option abortonclose
5998no option abortonclose
5999 Enable or disable early dropping of aborted requests pending in queues.
6000 May be used in sections : defaults | frontend | listen | backend
6001 yes | no | yes | yes
6002 Arguments : none
6003
6004 In presence of very high loads, the servers will take some time to respond.
6005 The per-instance connection queue will inflate, and the response time will
6006 increase respective to the size of the queue times the average per-session
6007 response time. When clients will wait for more than a few seconds, they will
Willy Tarreau198a7442008-01-17 12:05:32 +01006008 often hit the "STOP" button on their browser, leaving a useless request in
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006009 the queue, and slowing down other users, and the servers as well, because the
6010 request will eventually be served, then aborted at the first error
6011 encountered while delivering the response.
6012
6013 As there is no way to distinguish between a full STOP and a simple output
6014 close on the client side, HTTP agents should be conservative and consider
6015 that the client might only have closed its output channel while waiting for
6016 the response. However, this introduces risks of congestion when lots of users
6017 do the same, and is completely useless nowadays because probably no client at
6018 all will close the session while waiting for the response. Some HTTP agents
Davor Ocelice9ed2812017-12-25 17:49:28 +01006019 support this behavior (Squid, Apache, HAProxy), and others do not (TUX, most
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006020 hardware-based load balancers). So the probability for a closed input channel
Willy Tarreau198a7442008-01-17 12:05:32 +01006021 to represent a user hitting the "STOP" button is close to 100%, and the risk
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006022 of being the single component to break rare but valid traffic is extremely
6023 low, which adds to the temptation to be able to abort a session early while
6024 still not served and not pollute the servers.
6025
Davor Ocelice9ed2812017-12-25 17:49:28 +01006026 In HAProxy, the user can choose the desired behavior using the option
6027 "abortonclose". By default (without the option) the behavior is HTTP
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006028 compliant and aborted requests will be served. But when the option is
6029 specified, a session with an incoming channel closed will be aborted while
6030 it is still possible, either pending in the queue for a connection slot, or
6031 during the connection establishment if the server has not yet acknowledged
6032 the connection request. This considerably reduces the queue size and the load
6033 on saturated servers when users are tempted to click on STOP, which in turn
Willy Tarreaud72758d2010-01-12 10:42:19 +01006034 reduces the response time for other users.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006035
6036 If this option has been enabled in a "defaults" section, it can be disabled
6037 in a specific instance by prepending the "no" keyword before it.
6038
6039 See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters
6040
6041
Willy Tarreau4076a152009-04-02 15:18:36 +02006042option accept-invalid-http-request
6043no option accept-invalid-http-request
6044 Enable or disable relaxing of HTTP request parsing
6045 May be used in sections : defaults | frontend | listen | backend
6046 yes | yes | yes | no
6047 Arguments : none
6048
Willy Tarreau91852eb2015-05-01 13:26:00 +02006049 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02006050 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01006051 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02006052 forbidden characters are essentially used to build attacks exploiting server
6053 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
6054 server will emit invalid header names for whatever reason (configuration,
6055 implementation) and the issue will not be immediately fixed. In such a case,
6056 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau422246e2012-01-07 23:54:13 +01006057 even if that does not make sense, by specifying this option. Similarly, the
6058 list of characters allowed to appear in a URI is well defined by RFC3986, and
6059 chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96
6060 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are
Davor Ocelice9ed2812017-12-25 17:49:28 +01006061 not allowed at all. HAProxy always blocks a number of them (0..32, 127). The
Willy Tarreau91852eb2015-05-01 13:26:00 +02006062 remaining ones are blocked by default unless this option is enabled. This
Willy Tarreau13317662015-05-01 13:47:08 +02006063 option also relaxes the test on the HTTP version, it allows HTTP/0.9 requests
6064 to pass through (no version specified) and multiple digits for both the major
6065 and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02006066
6067 This option should never be enabled by default as it hides application bugs
6068 and open security breaches. It should only be deployed after a problem has
6069 been confirmed.
6070
6071 When this option is enabled, erroneous header names will still be accepted in
6072 requests, but the complete request will be captured in order to permit later
Willy Tarreau422246e2012-01-07 23:54:13 +01006073 analysis using the "show errors" request on the UNIX stats socket. Similarly,
6074 requests containing invalid chars in the URI part will be logged. Doing this
Willy Tarreau4076a152009-04-02 15:18:36 +02006075 also helps confirming that the issue has been solved.
6076
6077 If this option has been enabled in a "defaults" section, it can be disabled
6078 in a specific instance by prepending the "no" keyword before it.
6079
6080 See also : "option accept-invalid-http-response" and "show errors" on the
6081 stats socket.
6082
6083
6084option accept-invalid-http-response
6085no option accept-invalid-http-response
6086 Enable or disable relaxing of HTTP response parsing
6087 May be used in sections : defaults | frontend | listen | backend
6088 yes | no | yes | yes
6089 Arguments : none
6090
Willy Tarreau91852eb2015-05-01 13:26:00 +02006091 By default, HAProxy complies with RFC7230 in terms of message parsing. This
Willy Tarreau4076a152009-04-02 15:18:36 +02006092 means that invalid characters in header names are not permitted and cause an
Davor Ocelice9ed2812017-12-25 17:49:28 +01006093 error to be returned to the client. This is the desired behavior as such
Willy Tarreau4076a152009-04-02 15:18:36 +02006094 forbidden characters are essentially used to build attacks exploiting server
6095 weaknesses, and bypass security filtering. Sometimes, a buggy browser or
6096 server will emit invalid header names for whatever reason (configuration,
6097 implementation) and the issue will not be immediately fixed. In such a case,
6098 it is possible to relax HAProxy's header name parser to accept any character
Willy Tarreau91852eb2015-05-01 13:26:00 +02006099 even if that does not make sense, by specifying this option. This option also
6100 relaxes the test on the HTTP version format, it allows multiple digits for
6101 both the major and the minor version.
Willy Tarreau4076a152009-04-02 15:18:36 +02006102
6103 This option should never be enabled by default as it hides application bugs
6104 and open security breaches. It should only be deployed after a problem has
6105 been confirmed.
6106
6107 When this option is enabled, erroneous header names will still be accepted in
6108 responses, but the complete response will be captured in order to permit
6109 later analysis using the "show errors" request on the UNIX stats socket.
6110 Doing this also helps confirming that the issue has been solved.
6111
6112 If this option has been enabled in a "defaults" section, it can be disabled
6113 in a specific instance by prepending the "no" keyword before it.
6114
6115 See also : "option accept-invalid-http-request" and "show errors" on the
6116 stats socket.
6117
6118
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006119option allbackups
6120no option allbackups
6121 Use either all backup servers at a time or only the first one
6122 May be used in sections : defaults | frontend | listen | backend
6123 yes | no | yes | yes
6124 Arguments : none
6125
6126 By default, the first operational backup server gets all traffic when normal
6127 servers are all down. Sometimes, it may be preferred to use multiple backups
6128 at once, because one will not be enough. When "option allbackups" is enabled,
6129 the load balancing will be performed among all backup servers when all normal
6130 ones are unavailable. The same load balancing algorithm will be used and the
6131 servers' weights will be respected. Thus, there will not be any priority
6132 order between the backup servers anymore.
6133
6134 This option is mostly used with static server farms dedicated to return a
6135 "sorry" page when an application is completely offline.
6136
6137 If this option has been enabled in a "defaults" section, it can be disabled
6138 in a specific instance by prepending the "no" keyword before it.
6139
6140
6141option checkcache
6142no option checkcache
Godbach7056a352013-12-11 20:01:07 +08006143 Analyze all server responses and block responses with cacheable cookies
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006144 May be used in sections : defaults | frontend | listen | backend
6145 yes | no | yes | yes
6146 Arguments : none
6147
6148 Some high-level frameworks set application cookies everywhere and do not
6149 always let enough control to the developer to manage how the responses should
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006150 be cached. When a session cookie is returned on a cacheable object, there is a
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006151 high risk of session crossing or stealing between users traversing the same
6152 caches. In some situations, it is better to block the response than to let
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02006153 some sensitive session information go in the wild.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006154
6155 The option "checkcache" enables deep inspection of all server responses for
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006156 strict compliance with HTTP specification in terms of cacheability. It
Willy Tarreau198a7442008-01-17 12:05:32 +01006157 carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006158 response to check if there's a risk of caching a cookie on a client-side
6159 proxy. When this option is enabled, the only responses which can be delivered
Willy Tarreau198a7442008-01-17 12:05:32 +01006160 to the client are :
Davor Ocelice9ed2812017-12-25 17:49:28 +01006161 - all those without "Set-Cookie" header;
Willy Tarreauc55ddce2017-12-21 11:41:38 +01006162 - all those with a return code other than 200, 203, 204, 206, 300, 301,
6163 404, 405, 410, 414, 501, provided that the server has not set a
Davor Ocelice9ed2812017-12-25 17:49:28 +01006164 "Cache-control: public" header field;
Willy Tarreau24ea0bc2017-12-21 11:32:55 +01006165 - all those that result from a request using a method other than GET, HEAD,
6166 OPTIONS, TRACE, provided that the server has not set a 'Cache-Control:
Davor Ocelice9ed2812017-12-25 17:49:28 +01006167 public' header field;
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006168 - those with a 'Pragma: no-cache' header
6169 - those with a 'Cache-control: private' header
6170 - those with a 'Cache-control: no-store' header
6171 - those with a 'Cache-control: max-age=0' header
6172 - those with a 'Cache-control: s-maxage=0' header
6173 - those with a 'Cache-control: no-cache' header
6174 - those with a 'Cache-control: no-cache="set-cookie"' header
6175 - those with a 'Cache-control: no-cache="set-cookie,' header
6176 (allowing other fields after set-cookie)
6177
6178 If a response doesn't respect these requirements, then it will be blocked
Willy Tarreau198a7442008-01-17 12:05:32 +01006179 just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway".
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006180 The session state shows "PH--" meaning that the proxy blocked the response
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01006181 during headers processing. Additionally, an alert will be sent in the logs so
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006182 that admins are informed that there's something to be fixed.
6183
6184 Due to the high impact on the application, the application should be tested
6185 in depth with the option enabled before going to production. It is also a
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01006186 good practice to always activate it during tests, even if it is not used in
Davor Ocelice9ed2812017-12-25 17:49:28 +01006187 production, as it will report potentially dangerous application behaviors.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006188
6189 If this option has been enabled in a "defaults" section, it can be disabled
6190 in a specific instance by prepending the "no" keyword before it.
6191
6192
6193option clitcpka
6194no option clitcpka
6195 Enable or disable the sending of TCP keepalive packets on the client side
6196 May be used in sections : defaults | frontend | listen | backend
6197 yes | yes | yes | no
6198 Arguments : none
6199
6200 When there is a firewall or any session-aware component between a client and
6201 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01006202 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006203 components decides to expire a session which has remained idle for too long.
6204
6205 Enabling socket-level TCP keep-alives makes the system regularly send packets
6206 to the other end of the connection, leaving it active. The delay between
6207 keep-alive probes is controlled by the system only and depends both on the
6208 operating system and its tuning parameters.
6209
6210 It is important to understand that keep-alive packets are neither emitted nor
6211 received at the application level. It is only the network stacks which sees
6212 them. For this reason, even if one side of the proxy already uses keep-alives
6213 to maintain its connection alive, those keep-alive packets will not be
6214 forwarded to the other side of the proxy.
6215
6216 Please note that this has nothing to do with HTTP keep-alive.
6217
6218 Using option "clitcpka" enables the emission of TCP keep-alive probes on the
6219 client side of a connection, which should help when session expirations are
6220 noticed between HAProxy and a client.
6221
6222 If this option has been enabled in a "defaults" section, it can be disabled
6223 in a specific instance by prepending the "no" keyword before it.
6224
6225 See also : "option srvtcpka", "option tcpka"
6226
6227
Willy Tarreau0ba27502007-12-24 16:55:16 +01006228option contstats
6229 Enable continuous traffic statistics updates
6230 May be used in sections : defaults | frontend | listen | backend
6231 yes | yes | yes | no
6232 Arguments : none
6233
6234 By default, counters used for statistics calculation are incremented
6235 only when a session finishes. It works quite well when serving small
6236 objects, but with big ones (for example large images or archives) or
6237 with A/V streaming, a graph generated from haproxy counters looks like
Willy Tarreaudef0d222016-11-08 22:03:00 +01006238 a hedgehog. With this option enabled counters get incremented frequently
6239 along the session, typically every 5 seconds, which is often enough to
6240 produce clean graphs. Recounting touches a hotpath directly so it is not
6241 not enabled by default, as it can cause a lot of wakeups for very large
6242 session counts and cause a small performance drop.
Willy Tarreau0ba27502007-12-24 16:55:16 +01006243
6244
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006245option dontlog-normal
6246no option dontlog-normal
6247 Enable or disable logging of normal, successful connections
6248 May be used in sections : defaults | frontend | listen | backend
6249 yes | yes | yes | no
6250 Arguments : none
6251
6252 There are large sites dealing with several thousand connections per second
6253 and for which logging is a major pain. Some of them are even forced to turn
6254 logs off and cannot debug production issues. Setting this option ensures that
6255 normal connections, those which experience no error, no timeout, no retry nor
6256 redispatch, will not be logged. This leaves disk space for anomalies. In HTTP
6257 mode, the response status code is checked and return codes 5xx will still be
6258 logged.
6259
6260 It is strongly discouraged to use this option as most of the time, the key to
6261 complex issues is in the normal logs which will not be logged here. If you
6262 need to separate logs, see the "log-separate-errors" option instead.
6263
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006264 See also : "log", "dontlognull", "log-separate-errors" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02006265 logging.
6266
6267
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006268option dontlognull
6269no option dontlognull
6270 Enable or disable logging of null connections
6271 May be used in sections : defaults | frontend | listen | backend
6272 yes | yes | yes | no
6273 Arguments : none
6274
6275 In certain environments, there are components which will regularly connect to
6276 various systems to ensure that they are still alive. It can be the case from
6277 another load balancer as well as from monitoring systems. By default, even a
6278 simple port probe or scan will produce a log. If those connections pollute
6279 the logs too much, it is possible to enable option "dontlognull" to indicate
6280 that a connection on which no data has been transferred will not be logged,
Willy Tarreau0f228a02015-05-01 15:37:53 +02006281 which typically corresponds to those probes. Note that errors will still be
6282 returned to the client and accounted for in the stats. If this is not what is
6283 desired, option http-ignore-probes can be used instead.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006284
6285 It is generally recommended not to use this option in uncontrolled
Davor Ocelice9ed2812017-12-25 17:49:28 +01006286 environments (e.g. internet), otherwise scans and other malicious activities
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006287 would not be logged.
6288
6289 If this option has been enabled in a "defaults" section, it can be disabled
6290 in a specific instance by prepending the "no" keyword before it.
6291
Willy Tarreau0f228a02015-05-01 15:37:53 +02006292 See also : "log", "http-ignore-probes", "monitor-net", "monitor-uri", and
6293 section 8 about logging.
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006294
Willy Tarreaubf1f8162007-12-28 17:42:56 +01006295
Willy Tarreau87cf5142011-08-19 22:57:24 +02006296option forwardfor [ except <network> ] [ header <name> ] [ if-none ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01006297 Enable insertion of the X-Forwarded-For header to requests sent to servers
6298 May be used in sections : defaults | frontend | listen | backend
6299 yes | yes | yes | yes
6300 Arguments :
6301 <network> is an optional argument used to disable this option for sources
6302 matching <network>
Ross Westaf72a1d2008-08-03 10:51:45 +02006303 <name> an optional argument to specify a different "X-Forwarded-For"
Willy Tarreaud72758d2010-01-12 10:42:19 +01006304 header name.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006305
6306 Since HAProxy works in reverse-proxy mode, the servers see its IP address as
6307 their client address. This is sometimes annoying when the client's IP address
6308 is expected in server logs. To solve this problem, the well-known HTTP header
6309 "X-Forwarded-For" may be added by HAProxy to all requests sent to the server.
6310 This header contains a value representing the client's IP address. Since this
6311 header is always appended at the end of the existing header list, the server
6312 must be configured to always use the last occurrence of this header only. See
Ross Westaf72a1d2008-08-03 10:51:45 +02006313 the server's manual to find how to enable use of this standard header. Note
6314 that only the last occurrence of the header must be used, since it is really
6315 possible that the client has already brought one.
6316
Willy Tarreaud72758d2010-01-12 10:42:19 +01006317 The keyword "header" may be used to supply a different header name to replace
Ross Westaf72a1d2008-08-03 10:51:45 +02006318 the default "X-Forwarded-For". This can be useful where you might already
Davor Ocelice9ed2812017-12-25 17:49:28 +01006319 have a "X-Forwarded-For" header from a different application (e.g. stunnel),
Willy Tarreaud72758d2010-01-12 10:42:19 +01006320 and you need preserve it. Also if your backend server doesn't use the
Davor Ocelice9ed2812017-12-25 17:49:28 +01006321 "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers
Ross Westaf72a1d2008-08-03 10:51:45 +02006322 require "X-Cluster-Client-IP").
Willy Tarreauc27debf2008-01-06 08:57:02 +01006323
6324 Sometimes, a same HAProxy instance may be shared between a direct client
6325 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
6326 used to decrypt HTTPS traffic). It is possible to disable the addition of the
6327 header for a known source address or network by adding the "except" keyword
6328 followed by the network address. In this case, any source IP matching the
6329 network will not cause an addition of this header. Most common uses are with
6330 private networks or 127.0.0.1.
6331
Willy Tarreau87cf5142011-08-19 22:57:24 +02006332 Alternatively, the keyword "if-none" states that the header will only be
6333 added if it is not present. This should only be used in perfectly trusted
6334 environment, as this might cause a security issue if headers reaching haproxy
6335 are under the control of the end-user.
6336
Willy Tarreauc27debf2008-01-06 08:57:02 +01006337 This option may be specified either in the frontend or in the backend. If at
Ross Westaf72a1d2008-08-03 10:51:45 +02006338 least one of them uses it, the header will be added. Note that the backend's
6339 setting of the header subargument takes precedence over the frontend's if
Willy Tarreau87cf5142011-08-19 22:57:24 +02006340 both are defined. In the case of the "if-none" argument, if at least one of
6341 the frontend or the backend does not specify it, it wants the addition to be
6342 mandatory, so it wins.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006343
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +02006344 Example :
Willy Tarreauc27debf2008-01-06 08:57:02 +01006345 # Public HTTP address also used by stunnel on the same machine
6346 frontend www
6347 mode http
6348 option forwardfor except 127.0.0.1 # stunnel already adds the header
6349
Ross Westaf72a1d2008-08-03 10:51:45 +02006350 # Those servers want the IP Address in X-Client
6351 backend www
6352 mode http
6353 option forwardfor header X-Client
6354
Willy Tarreau87cf5142011-08-19 22:57:24 +02006355 See also : "option httpclose", "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02006356 "option http-keep-alive"
Willy Tarreauc27debf2008-01-06 08:57:02 +01006357
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006358
Christopher Fauleta99ff4d2019-07-22 16:18:24 +02006359option h1-case-adjust-bogus-client
6360no option h1-case-adjust-bogus-client
6361 Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients
6362 May be used in sections : defaults | frontend | listen | backend
6363 yes | yes | yes | no
6364 Arguments : none
6365
6366 There is no standard case for header names because, as stated in RFC7230,
6367 they are case-insensitive. So applications must handle them in a case-
6368 insensitive manner. But some bogus applications violate the standards and
6369 erroneously rely on the cases most commonly used by browsers. This problem
6370 becomes critical with HTTP/2 because all header names must be exchanged in
6371 lower case, and HAProxy follows the same convention. All header names are
6372 sent in lower case to clients and servers, regardless of the HTTP version.
6373
6374 When HAProxy receives an HTTP/1 response, its header names are converted to
6375 lower case and manipulated and sent this way to the clients. If a client is
6376 known to violate the HTTP standards and to fail to process a response coming
6377 from HAProxy, it is possible to transform the lower case header names to a
6378 different format when the response is formatted and sent to the client, by
6379 enabling this option and specifying the list of headers to be reformatted
6380 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
6381 must only be a temporary workaround for the time it takes the client to be
6382 fixed, because clients which require such workarounds might be vulnerable to
6383 content smuggling attacks and must absolutely be fixed.
6384
6385 Please note that this option will not affect standards-compliant clients.
6386
6387 If this option has been enabled in a "defaults" section, it can be disabled
6388 in a specific instance by prepending the "no" keyword before it.
6389
6390 See also: "option h1-case-adjust-bogus-server", "h1-case-adjust",
6391 "h1-case-adjust-file".
6392
6393
6394option h1-case-adjust-bogus-server
6395no option h1-case-adjust-bogus-server
6396 Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers
6397 May be used in sections : defaults | frontend | listen | backend
6398 yes | no | yes | yes
6399 Arguments : none
6400
6401 There is no standard case for header names because, as stated in RFC7230,
6402 they are case-insensitive. So applications must handle them in a case-
6403 insensitive manner. But some bogus applications violate the standards and
6404 erroneously rely on the cases most commonly used by browsers. This problem
6405 becomes critical with HTTP/2 because all header names must be exchanged in
6406 lower case, and HAProxy follows the same convention. All header names are
6407 sent in lower case to clients and servers, regardless of the HTTP version.
6408
6409 When HAProxy receives an HTTP/1 request, its header names are converted to
6410 lower case and manipulated and sent this way to the servers. If a server is
6411 known to violate the HTTP standards and to fail to process a request coming
6412 from HAProxy, it is possible to transform the lower case header names to a
6413 different format when the request is formatted and sent to the server, by
6414 enabling this option and specifying the list of headers to be reformatted
6415 using the global directives "h1-case-adjust" or "h1-case-adjust-file". This
6416 must only be a temporary workaround for the time it takes the server to be
6417 fixed, because servers which require such workarounds might be vulnerable to
6418 content smuggling attacks and must absolutely be fixed.
6419
6420 Please note that this option will not affect standards-compliant servers.
6421
6422 If this option has been enabled in a "defaults" section, it can be disabled
6423 in a specific instance by prepending the "no" keyword before it.
6424
6425 See also: "option h1-case-adjust-bogus-client", "h1-case-adjust",
6426 "h1-case-adjust-file".
6427
6428
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006429option http-buffer-request
6430no option http-buffer-request
6431 Enable or disable waiting for whole HTTP request body before proceeding
6432 May be used in sections : defaults | frontend | listen | backend
6433 yes | yes | yes | yes
6434 Arguments : none
6435
6436 It is sometimes desirable to wait for the body of an HTTP request before
6437 taking a decision. This is what is being done by "balance url_param" for
6438 example. The first use case is to buffer requests from slow clients before
6439 connecting to the server. Another use case consists in taking the routing
6440 decision based on the request body's contents. This option placed in a
6441 frontend or backend forces the HTTP processing to wait until either the whole
6442 body is received, or the request buffer is full, or the first chunk is
6443 complete in case of chunked encoding. It can have undesired side effects with
Tim Düsterhus4896c442016-11-29 02:15:19 +01006444 some applications abusing HTTP by expecting unbuffered transmissions between
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006445 the frontend and the backend, so this should definitely not be used by
6446 default.
6447
Baptiste Assmanneccdf432015-10-28 13:49:01 +01006448 See also : "option http-no-delay", "timeout http-request"
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006449
6450
Willy Tarreau0f228a02015-05-01 15:37:53 +02006451option http-ignore-probes
6452no option http-ignore-probes
6453 Enable or disable logging of null connections and request timeouts
6454 May be used in sections : defaults | frontend | listen | backend
6455 yes | yes | yes | no
6456 Arguments : none
6457
6458 Recently some browsers started to implement a "pre-connect" feature
6459 consisting in speculatively connecting to some recently visited web sites
6460 just in case the user would like to visit them. This results in many
6461 connections being established to web sites, which end up in 408 Request
6462 Timeout if the timeout strikes first, or 400 Bad Request when the browser
6463 decides to close them first. These ones pollute the log and feed the error
6464 counters. There was already "option dontlognull" but it's insufficient in
6465 this case. Instead, this option does the following things :
6466 - prevent any 400/408 message from being sent to the client if nothing
Davor Ocelice9ed2812017-12-25 17:49:28 +01006467 was received over a connection before it was closed;
6468 - prevent any log from being emitted in this situation;
Willy Tarreau0f228a02015-05-01 15:37:53 +02006469 - prevent any error counter from being incremented
6470
6471 That way the empty connection is silently ignored. Note that it is better
6472 not to use this unless it is clear that it is needed, because it will hide
6473 real problems. The most common reason for not receiving a request and seeing
6474 a 408 is due to an MTU inconsistency between the client and an intermediary
6475 element such as a VPN, which blocks too large packets. These issues are
6476 generally seen with POST requests as well as GET with large cookies. The logs
6477 are often the only way to detect them.
6478
6479 If this option has been enabled in a "defaults" section, it can be disabled
6480 in a specific instance by prepending the "no" keyword before it.
6481
6482 See also : "log", "dontlognull", "errorfile", and section 8 about logging.
6483
6484
Willy Tarreau16bfb022010-01-16 19:48:41 +01006485option http-keep-alive
6486no option http-keep-alive
6487 Enable or disable HTTP keep-alive from client to server
6488 May be used in sections : defaults | frontend | listen | backend
6489 yes | yes | yes | yes
6490 Arguments : none
6491
Willy Tarreau70dffda2014-01-30 03:07:23 +01006492 By default HAProxy operates in keep-alive mode with regards to persistent
6493 connections: for each connection it processes each request and response, and
Christopher Faulet315b39c2018-09-21 16:26:19 +02006494 leaves the connection idle on both sides between the end of a response and
6495 the start of a new request. This mode may be changed by several options such
6496 as "option http-server-close", "option httpclose" or "option http-tunnel".
6497 This option allows to set back the keep-alive mode, which can be useful when
6498 another mode was used in a defaults section.
Willy Tarreau70dffda2014-01-30 03:07:23 +01006499
6500 Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-
6501 and server- sides. This provides the lowest latency on the client side (slow
Willy Tarreau16bfb022010-01-16 19:48:41 +01006502 network) and the fastest session reuse on the server side at the expense
6503 of maintaining idle connections to the servers. In general, it is possible
6504 with this option to achieve approximately twice the request rate that the
6505 "http-server-close" option achieves on small objects. There are mainly two
6506 situations where this option may be useful :
6507
6508 - when the server is non-HTTP compliant and authenticates the connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01006509 instead of requests (e.g. NTLM authentication)
Willy Tarreau16bfb022010-01-16 19:48:41 +01006510
6511 - when the cost of establishing the connection to the server is significant
6512 compared to the cost of retrieving the associated object from the server.
6513
6514 This last case can happen when the server is a fast static server of cache.
6515 In this case, the server will need to be properly tuned to support high enough
6516 connection counts because connections will last until the client sends another
6517 request.
6518
6519 If the client request has to go to another backend or another server due to
6520 content switching or the load balancing algorithm, the idle connection will
Willy Tarreau9420b122013-12-15 18:58:25 +01006521 immediately be closed and a new one re-opened. Option "prefer-last-server" is
6522 available to try optimize server selection so that if the server currently
6523 attached to an idle connection is usable, it will be used.
Willy Tarreau16bfb022010-01-16 19:48:41 +01006524
Willy Tarreau16bfb022010-01-16 19:48:41 +01006525 At the moment, logs will not indicate whether requests came from the same
6526 session or not. The accept date reported in the logs corresponds to the end
6527 of the previous request, and the request time corresponds to the time spent
6528 waiting for a new request. The keep-alive request time is still bound to the
6529 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
6530 not set.
6531
Cyril Bonté653dcd62014-02-20 00:13:15 +01006532 This option disables and replaces any previous "option httpclose", "option
Christopher Faulet315b39c2018-09-21 16:26:19 +02006533 http-server-close" or "option http-tunnel". When backend and frontend options
6534 differ, all of these 4 options have precedence over "option http-keep-alive".
Willy Tarreau16bfb022010-01-16 19:48:41 +01006535
Christopher Faulet315b39c2018-09-21 16:26:19 +02006536 See also : "option httpclose",, "option http-server-close",
Willy Tarreau9420b122013-12-15 18:58:25 +01006537 "option prefer-last-server", "option http-pretend-keepalive",
Frédéric Lécaille93d33162019-03-06 09:35:59 +01006538 and "1.1. The HTTP transaction model".
Willy Tarreau16bfb022010-01-16 19:48:41 +01006539
6540
Willy Tarreau96e31212011-05-30 18:10:30 +02006541option http-no-delay
6542no option http-no-delay
6543 Instruct the system to favor low interactive delays over performance in HTTP
6544 May be used in sections : defaults | frontend | listen | backend
6545 yes | yes | yes | yes
6546 Arguments : none
6547
6548 In HTTP, each payload is unidirectional and has no notion of interactivity.
6549 Any agent is expected to queue data somewhat for a reasonably low delay.
6550 There are some very rare server-to-server applications that abuse the HTTP
6551 protocol and expect the payload phase to be highly interactive, with many
6552 interleaved data chunks in both directions within a single request. This is
6553 absolutely not supported by the HTTP specification and will not work across
6554 most proxies or servers. When such applications attempt to do this through
6555 haproxy, it works but they will experience high delays due to the network
6556 optimizations which favor performance by instructing the system to wait for
6557 enough data to be available in order to only send full packets. Typical
6558 delays are around 200 ms per round trip. Note that this only happens with
6559 abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not
6560 affected.
6561
6562 When "option http-no-delay" is present in either the frontend or the backend
6563 used by a connection, all such optimizations will be disabled in order to
6564 make the exchanges as fast as possible. Of course this offers no guarantee on
6565 the functionality, as it may break at any other place. But if it works via
6566 HAProxy, it will work as fast as possible. This option should never be used
6567 by default, and should never be used at all unless such a buggy application
6568 is discovered. The impact of using this option is an increase of bandwidth
6569 usage and CPU usage, which may significantly lower performance in high
6570 latency environments.
6571
Willy Tarreau9fbe18e2015-05-01 22:42:08 +02006572 See also : "option http-buffer-request"
6573
Willy Tarreau96e31212011-05-30 18:10:30 +02006574
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006575option http-pretend-keepalive
6576no option http-pretend-keepalive
6577 Define whether haproxy will announce keepalive to the server or not
6578 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet98db9762018-09-21 10:25:19 +02006579 yes | no | yes | yes
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006580 Arguments : none
6581
Christopher Faulet315b39c2018-09-21 16:26:19 +02006582 When running with "option http-server-close" or "option httpclose", haproxy
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006583 adds a "Connection: close" header to the request forwarded to the server.
6584 Unfortunately, when some servers see this header, they automatically refrain
6585 from using the chunked encoding for responses of unknown length, while this
6586 is totally unrelated. The immediate effect is that this prevents haproxy from
6587 maintaining the client connection alive. A second effect is that a client or
6588 a cache could receive an incomplete response without being aware of it, and
6589 consider the response complete.
6590
6591 By setting "option http-pretend-keepalive", haproxy will make the server
6592 believe it will keep the connection alive. The server will then not fall back
6593 to the abnormal undesired above. When haproxy gets the whole response, it
6594 will close the connection with the server just as it would do with the
Christopher Faulet315b39c2018-09-21 16:26:19 +02006595 "option httpclose". That way the client gets a normal response and the
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006596 connection is correctly closed on the server side.
6597
6598 It is recommended not to enable this option by default, because most servers
6599 will more efficiently close the connection themselves after the last packet,
6600 and release its buffers slightly earlier. Also, the added packet on the
6601 network could slightly reduce the overall peak performance. However it is
6602 worth noting that when this option is enabled, haproxy will have slightly
6603 less work to do. So if haproxy is the bottleneck on the whole architecture,
6604 enabling this option might save a few CPU cycles.
6605
Christopher Faulet98db9762018-09-21 10:25:19 +02006606 This option may be set in backend and listen sections. Using it in a frontend
6607 section will be ignored and a warning will be reported during startup. It is
6608 a backend related option, so there is no real reason to set it on a
6609 frontend. This option may be combined with "option httpclose", which will
6610 cause keepalive to be announced to the server and close to be announced to
6611 the client. This practice is discouraged though.
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006612
6613 If this option has been enabled in a "defaults" section, it can be disabled
6614 in a specific instance by prepending the "no" keyword before it.
6615
Christopher Faulet315b39c2018-09-21 16:26:19 +02006616 See also : "option httpclose", "option http-server-close", and
Willy Tarreau16bfb022010-01-16 19:48:41 +01006617 "option http-keep-alive"
Willy Tarreau8a8e1d92010-04-05 16:15:16 +02006618
Willy Tarreauc27debf2008-01-06 08:57:02 +01006619
Willy Tarreaub608feb2010-01-02 22:47:18 +01006620option http-server-close
6621no option http-server-close
6622 Enable or disable HTTP connection closing on the server side
6623 May be used in sections : defaults | frontend | listen | backend
6624 yes | yes | yes | yes
6625 Arguments : none
6626
Willy Tarreau70dffda2014-01-30 03:07:23 +01006627 By default HAProxy operates in keep-alive mode with regards to persistent
6628 connections: for each connection it processes each request and response, and
6629 leaves the connection idle on both sides between the end of a response and
6630 the start of a new request. This mode may be changed by several options such
Christopher Faulet315b39c2018-09-21 16:26:19 +02006631 as "option http-server-close", "option httpclose" or "option http-tunnel".
6632 Setting "option http-server-close" enables HTTP connection-close mode on the
6633 server side while keeping the ability to support HTTP keep-alive and
6634 pipelining on the client side. This provides the lowest latency on the client
6635 side (slow network) and the fastest session reuse on the server side to save
6636 server resources, similarly to "option httpclose". It also permits
6637 non-keepalive capable servers to be served in keep-alive mode to the clients
6638 if they conform to the requirements of RFC7230. Please note that some servers
6639 do not always conform to those requirements when they see "Connection: close"
6640 in the request. The effect will be that keep-alive will never be used. A
6641 workaround consists in enabling "option http-pretend-keepalive".
Willy Tarreaub608feb2010-01-02 22:47:18 +01006642
6643 At the moment, logs will not indicate whether requests came from the same
6644 session or not. The accept date reported in the logs corresponds to the end
6645 of the previous request, and the request time corresponds to the time spent
6646 waiting for a new request. The keep-alive request time is still bound to the
Willy Tarreaub16a5742010-01-10 14:46:16 +01006647 timeout defined by "timeout http-keep-alive" or "timeout http-request" if
6648 not set.
Willy Tarreaub608feb2010-01-02 22:47:18 +01006649
6650 This option may be set both in a frontend and in a backend. It is enabled if
6651 at least one of the frontend or backend holding a connection has it enabled.
Christopher Faulet315b39c2018-09-21 16:26:19 +02006652 It disables and replaces any previous "option httpclose", "option http-tunnel"
6653 or "option http-keep-alive". Please check section 4 ("Proxies") to see how
6654 this option combines with others when frontend and backend options differ.
Willy Tarreaub608feb2010-01-02 22:47:18 +01006655
6656 If this option has been enabled in a "defaults" section, it can be disabled
6657 in a specific instance by prepending the "no" keyword before it.
6658
Christopher Faulet315b39c2018-09-21 16:26:19 +02006659 See also : "option httpclose", "option http-pretend-keepalive",
6660 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreaub608feb2010-01-02 22:47:18 +01006661
6662
Christopher Faulet6c9bbb22019-03-26 21:37:23 +01006663option http-tunnel (deprecated)
6664no option http-tunnel (deprecated)
6665 Disable or enable HTTP connection processing after first transaction.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006666 May be used in sections : defaults | frontend | listen | backend
Christopher Faulet4212a302018-09-21 10:42:19 +02006667 yes | yes | yes | no
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006668 Arguments : none
6669
Christopher Faulet6c9bbb22019-03-26 21:37:23 +01006670 Warning : Because it cannot work in HTTP/2, this option is deprecated and it
6671 is only supported on legacy HTTP frontends. In HTX, it is ignored and a
6672 warning is emitted during HAProxy startup.
6673
Willy Tarreau70dffda2014-01-30 03:07:23 +01006674 By default HAProxy operates in keep-alive mode with regards to persistent
6675 connections: for each connection it processes each request and response, and
6676 leaves the connection idle on both sides between the end of a response and
6677 the start of a new request. This mode may be changed by several options such
Christopher Faulet315b39c2018-09-21 16:26:19 +02006678 as "option http-server-close", "option httpclose" or "option http-tunnel".
Willy Tarreau70dffda2014-01-30 03:07:23 +01006679
6680 Option "http-tunnel" disables any HTTP processing past the first request and
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03006681 the first response. This is the mode which was used by default in versions
Willy Tarreau70dffda2014-01-30 03:07:23 +01006682 1.0 to 1.5-dev21. It is the mode with the lowest processing overhead, which
6683 is normally not needed anymore unless in very specific cases such as when
6684 using an in-house protocol that looks like HTTP but is not compatible, or
6685 just to log one request per client in order to reduce log size. Note that
6686 everything which works at the HTTP level, including header parsing/addition,
6687 cookie processing or content switching will only work for the first request
6688 and will be ignored after the first response.
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006689
Christopher Faulet4212a302018-09-21 10:42:19 +02006690 This option may be set on frontend and listen sections. Using it on a backend
6691 section will be ignored and a warning will be reported during the startup. It
6692 is a frontend related option, so there is no real reason to set it on a
6693 backend.
6694
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006695 If this option has been enabled in a "defaults" section, it can be disabled
6696 in a specific instance by prepending the "no" keyword before it.
6697
Christopher Faulet315b39c2018-09-21 16:26:19 +02006698 See also : "option httpclose", "option http-server-close",
6699 "option http-keep-alive", and "1.1. The HTTP transaction model".
Willy Tarreau02bce8b2014-01-30 00:15:28 +01006700
6701
Willy Tarreau88d349d2010-01-25 12:15:43 +01006702option http-use-proxy-header
Cyril Bontéf0c60612010-02-06 14:44:47 +01006703no option http-use-proxy-header
Willy Tarreau88d349d2010-01-25 12:15:43 +01006704 Make use of non-standard Proxy-Connection header instead of Connection
6705 May be used in sections : defaults | frontend | listen | backend
6706 yes | yes | yes | no
6707 Arguments : none
6708
Lukas Tribus23953682017-04-28 13:24:30 +00006709 While RFC7230 explicitly states that HTTP/1.1 agents must use the
Willy Tarreau88d349d2010-01-25 12:15:43 +01006710 Connection header to indicate their wish of persistent or non-persistent
6711 connections, both browsers and proxies ignore this header for proxied
6712 connections and make use of the undocumented, non-standard Proxy-Connection
6713 header instead. The issue begins when trying to put a load balancer between
6714 browsers and such proxies, because there will be a difference between what
6715 haproxy understands and what the client and the proxy agree on.
6716
6717 By setting this option in a frontend, haproxy can automatically switch to use
6718 that non-standard header if it sees proxied requests. A proxied request is
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006719 defined here as one where the URI begins with neither a '/' nor a '*'. This
6720 is incompatible with the HTTP tunnel mode. Note that this option can only be
6721 specified in a frontend and will affect the request along its whole life.
Willy Tarreau88d349d2010-01-25 12:15:43 +01006722
Willy Tarreau844a7e72010-01-31 21:46:18 +01006723 Also, when this option is set, a request which requires authentication will
6724 automatically switch to use proxy authentication headers if it is itself a
6725 proxied request. That makes it possible to check or enforce authentication in
6726 front of an existing proxy.
6727
Willy Tarreau88d349d2010-01-25 12:15:43 +01006728 This option should normally never be used, except in front of a proxy.
6729
Christopher Faulet315b39c2018-09-21 16:26:19 +02006730 See also : "option httpclose", and "option http-server-close".
Willy Tarreau88d349d2010-01-25 12:15:43 +01006731
6732
Willy Tarreau68ad3a42018-10-22 11:49:15 +02006733option http-use-htx
6734no option http-use-htx
6735 Switch to the new HTX internal representation for HTTP protocol elements
6736 May be used in sections : defaults | frontend | listen | backend
6737 yes | yes | yes | yes
6738 Arguments : none
6739
Christopher Faulet1d2b5862019-04-12 16:10:51 +02006740 Historically, the HTTP protocol is processed as-is. Inserting, deleting, or
Willy Tarreau68ad3a42018-10-22 11:49:15 +02006741 modifying a header field requires to rewrite the affected part in the buffer
Christopher Faulet1d2b5862019-04-12 16:10:51 +02006742 and to move the buffer's tail accordingly. This mode is known as the legacy
6743 HTTP mode. Since this principle has deep roots in haproxy, the HTTP/2
6744 protocol is converted to HTTP/1.1 before being processed this way. It also
6745 results in the inability to establish HTTP/2 connections to servers because
6746 of the loss of HTTP/2 semantics in the HTTP/1 representation.
Willy Tarreau68ad3a42018-10-22 11:49:15 +02006747
6748 HTX is the name of a totally new native internal representation for the HTTP
6749 protocol, that is agnostic to the version and aims at preserving semantics
6750 all along the chain. It relies on a fast parsing, tokenizing and indexing of
6751 the protocol elements so that no more memory moves are necessary and that
Christopher Faulet1d2b5862019-04-12 16:10:51 +02006752 most elements are directly accessed. It supports using either HTTP/1 or
6753 HTTP/2 on any side regardless of the other side's version. It also supports
6754 upgrades from TCP to HTTP and implicit ones from HTTP/1 to HTTP/2 (matching
6755 the HTTP/2 preface).
Willy Tarreau68ad3a42018-10-22 11:49:15 +02006756
Christopher Faulet1d2b5862019-04-12 16:10:51 +02006757 This option indicates that HTX needs to be used. Since the version 2.0-dev3,
6758 the HTX is the default mode. To switch back on the legacy HTTP mode, the
6759 option must be explicitly disabled using the "no" prefix. For prior versions,
6760 the feature has incomplete functional coverage, so it is not enabled by
6761 default.
Willy Tarreau68ad3a42018-10-22 11:49:15 +02006762
6763 See also : "mode http"
6764
6765
Willy Tarreaud63335a2010-02-26 12:56:52 +01006766option httpchk
6767option httpchk <uri>
6768option httpchk <method> <uri>
6769option httpchk <method> <uri> <version>
6770 Enable HTTP protocol to check on the servers health
6771 May be used in sections : defaults | frontend | listen | backend
6772 yes | no | yes | yes
6773 Arguments :
6774 <method> is the optional HTTP method used with the requests. When not set,
6775 the "OPTIONS" method is used, as it generally requires low server
6776 processing and is easy to filter out from the logs. Any method
6777 may be used, though it is not recommended to invent non-standard
6778 ones.
6779
6780 <uri> is the URI referenced in the HTTP requests. It defaults to " / "
6781 which is accessible by default on almost any server, but may be
6782 changed to any other URI. Query strings are permitted.
6783
6784 <version> is the optional HTTP version string. It defaults to "HTTP/1.0"
6785 but some servers might behave incorrectly in HTTP 1.0, so turning
6786 it to HTTP/1.1 may sometimes help. Note that the Host field is
Christopher Fauletf304ad32020-04-09 08:44:06 +02006787 mandatory in HTTP/1.1, use "http-check send" directive to add it.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006788
6789 By default, server health checks only consist in trying to establish a TCP
6790 connection. When "option httpchk" is specified, a complete HTTP request is
6791 sent once the TCP connection is established, and responses 2xx and 3xx are
6792 considered valid, while all other ones indicate a server failure, including
6793 the lack of any response.
6794
6795 The port and interval are specified in the server configuration.
6796
6797 This option does not necessarily require an HTTP backend, it also works with
6798 plain TCP backends. This is particularly useful to check simple scripts bound
6799 to some dedicated ports using the inetd daemon.
6800
Christopher Fauletf304ad32020-04-09 08:44:06 +02006801 Note : For a while, there was no way to add headers or body in the request
6802 used for HTTP health checks. So a workaround was to hide it at the end
6803 of the version string with a "\r\n" after the version. It is now
6804 deprecated. The directive "http-check send" must be used instead.
6805
Willy Tarreaud63335a2010-02-26 12:56:52 +01006806 Examples :
6807 # Relay HTTPS traffic to Apache instance and check service availability
6808 # using HTTP request "OPTIONS * HTTP/1.1" on port 80.
6809 backend https_relay
6810 mode tcp
Christopher Fauletf304ad32020-04-09 08:44:06 +02006811 option httpchk OPTIONS * HTTP/1.1
6812 http-check send hdr Host www
Willy Tarreaud63335a2010-02-26 12:56:52 +01006813 server apache1 192.168.1.1:443 check port 80
6814
Simon Hormanafc47ee2013-11-25 10:46:35 +09006815 See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check",
6816 "option pgsql-check", "http-check" and the "check", "port" and
6817 "inter" server options.
Willy Tarreaud63335a2010-02-26 12:56:52 +01006818
6819
Willy Tarreauc27debf2008-01-06 08:57:02 +01006820option httpclose
6821no option httpclose
Christopher Faulet315b39c2018-09-21 16:26:19 +02006822 Enable or disable HTTP connection closing
Willy Tarreauc27debf2008-01-06 08:57:02 +01006823 May be used in sections : defaults | frontend | listen | backend
6824 yes | yes | yes | yes
6825 Arguments : none
6826
Willy Tarreau70dffda2014-01-30 03:07:23 +01006827 By default HAProxy operates in keep-alive mode with regards to persistent
6828 connections: for each connection it processes each request and response, and
6829 leaves the connection idle on both sides between the end of a response and
6830 the start of a new request. This mode may be changed by several options such
Christopher Faulet315b39c2018-09-21 16:26:19 +02006831 as "option http-server-close", "option httpclose" or "option http-tunnel".
Willy Tarreau70dffda2014-01-30 03:07:23 +01006832
Christopher Faulet315b39c2018-09-21 16:26:19 +02006833 If "option httpclose" is set, HAProxy will close connections with the server
6834 and the client as soon as the request and the response are received. It will
John Roesler27c754c2019-07-10 15:45:51 -05006835 also check if a "Connection: close" header is already set in each direction,
Christopher Faulet315b39c2018-09-21 16:26:19 +02006836 and will add one if missing. Any "Connection" header different from "close"
6837 will also be removed.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006838
Christopher Faulet315b39c2018-09-21 16:26:19 +02006839 This option may also be combined with "option http-pretend-keepalive", which
6840 will disable sending of the "Connection: close" header, but will still cause
6841 the connection to be closed once the whole response is received.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006842
6843 This option may be set both in a frontend and in a backend. It is enabled if
6844 at least one of the frontend or backend holding a connection has it enabled.
Cyril Bonté653dcd62014-02-20 00:13:15 +01006845 It disables and replaces any previous "option http-server-close",
Christopher Faulet315b39c2018-09-21 16:26:19 +02006846 "option http-keep-alive" or "option http-tunnel". Please check section 4
6847 ("Proxies") to see how this option combines with others when frontend and
6848 backend options differ.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006849
6850 If this option has been enabled in a "defaults" section, it can be disabled
6851 in a specific instance by prepending the "no" keyword before it.
6852
Christopher Faulet315b39c2018-09-21 16:26:19 +02006853 See also : "option http-server-close" and "1.1. The HTTP transaction model".
Willy Tarreauc27debf2008-01-06 08:57:02 +01006854
6855
Emeric Brun3a058f32009-06-30 18:26:00 +02006856option httplog [ clf ]
Willy Tarreauc27debf2008-01-06 08:57:02 +01006857 Enable logging of HTTP request, session state and timers
6858 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01006859 yes | yes | yes | no
Emeric Brun3a058f32009-06-30 18:26:00 +02006860 Arguments :
6861 clf if the "clf" argument is added, then the output format will be
6862 the CLF format instead of HAProxy's default HTTP format. You can
6863 use this when you need to feed HAProxy's logs through a specific
Davor Ocelice9ed2812017-12-25 17:49:28 +01006864 log analyzer which only support the CLF format and which is not
Emeric Brun3a058f32009-06-30 18:26:00 +02006865 extensible.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006866
6867 By default, the log output format is very poor, as it only contains the
6868 source and destination addresses, and the instance name. By specifying
6869 "option httplog", each log line turns into a much richer format including,
6870 but not limited to, the HTTP request, the connection timers, the session
6871 status, the connections numbers, the captured headers and cookies, the
6872 frontend, backend and server name, and of course the source address and
6873 ports.
6874
PiBa-NLbd556bf2014-12-11 21:31:54 +01006875 Specifying only "option httplog" will automatically clear the 'clf' mode
6876 if it was set by default.
Emeric Brun3a058f32009-06-30 18:26:00 +02006877
Guillaume de Lafond29f45602017-03-31 19:52:15 +02006878 "option httplog" overrides any previous "log-format" directive.
6879
Willy Tarreauc57f0e22009-05-10 13:12:33 +02006880 See also : section 8 about logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01006881
Willy Tarreau55165fe2009-05-10 12:02:55 +02006882
6883option http_proxy
6884no option http_proxy
6885 Enable or disable plain HTTP proxy mode
6886 May be used in sections : defaults | frontend | listen | backend
6887 yes | yes | yes | yes
6888 Arguments : none
6889
6890 It sometimes happens that people need a pure HTTP proxy which understands
6891 basic proxy requests without caching nor any fancy feature. In this case,
6892 it may be worth setting up an HAProxy instance with the "option http_proxy"
6893 set. In this mode, no server is declared, and the connection is forwarded to
6894 the IP address and port found in the URL after the "http://" scheme.
6895
6896 No host address resolution is performed, so this only works when pure IP
6897 addresses are passed. Since this option's usage perimeter is rather limited,
Lukas Tribusf01a9cd2016-02-03 18:09:37 +01006898 it will probably be used only by experts who know they need exactly it. This
6899 is incompatible with the HTTP tunnel mode.
Willy Tarreau55165fe2009-05-10 12:02:55 +02006900
6901 If this option has been enabled in a "defaults" section, it can be disabled
6902 in a specific instance by prepending the "no" keyword before it.
6903
6904 Example :
6905 # this backend understands HTTP proxy requests and forwards them directly.
6906 backend direct_forward
6907 option httpclose
6908 option http_proxy
6909
6910 See also : "option httpclose"
6911
Willy Tarreau211ad242009-10-03 21:45:07 +02006912
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006913option independent-streams
6914no option independent-streams
6915 Enable or disable independent timeout processing for both directions
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006916 May be used in sections : defaults | frontend | listen | backend
6917 yes | yes | yes | yes
6918 Arguments : none
6919
6920 By default, when data is sent over a socket, both the write timeout and the
6921 read timeout for that socket are refreshed, because we consider that there is
6922 activity on that socket, and we have no other means of guessing if we should
6923 receive data or not.
6924
Davor Ocelice9ed2812017-12-25 17:49:28 +01006925 While this default behavior is desirable for almost all applications, there
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006926 exists a situation where it is desirable to disable it, and only refresh the
6927 read timeout if there are incoming data. This happens on sessions with large
6928 timeouts and low amounts of exchanged data such as telnet session. If the
6929 server suddenly disappears, the output data accumulates in the system's
6930 socket buffers, both timeouts are correctly refreshed, and there is no way
6931 to know the server does not receive them, so we don't timeout. However, when
6932 the underlying protocol always echoes sent data, it would be enough by itself
6933 to detect the issue using the read timeout. Note that this problem does not
6934 happen with more verbose protocols because data won't accumulate long in the
6935 socket buffers.
6936
6937 When this option is set on the frontend, it will disable read timeout updates
6938 on data sent to the client. There probably is little use of this case. When
6939 the option is set on the backend, it will disable read timeout updates on
6940 data sent to the server. Doing so will typically break large HTTP posts from
6941 slow lines, so use it with caution.
6942
Lukas Tribus745f15e2018-11-08 12:41:42 +01006943 Note: older versions used to call this setting "option independant-streams"
Jamie Gloudon801a0a32012-08-25 00:18:33 -04006944 with a spelling mistake. This spelling is still supported but
6945 deprecated.
6946
Willy Tarreauce887fd2012-05-12 12:50:00 +02006947 See also : "timeout client", "timeout server" and "timeout tunnel"
Willy Tarreauf27b5ea2009-10-03 22:01:18 +02006948
6949
Gabor Lekenyb4c81e42010-09-29 18:17:05 +02006950option ldap-check
6951 Use LDAPv3 health checks for server testing
6952 May be used in sections : defaults | frontend | listen | backend
6953 yes | no | yes | yes
6954 Arguments : none
6955
6956 It is possible to test that the server correctly talks LDAPv3 instead of just
6957 testing that it accepts the TCP connection. When this option is set, an
6958 LDAPv3 anonymous simple bind message is sent to the server, and the response
6959 is analyzed to find an LDAPv3 bind response message.
6960
6961 The server is considered valid only when the LDAP response contains success
6962 resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9).
6963
6964 Logging of bind requests is server dependent see your documentation how to
6965 configure it.
6966
6967 Example :
6968 option ldap-check
6969
6970 See also : "option httpchk"
6971
6972
Simon Horman98637e52014-06-20 12:30:16 +09006973option external-check
6974 Use external processes for server health checks
6975 May be used in sections : defaults | frontend | listen | backend
6976 yes | no | yes | yes
6977
6978 It is possible to test the health of a server using an external command.
6979 This is achieved by running the executable set using "external-check
6980 command".
6981
6982 Requires the "external-check" global to be set.
6983
6984 See also : "external-check", "external-check command", "external-check path"
6985
6986
Willy Tarreau211ad242009-10-03 21:45:07 +02006987option log-health-checks
6988no option log-health-checks
Willy Tarreaubef1b322014-05-13 21:01:39 +02006989 Enable or disable logging of health checks status updates
Willy Tarreau211ad242009-10-03 21:45:07 +02006990 May be used in sections : defaults | frontend | listen | backend
6991 yes | no | yes | yes
6992 Arguments : none
6993
Willy Tarreaubef1b322014-05-13 21:01:39 +02006994 By default, failed health check are logged if server is UP and successful
6995 health checks are logged if server is DOWN, so the amount of additional
6996 information is limited.
Willy Tarreau211ad242009-10-03 21:45:07 +02006997
Willy Tarreaubef1b322014-05-13 21:01:39 +02006998 When this option is enabled, any change of the health check status or to
6999 the server's health will be logged, so that it becomes possible to know
7000 that a server was failing occasional checks before crashing, or exactly when
7001 it failed to respond a valid HTTP status, then when the port started to
7002 reject connections, then when the server stopped responding at all.
7003
Davor Ocelice9ed2812017-12-25 17:49:28 +01007004 Note that status changes not caused by health checks (e.g. enable/disable on
Willy Tarreaubef1b322014-05-13 21:01:39 +02007005 the CLI) are intentionally not logged by this option.
Willy Tarreau211ad242009-10-03 21:45:07 +02007006
Willy Tarreaubef1b322014-05-13 21:01:39 +02007007 See also: "option httpchk", "option ldap-check", "option mysql-check",
7008 "option pgsql-check", "option redis-check", "option smtpchk",
7009 "option tcp-check", "log" and section 8 about logging.
Willy Tarreau211ad242009-10-03 21:45:07 +02007010
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02007011
7012option log-separate-errors
7013no option log-separate-errors
7014 Change log level for non-completely successful connections
7015 May be used in sections : defaults | frontend | listen | backend
7016 yes | yes | yes | no
7017 Arguments : none
7018
7019 Sometimes looking for errors in logs is not easy. This option makes haproxy
7020 raise the level of logs containing potentially interesting information such
7021 as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The
7022 level changes from "info" to "err". This makes it possible to log them
7023 separately to a different file with most syslog daemons. Be careful not to
7024 remove them from the original file, otherwise you would lose ordering which
7025 provides very important information.
7026
7027 Using this option, large sites dealing with several thousand connections per
7028 second may log normal traffic to a rotating buffer and only archive smaller
7029 error logs.
7030
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007031 See also : "log", "dontlognull", "dontlog-normal" and section 8 about
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +02007032 logging.
7033
Willy Tarreauc27debf2008-01-06 08:57:02 +01007034
7035option logasap
7036no option logasap
Jerome Magnina1d4a732020-04-23 19:01:17 +02007037 Enable or disable early logging.
Willy Tarreauc27debf2008-01-06 08:57:02 +01007038 May be used in sections : defaults | frontend | listen | backend
7039 yes | yes | yes | no
7040 Arguments : none
7041
Jerome Magnina1d4a732020-04-23 19:01:17 +02007042 By default, logs are emitted when all the log format variables and sample
7043 fetches used in the definition of the log-format string return a value, or
7044 when the session is terminated. This allows the built in log-format strings
7045 to account for the transfer time, or the number of bytes in log messages.
7046
7047 When handling long lived connections such as large file transfers or RDP,
7048 it may take a while for the request or connection to appear in the logs.
7049 Using "option logasap", the log message is created as soon as the server
7050 connection is established in mode tcp, or as soon as the server sends the
7051 complete headers in mode http. Missing information in the logs will be the
7052 total number of bytes which will only indicate the amount of data transfered
7053 before the message was created and the total time which will not take the
7054 remainder of the connection life or transfer time into account. For the case
7055 of HTTP, it is good practice to capture the Content-Length response header
7056 so that the logs at least indicate how many bytes are expected to be
7057 transfered.
Willy Tarreauc27debf2008-01-06 08:57:02 +01007058
Willy Tarreaucc6c8912009-02-22 10:53:55 +01007059 Examples :
7060 listen http_proxy 0.0.0.0:80
7061 mode http
7062 option httplog
7063 option logasap
7064 log 192.168.2.200 local3
7065
7066 >>> Feb 6 12:14:14 localhost \
7067 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
7068 static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \
7069 "GET /image.iso HTTP/1.0"
7070
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007071 See also : "option httplog", "capture response header", and section 8 about
Willy Tarreauc27debf2008-01-06 08:57:02 +01007072 logging.
7073
7074
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02007075option mysql-check [ user <username> [ post-41 ] ]
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02007076 Use MySQL health checks for server testing
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01007077 May be used in sections : defaults | frontend | listen | backend
7078 yes | no | yes | yes
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02007079 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +02007080 <username> This is the username which will be used when connecting to MySQL
7081 server.
Nenad Merdanovic6639a7c2014-05-30 14:26:32 +02007082 post-41 Send post v4.1 client compatible checks
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02007083
7084 If you specify a username, the check consists of sending two MySQL packet,
7085 one Client Authentication packet, and one QUIT packet, to correctly close
Davor Ocelice9ed2812017-12-25 17:49:28 +01007086 MySQL session. We then parse the MySQL Handshake Initialization packet and/or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02007087 Error packet. It is a basic but useful test which does not produce error nor
7088 aborted connect on the server. However, it requires adding an authorization
7089 in the MySQL table, like this :
7090
7091 USE mysql;
7092 INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>');
7093 FLUSH PRIVILEGES;
7094
7095 If you don't specify a username (it is deprecated and not recommended), the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007096 check only consists in parsing the Mysql Handshake Initialization packet or
Hervé COMMOWICK8776f1b2010-10-18 15:58:36 +02007097 Error packet, we don't send anything in this mode. It was reported that it
7098 can generate lockout if check is too frequent and/or if there is not enough
7099 traffic. In fact, you need in this case to check MySQL "max_connect_errors"
7100 value as if a connection is established successfully within fewer than MySQL
7101 "max_connect_errors" attempts after a previous connection was interrupted,
7102 the error count for the host is cleared to zero. If HAProxy's server get
7103 blocked, the "FLUSH HOSTS" statement is the only way to unblock it.
7104
7105 Remember that this does not check database presence nor database consistency.
7106 To do this, you can use an external check with xinetd for example.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01007107
Hervé COMMOWICK212f7782011-06-10 14:05:59 +02007108 The check requires MySQL >=3.22, for older version, please use TCP check.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01007109
7110 Most often, an incoming MySQL server needs to see the client's IP address for
7111 various purposes, including IP privilege matching and connection logging.
7112 When possible, it is often wise to masquerade the client's IP address when
7113 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02007114 which requires the transparent proxy feature to be compiled in, and the MySQL
7115 server to route the client via the machine hosting haproxy.
Hervé COMMOWICK698ae002010-01-12 09:25:13 +01007116
7117 See also: "option httpchk"
7118
7119
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007120option nolinger
7121no option nolinger
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007122 Enable or disable immediate session resource cleaning after close
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007123 May be used in sections: defaults | frontend | listen | backend
7124 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007125 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007126
Davor Ocelice9ed2812017-12-25 17:49:28 +01007127 When clients or servers abort connections in a dirty way (e.g. they are
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007128 physically disconnected), the session timeouts triggers and the session is
7129 closed. But it will remain in FIN_WAIT1 state for some time in the system,
7130 using some resources and possibly limiting the ability to establish newer
7131 connections.
7132
7133 When this happens, it is possible to activate "option nolinger" which forces
7134 the system to immediately remove any socket's pending data on close. Thus,
7135 the session is instantly purged from the system's tables. This usually has
7136 side effects such as increased number of TCP resets due to old retransmits
7137 getting immediately rejected. Some firewalls may sometimes complain about
7138 this too.
7139
7140 For this reason, it is not recommended to use this option when not absolutely
7141 needed. You know that you need it when you have thousands of FIN_WAIT1
7142 sessions on your system (TIME_WAIT ones do not count).
7143
7144 This option may be used both on frontends and backends, depending on the side
7145 where it is required. Use it on the frontend for clients, and on the backend
7146 for servers.
7147
7148 If this option has been enabled in a "defaults" section, it can be disabled
7149 in a specific instance by prepending the "no" keyword before it.
7150
7151
Willy Tarreau55165fe2009-05-10 12:02:55 +02007152option originalto [ except <network> ] [ header <name> ]
7153 Enable insertion of the X-Original-To header to requests sent to servers
7154 May be used in sections : defaults | frontend | listen | backend
7155 yes | yes | yes | yes
7156 Arguments :
7157 <network> is an optional argument used to disable this option for sources
7158 matching <network>
7159 <name> an optional argument to specify a different "X-Original-To"
7160 header name.
7161
7162 Since HAProxy can work in transparent mode, every request from a client can
7163 be redirected to the proxy and HAProxy itself can proxy every request to a
7164 complex SQUID environment and the destination host from SO_ORIGINAL_DST will
7165 be lost. This is annoying when you want access rules based on destination ip
7166 addresses. To solve this problem, a new HTTP header "X-Original-To" may be
7167 added by HAProxy to all requests sent to the server. This header contains a
7168 value representing the original destination IP address. Since this must be
7169 configured to always use the last occurrence of this header only. Note that
7170 only the last occurrence of the header must be used, since it is really
7171 possible that the client has already brought one.
7172
7173 The keyword "header" may be used to supply a different header name to replace
7174 the default "X-Original-To". This can be useful where you might already
7175 have a "X-Original-To" header from a different application, and you need
7176 preserve it. Also if your backend server doesn't use the "X-Original-To"
7177 header and requires different one.
7178
7179 Sometimes, a same HAProxy instance may be shared between a direct client
7180 access and a reverse-proxy access (for instance when an SSL reverse-proxy is
7181 used to decrypt HTTPS traffic). It is possible to disable the addition of the
7182 header for a known source address or network by adding the "except" keyword
7183 followed by the network address. In this case, any source IP matching the
7184 network will not cause an addition of this header. Most common uses are with
7185 private networks or 127.0.0.1.
7186
7187 This option may be specified either in the frontend or in the backend. If at
7188 least one of them uses it, the header will be added. Note that the backend's
7189 setting of the header subargument takes precedence over the frontend's if
7190 both are defined.
7191
Willy Tarreau55165fe2009-05-10 12:02:55 +02007192 Examples :
7193 # Original Destination address
7194 frontend www
7195 mode http
7196 option originalto except 127.0.0.1
7197
7198 # Those servers want the IP Address in X-Client-Dst
7199 backend www
7200 mode http
7201 option originalto header X-Client-Dst
7202
Christopher Faulet315b39c2018-09-21 16:26:19 +02007203 See also : "option httpclose", "option http-server-close".
Willy Tarreau55165fe2009-05-10 12:02:55 +02007204
7205
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007206option persist
7207no option persist
7208 Enable or disable forced persistence on down servers
7209 May be used in sections: defaults | frontend | listen | backend
7210 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007211 Arguments : none
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007212
7213 When an HTTP request reaches a backend with a cookie which references a dead
7214 server, by default it is redispatched to another server. It is possible to
7215 force the request to be sent to the dead server first using "option persist"
7216 if absolutely needed. A common use case is when servers are under extreme
7217 load and spend their time flapping. In this case, the users would still be
7218 directed to the server they opened the session on, in the hope they would be
7219 correctly served. It is recommended to use "option redispatch" in conjunction
7220 with this option so that in the event it would not be possible to connect to
7221 the server at all (server definitely dead), the client would finally be
7222 redirected to another valid server.
7223
7224 If this option has been enabled in a "defaults" section, it can be disabled
7225 in a specific instance by prepending the "no" keyword before it.
7226
Willy Tarreau4de91492010-01-22 19:10:05 +01007227 See also : "option redispatch", "retries", "force-persist"
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007228
7229
Willy Tarreau0c122822013-12-15 18:49:01 +01007230option pgsql-check [ user <username> ]
7231 Use PostgreSQL health checks for server testing
7232 May be used in sections : defaults | frontend | listen | backend
7233 yes | no | yes | yes
7234 Arguments :
7235 <username> This is the username which will be used when connecting to
7236 PostgreSQL server.
7237
7238 The check sends a PostgreSQL StartupMessage and waits for either
7239 Authentication request or ErrorResponse message. It is a basic but useful
7240 test which does not produce error nor aborted connect on the server.
7241 This check is identical with the "mysql-check".
7242
7243 See also: "option httpchk"
7244
7245
Willy Tarreau9420b122013-12-15 18:58:25 +01007246option prefer-last-server
7247no option prefer-last-server
7248 Allow multiple load balanced requests to remain on the same server
7249 May be used in sections: defaults | frontend | listen | backend
7250 yes | no | yes | yes
7251 Arguments : none
7252
7253 When the load balancing algorithm in use is not deterministic, and a previous
7254 request was sent to a server to which haproxy still holds a connection, it is
7255 sometimes desirable that subsequent requests on a same session go to the same
7256 server as much as possible. Note that this is different from persistence, as
7257 we only indicate a preference which haproxy tries to apply without any form
7258 of warranty. The real use is for keep-alive connections sent to servers. When
7259 this option is used, haproxy will try to reuse the same connection that is
7260 attached to the server instead of rebalancing to another server, causing a
7261 close of the connection. This can make sense for static file servers. It does
Willy Tarreau068621e2013-12-23 15:11:25 +01007262 not make much sense to use this in combination with hashing algorithms. Note,
7263 haproxy already automatically tries to stick to a server which sends a 401 or
Lukas Tribus80512b12018-10-27 20:07:40 +02007264 to a proxy which sends a 407 (authentication required), when the load
7265 balancing algorithm is not deterministic. This is mandatory for use with the
7266 broken NTLM authentication challenge, and significantly helps in
Willy Tarreau068621e2013-12-23 15:11:25 +01007267 troubleshooting some faulty applications. Option prefer-last-server might be
7268 desirable in these environments as well, to avoid redistributing the traffic
7269 after every other response.
Willy Tarreau9420b122013-12-15 18:58:25 +01007270
7271 If this option has been enabled in a "defaults" section, it can be disabled
7272 in a specific instance by prepending the "no" keyword before it.
7273
7274 See also: "option http-keep-alive"
7275
7276
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007277option redispatch
Joseph Lynch726ab712015-05-11 23:25:34 -07007278option redispatch <interval>
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007279no option redispatch
7280 Enable or disable session redistribution in case of connection failure
7281 May be used in sections: defaults | frontend | listen | backend
7282 yes | no | yes | yes
Joseph Lynch726ab712015-05-11 23:25:34 -07007283 Arguments :
7284 <interval> The optional integer value that controls how often redispatches
7285 occur when retrying connections. Positive value P indicates a
7286 redispatch is desired on every Pth retry, and negative value
Davor Ocelice9ed2812017-12-25 17:49:28 +01007287 N indicate a redispatch is desired on the Nth retry prior to the
Joseph Lynch726ab712015-05-11 23:25:34 -07007288 last retry. For example, the default of -1 preserves the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007289 historical behavior of redispatching on the last retry, a
Joseph Lynch726ab712015-05-11 23:25:34 -07007290 positive value of 1 would indicate a redispatch on every retry,
7291 and a positive value of 3 would indicate a redispatch on every
7292 third retry. You can disable redispatches with a value of 0.
7293
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007294
7295 In HTTP mode, if a server designated by a cookie is down, clients may
7296 definitely stick to it because they cannot flush the cookie, so they will not
7297 be able to access the service anymore.
7298
Willy Tarreau59884a62019-01-02 14:48:31 +01007299 Specifying "option redispatch" will allow the proxy to break cookie or
7300 consistent hash based persistence and redistribute them to a working server.
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007301
Joseph Lynch726ab712015-05-11 23:25:34 -07007302 It also allows to retry connections to another server in case of multiple
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007303 connection failures. Of course, it requires having "retries" set to a nonzero
7304 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01007305
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007306 This form is the preferred form, which replaces both the "redispatch" and
7307 "redisp" keywords.
7308
7309 If this option has been enabled in a "defaults" section, it can be disabled
7310 in a specific instance by prepending the "no" keyword before it.
7311
Willy Tarreau4de91492010-01-22 19:10:05 +01007312 See also : "redispatch", "retries", "force-persist"
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007313
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007314
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02007315option redis-check
7316 Use redis health checks for server testing
7317 May be used in sections : defaults | frontend | listen | backend
7318 yes | no | yes | yes
7319 Arguments : none
7320
7321 It is possible to test that the server correctly talks REDIS protocol instead
7322 of just testing that it accepts the TCP connection. When this option is set,
7323 a PING redis command is sent to the server, and the response is analyzed to
7324 find the "+PONG" response message.
7325
7326 Example :
7327 option redis-check
7328
Jarno Huuskonene5ae7022017-04-03 14:36:21 +03007329 See also : "option httpchk", "option tcp-check", "tcp-check expect"
Hervé COMMOWICKec032d62011-08-05 16:23:48 +02007330
7331
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007332option smtpchk
7333option smtpchk <hello> <domain>
7334 Use SMTP health checks for server testing
7335 May be used in sections : defaults | frontend | listen | backend
7336 yes | no | yes | yes
Willy Tarreaud72758d2010-01-12 10:42:19 +01007337 Arguments :
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007338 <hello> is an optional argument. It is the "hello" command to use. It can
Lukas Tribus27935782018-10-01 02:00:16 +02007339 be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007340 values will be turned into the default command ("HELO").
7341
7342 <domain> is the domain name to present to the server. It may only be
7343 specified (and is mandatory) if the hello command has been
7344 specified. By default, "localhost" is used.
7345
7346 When "option smtpchk" is set, the health checks will consist in TCP
7347 connections followed by an SMTP command. By default, this command is
7348 "HELO localhost". The server's return code is analyzed and only return codes
7349 starting with a "2" will be considered as valid. All other responses,
7350 including a lack of response will constitute an error and will indicate a
7351 dead server.
7352
7353 This test is meant to be used with SMTP servers or relays. Depending on the
7354 request, it is possible that some servers do not log each connection attempt,
Davor Ocelice9ed2812017-12-25 17:49:28 +01007355 so you may want to experiment to improve the behavior. Using telnet on port
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007356 25 is often easier than adjusting the configuration.
7357
7358 Most often, an incoming SMTP server needs to see the client's IP address for
7359 various purposes, including spam filtering, anti-spoofing and logging. When
7360 possible, it is often wise to masquerade the client's IP address when
7361 connecting to the server using the "usesrc" argument of the "source" keyword,
Willy Tarreau29fbe512015-08-20 19:35:14 +02007362 which requires the transparent proxy feature to be compiled in.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007363
7364 Example :
7365 option smtpchk HELO mydomain.org
7366
7367 See also : "option httpchk", "source"
7368
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01007369
Krzysztof Piotr Oledzkiaeebf9b2009-10-04 15:43:17 +02007370option socket-stats
7371no option socket-stats
7372
7373 Enable or disable collecting & providing separate statistics for each socket.
7374 May be used in sections : defaults | frontend | listen | backend
7375 yes | yes | yes | no
7376
7377 Arguments : none
7378
7379
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007380option splice-auto
7381no option splice-auto
7382 Enable or disable automatic kernel acceleration on sockets in both directions
7383 May be used in sections : defaults | frontend | listen | backend
7384 yes | yes | yes | yes
7385 Arguments : none
7386
7387 When this option is enabled either on a frontend or on a backend, haproxy
7388 will automatically evaluate the opportunity to use kernel tcp splicing to
Davor Ocelice9ed2812017-12-25 17:49:28 +01007389 forward data between the client and the server, in either direction. HAProxy
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007390 uses heuristics to estimate if kernel splicing might improve performance or
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007391 not. Both directions are handled independently. Note that the heuristics used
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007392 are not much aggressive in order to limit excessive use of splicing. This
7393 option requires splicing to be enabled at compile time, and may be globally
7394 disabled with the global option "nosplice". Since splice uses pipes, using it
7395 requires that there are enough spare pipes.
7396
7397 Important note: kernel-based TCP splicing is a Linux-specific feature which
7398 first appeared in kernel 2.6.25. It offers kernel-based acceleration to
7399 transfer data between sockets without copying these data to user-space, thus
7400 providing noticeable performance gains and CPU cycles savings. Since many
7401 early implementations are buggy, corrupt data and/or are inefficient, this
7402 feature is not enabled by default, and it should be used with extreme care.
7403 While it is not possible to detect the correctness of an implementation,
7404 2.6.29 is the first version offering a properly working implementation. In
7405 case of doubt, splicing may be globally disabled using the global "nosplice"
7406 keyword.
7407
7408 Example :
7409 option splice-auto
7410
7411 If this option has been enabled in a "defaults" section, it can be disabled
7412 in a specific instance by prepending the "no" keyword before it.
7413
7414 See also : "option splice-request", "option splice-response", and global
7415 options "nosplice" and "maxpipes"
7416
7417
7418option splice-request
7419no option splice-request
7420 Enable or disable automatic kernel acceleration on sockets for requests
7421 May be used in sections : defaults | frontend | listen | backend
7422 yes | yes | yes | yes
7423 Arguments : none
7424
7425 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007426 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007427 the client to the server. It might still use the recv/send scheme if there
7428 are no spare pipes left. This option requires splicing to be enabled at
7429 compile time, and may be globally disabled with the global option "nosplice".
7430 Since splice uses pipes, using it requires that there are enough spare pipes.
7431
7432 Important note: see "option splice-auto" for usage limitations.
7433
7434 Example :
7435 option splice-request
7436
7437 If this option has been enabled in a "defaults" section, it can be disabled
7438 in a specific instance by prepending the "no" keyword before it.
7439
7440 See also : "option splice-auto", "option splice-response", and global options
7441 "nosplice" and "maxpipes"
7442
7443
7444option splice-response
7445no option splice-response
7446 Enable or disable automatic kernel acceleration on sockets for responses
7447 May be used in sections : defaults | frontend | listen | backend
7448 yes | yes | yes | yes
7449 Arguments : none
7450
7451 When this option is enabled either on a frontend or on a backend, haproxy
Jamie Gloudonaaa21002012-08-25 00:18:33 -04007452 will use kernel tcp splicing whenever possible to forward data going from
Willy Tarreauff4f82d2009-02-06 11:28:13 +01007453 the server to the client. It might still use the recv/send scheme if there
7454 are no spare pipes left. This option requires splicing to be enabled at
7455 compile time, and may be globally disabled with the global option "nosplice".
7456 Since splice uses pipes, using it requires that there are enough spare pipes.
7457
7458 Important note: see "option splice-auto" for usage limitations.
7459
7460 Example :
7461 option splice-response
7462
7463 If this option has been enabled in a "defaults" section, it can be disabled
7464 in a specific instance by prepending the "no" keyword before it.
7465
7466 See also : "option splice-auto", "option splice-request", and global options
7467 "nosplice" and "maxpipes"
7468
7469
Christopher Fauletba7bc162016-11-07 21:07:38 +01007470option spop-check
7471 Use SPOP health checks for server testing
7472 May be used in sections : defaults | frontend | listen | backend
7473 no | no | no | yes
7474 Arguments : none
7475
7476 It is possible to test that the server correctly talks SPOP protocol instead
7477 of just testing that it accepts the TCP connection. When this option is set,
7478 a HELLO handshake is performed between HAProxy and the server, and the
7479 response is analyzed to check no error is reported.
7480
7481 Example :
7482 option spop-check
7483
7484 See also : "option httpchk"
7485
7486
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007487option srvtcpka
7488no option srvtcpka
7489 Enable or disable the sending of TCP keepalive packets on the server side
7490 May be used in sections : defaults | frontend | listen | backend
7491 yes | no | yes | yes
7492 Arguments : none
7493
7494 When there is a firewall or any session-aware component between a client and
7495 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01007496 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007497 components decides to expire a session which has remained idle for too long.
7498
7499 Enabling socket-level TCP keep-alives makes the system regularly send packets
7500 to the other end of the connection, leaving it active. The delay between
7501 keep-alive probes is controlled by the system only and depends both on the
7502 operating system and its tuning parameters.
7503
7504 It is important to understand that keep-alive packets are neither emitted nor
7505 received at the application level. It is only the network stacks which sees
7506 them. For this reason, even if one side of the proxy already uses keep-alives
7507 to maintain its connection alive, those keep-alive packets will not be
7508 forwarded to the other side of the proxy.
7509
7510 Please note that this has nothing to do with HTTP keep-alive.
7511
7512 Using option "srvtcpka" enables the emission of TCP keep-alive probes on the
7513 server side of a connection, which should help when session expirations are
7514 noticed between HAProxy and a server.
7515
7516 If this option has been enabled in a "defaults" section, it can be disabled
7517 in a specific instance by prepending the "no" keyword before it.
7518
7519 See also : "option clitcpka", "option tcpka"
7520
7521
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007522option ssl-hello-chk
7523 Use SSLv3 client hello health checks for server testing
7524 May be used in sections : defaults | frontend | listen | backend
7525 yes | no | yes | yes
7526 Arguments : none
7527
7528 When some SSL-based protocols are relayed in TCP mode through HAProxy, it is
7529 possible to test that the server correctly talks SSL instead of just testing
7530 that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure
7531 SSLv3 client hello messages are sent once the connection is established to
7532 the server, and the response is analyzed to find an SSL server hello message.
7533 The server is considered valid only when the response contains this server
7534 hello message.
7535
7536 All servers tested till there correctly reply to SSLv3 client hello messages,
7537 and most servers tested do not even log the requests containing only hello
7538 messages, which is appreciable.
7539
Willy Tarreau763a95b2012-10-04 23:15:39 +02007540 Note that this check works even when SSL support was not built into haproxy
7541 because it forges the SSL message. When SSL support is available, it is best
7542 to use native SSL health checks instead of this one.
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007543
Willy Tarreau763a95b2012-10-04 23:15:39 +02007544 See also: "option httpchk", "check-ssl"
7545
Willy Tarreaua453bdd2008-01-08 19:50:52 +01007546
Willy Tarreaued179852013-12-16 01:07:00 +01007547option tcp-check
7548 Perform health checks using tcp-check send/expect sequences
7549 May be used in sections: defaults | frontend | listen | backend
7550 yes | no | yes | yes
7551
7552 This health check method is intended to be combined with "tcp-check" command
7553 lists in order to support send/expect types of health check sequences.
7554
7555 TCP checks currently support 4 modes of operations :
7556 - no "tcp-check" directive : the health check only consists in a connection
7557 attempt, which remains the default mode.
7558
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007559 - "tcp-check send" or "tcp-check send-binary" only is mentioned : this is
Willy Tarreaued179852013-12-16 01:07:00 +01007560 used to send a string along with a connection opening. With some
7561 protocols, it helps sending a "QUIT" message for example that prevents
7562 the server from logging a connection error for each health check. The
7563 check result will still be based on the ability to open the connection
7564 only.
7565
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007566 - "tcp-check expect" only is mentioned : this is used to test a banner.
Willy Tarreaued179852013-12-16 01:07:00 +01007567 The connection is opened and haproxy waits for the server to present some
7568 contents which must validate some rules. The check result will be based
7569 on the matching between the contents and the rules. This is suited for
7570 POP, IMAP, SMTP, FTP, SSH, TELNET.
7571
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007572 - both "tcp-check send" and "tcp-check expect" are mentioned : this is
Davor Ocelice9ed2812017-12-25 17:49:28 +01007573 used to test a hello-type protocol. HAProxy sends a message, the server
7574 responds and its response is analyzed. the check result will be based on
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007575 the matching between the response contents and the rules. This is often
Willy Tarreaued179852013-12-16 01:07:00 +01007576 suited for protocols which require a binding or a request/response model.
7577 LDAP, MySQL, Redis and SSL are example of such protocols, though they
7578 already all have their dedicated checks with a deeper understanding of
7579 the respective protocols.
7580 In this mode, many questions may be sent and many answers may be
Davor Ocelice9ed2812017-12-25 17:49:28 +01007581 analyzed.
Willy Tarreaued179852013-12-16 01:07:00 +01007582
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007583 A fifth mode can be used to insert comments in different steps of the
7584 script.
7585
7586 For each tcp-check rule you create, you can add a "comment" directive,
7587 followed by a string. This string will be reported in the log and stderr
7588 in debug mode. It is useful to make user-friendly error reporting.
7589 The "comment" is of course optional.
7590
7591
Willy Tarreaued179852013-12-16 01:07:00 +01007592 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01007593 # perform a POP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01007594 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007595 tcp-check expect string +OK\ POP3\ ready comment POP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01007596
Davor Ocelice9ed2812017-12-25 17:49:28 +01007597 # perform an IMAP check (analyze only server's banner)
Willy Tarreaued179852013-12-16 01:07:00 +01007598 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007599 tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol
Willy Tarreaued179852013-12-16 01:07:00 +01007600
7601 # look for the redis master server after ensuring it speaks well
7602 # redis protocol, then it exits properly.
Davor Ocelice9ed2812017-12-25 17:49:28 +01007603 # (send a command then analyze the response 3 times)
Willy Tarreaued179852013-12-16 01:07:00 +01007604 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007605 tcp-check comment PING\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01007606 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02007607 tcp-check expect string +PONG
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007608 tcp-check comment role\ check
Willy Tarreaued179852013-12-16 01:07:00 +01007609 tcp-check send info\ replication\r\n
7610 tcp-check expect string role:master
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007611 tcp-check comment QUIT\ phase
Willy Tarreaued179852013-12-16 01:07:00 +01007612 tcp-check send QUIT\r\n
7613 tcp-check expect string +OK
7614
Davor Ocelice9ed2812017-12-25 17:49:28 +01007615 forge a HTTP request, then analyze the response
Willy Tarreaued179852013-12-16 01:07:00 +01007616 (send many headers before analyzing)
7617 option tcp-check
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007618 tcp-check comment forge\ and\ send\ HTTP\ request
Willy Tarreaued179852013-12-16 01:07:00 +01007619 tcp-check send HEAD\ /\ HTTP/1.1\r\n
7620 tcp-check send Host:\ www.mydomain.com\r\n
7621 tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n
7622 tcp-check send \r\n
Baptiste Assmannd60a9e52015-04-25 16:27:23 +02007623 tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response
Willy Tarreaued179852013-12-16 01:07:00 +01007624
7625
7626 See also : "tcp-check expect", "tcp-check send"
7627
7628
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007629option tcp-smart-accept
7630no option tcp-smart-accept
7631 Enable or disable the saving of one ACK packet during the accept sequence
7632 May be used in sections : defaults | frontend | listen | backend
7633 yes | yes | yes | no
7634 Arguments : none
7635
7636 When an HTTP connection request comes in, the system acknowledges it on
7637 behalf of HAProxy, then the client immediately sends its request, and the
7638 system acknowledges it too while it is notifying HAProxy about the new
7639 connection. HAProxy then reads the request and responds. This means that we
7640 have one TCP ACK sent by the system for nothing, because the request could
7641 very well be acknowledged by HAProxy when it sends its response.
7642
7643 For this reason, in HTTP mode, HAProxy automatically asks the system to avoid
7644 sending this useless ACK on platforms which support it (currently at least
7645 Linux). It must not cause any problem, because the system will send it anyway
7646 after 40 ms if the response takes more time than expected to come.
7647
7648 During complex network debugging sessions, it may be desirable to disable
7649 this optimization because delayed ACKs can make troubleshooting more complex
7650 when trying to identify where packets are delayed. It is then possible to
Davor Ocelice9ed2812017-12-25 17:49:28 +01007651 fall back to normal behavior by specifying "no option tcp-smart-accept".
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007652
7653 It is also possible to force it for non-HTTP proxies by simply specifying
7654 "option tcp-smart-accept". For instance, it can make sense with some services
7655 such as SMTP where the server speaks first.
7656
7657 It is recommended to avoid forcing this option in a defaults section. In case
7658 of doubt, consider setting it back to automatic values by prepending the
7659 "default" keyword before it, or disabling it using the "no" keyword.
7660
Willy Tarreaud88edf22009-06-14 15:48:17 +02007661 See also : "option tcp-smart-connect"
7662
7663
7664option tcp-smart-connect
7665no option tcp-smart-connect
7666 Enable or disable the saving of one ACK packet during the connect sequence
7667 May be used in sections : defaults | frontend | listen | backend
7668 yes | no | yes | yes
7669 Arguments : none
7670
7671 On certain systems (at least Linux), HAProxy can ask the kernel not to
7672 immediately send an empty ACK upon a connection request, but to directly
7673 send the buffer request instead. This saves one packet on the network and
7674 thus boosts performance. It can also be useful for some servers, because they
7675 immediately get the request along with the incoming connection.
7676
7677 This feature is enabled when "option tcp-smart-connect" is set in a backend.
7678 It is not enabled by default because it makes network troubleshooting more
7679 complex.
7680
7681 It only makes sense to enable it with protocols where the client speaks first
7682 such as HTTP. In other situations, if there is no data to send in place of
7683 the ACK, a normal ACK is sent.
7684
7685 If this option has been enabled in a "defaults" section, it can be disabled
7686 in a specific instance by prepending the "no" keyword before it.
7687
7688 See also : "option tcp-smart-accept"
7689
Willy Tarreau9ea05a72009-06-14 12:07:01 +02007690
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007691option tcpka
7692 Enable or disable the sending of TCP keepalive packets on both sides
7693 May be used in sections : defaults | frontend | listen | backend
7694 yes | yes | yes | yes
7695 Arguments : none
7696
7697 When there is a firewall or any session-aware component between a client and
7698 a server, and when the protocol involves very long sessions with long idle
Davor Ocelice9ed2812017-12-25 17:49:28 +01007699 periods (e.g. remote desktops), there is a risk that one of the intermediate
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007700 components decides to expire a session which has remained idle for too long.
7701
7702 Enabling socket-level TCP keep-alives makes the system regularly send packets
7703 to the other end of the connection, leaving it active. The delay between
7704 keep-alive probes is controlled by the system only and depends both on the
7705 operating system and its tuning parameters.
7706
7707 It is important to understand that keep-alive packets are neither emitted nor
7708 received at the application level. It is only the network stacks which sees
7709 them. For this reason, even if one side of the proxy already uses keep-alives
7710 to maintain its connection alive, those keep-alive packets will not be
7711 forwarded to the other side of the proxy.
7712
7713 Please note that this has nothing to do with HTTP keep-alive.
7714
7715 Using option "tcpka" enables the emission of TCP keep-alive probes on both
7716 the client and server sides of a connection. Note that this is meaningful
7717 only in "defaults" or "listen" sections. If this option is used in a
7718 frontend, only the client side will get keep-alives, and if this option is
7719 used in a backend, only the server side will get keep-alives. For this
7720 reason, it is strongly recommended to explicitly use "option clitcpka" and
7721 "option srvtcpka" when the configuration is split between frontends and
7722 backends.
7723
7724 See also : "option clitcpka", "option srvtcpka"
7725
Willy Tarreau844e3c52008-01-11 16:28:18 +01007726
7727option tcplog
7728 Enable advanced logging of TCP connections with session state and timers
7729 May be used in sections : defaults | frontend | listen | backend
Tim Duesterhus9ad9f352018-02-05 20:52:27 +01007730 yes | yes | yes | no
Willy Tarreau844e3c52008-01-11 16:28:18 +01007731 Arguments : none
7732
7733 By default, the log output format is very poor, as it only contains the
7734 source and destination addresses, and the instance name. By specifying
7735 "option tcplog", each log line turns into a much richer format including, but
7736 not limited to, the connection timers, the session status, the connections
7737 numbers, the frontend, backend and server name, and of course the source
7738 address and ports. This option is useful for pure TCP proxies in order to
7739 find which of the client or server disconnects or times out. For normal HTTP
7740 proxies, it's better to use "option httplog" which is even more complete.
7741
Guillaume de Lafond29f45602017-03-31 19:52:15 +02007742 "option tcplog" overrides any previous "log-format" directive.
7743
Willy Tarreauc57f0e22009-05-10 13:12:33 +02007744 See also : "option httplog", and section 8 about logging.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007745
7746
Willy Tarreau844e3c52008-01-11 16:28:18 +01007747option transparent
7748no option transparent
7749 Enable client-side transparent proxying
7750 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +01007751 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +01007752 Arguments : none
7753
7754 This option was introduced in order to provide layer 7 persistence to layer 3
7755 load balancers. The idea is to use the OS's ability to redirect an incoming
7756 connection for a remote address to a local process (here HAProxy), and let
7757 this process know what address was initially requested. When this option is
7758 used, sessions without cookies will be forwarded to the original destination
7759 IP address of the incoming request (which should match that of another
7760 equipment), while requests with cookies will still be forwarded to the
7761 appropriate server.
7762
7763 Note that contrary to a common belief, this option does NOT make HAProxy
7764 present the client's IP to the server when establishing the connection.
7765
Willy Tarreaua1146052011-03-01 09:51:54 +01007766 See also: the "usesrc" argument of the "source" keyword, and the
Willy Tarreaueabeafa2008-01-16 16:17:06 +01007767 "transparent" option of the "bind" keyword.
Willy Tarreau844e3c52008-01-11 16:28:18 +01007768
Willy Tarreaubf1f8162007-12-28 17:42:56 +01007769
Simon Horman98637e52014-06-20 12:30:16 +09007770external-check command <command>
7771 Executable to run when performing an external-check
7772 May be used in sections : defaults | frontend | listen | backend
7773 yes | no | yes | yes
7774
7775 Arguments :
7776 <command> is the external command to run
7777
Simon Horman98637e52014-06-20 12:30:16 +09007778 The arguments passed to the to the command are:
7779
Cyril Bonté777be862014-12-02 21:21:35 +01007780 <proxy_address> <proxy_port> <server_address> <server_port>
Simon Horman98637e52014-06-20 12:30:16 +09007781
Cyril Bonté777be862014-12-02 21:21:35 +01007782 The <proxy_address> and <proxy_port> are derived from the first listener
7783 that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket
7784 listener the proxy_address will be the path of the socket and the
7785 <proxy_port> will be the string "NOT_USED". In a backend section, it's not
7786 possible to determine a listener, and both <proxy_address> and <proxy_port>
7787 will have the string value "NOT_USED".
Simon Horman98637e52014-06-20 12:30:16 +09007788
Cyril Bonté72cda2a2014-12-27 22:28:39 +01007789 Some values are also provided through environment variables.
7790
7791 Environment variables :
7792 HAPROXY_PROXY_ADDR The first bind address if available (or empty if not
7793 applicable, for example in a "backend" section).
7794
7795 HAPROXY_PROXY_ID The backend id.
7796
7797 HAPROXY_PROXY_NAME The backend name.
7798
7799 HAPROXY_PROXY_PORT The first bind port if available (or empty if not
7800 applicable, for example in a "backend" section or
7801 for a UNIX socket).
7802
7803 HAPROXY_SERVER_ADDR The server address.
7804
7805 HAPROXY_SERVER_CURCONN The current number of connections on the server.
7806
7807 HAPROXY_SERVER_ID The server id.
7808
7809 HAPROXY_SERVER_MAXCONN The server max connections.
7810
7811 HAPROXY_SERVER_NAME The server name.
7812
7813 HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX
7814 socket).
7815
7816 PATH The PATH environment variable used when executing
7817 the command may be set using "external-check path".
7818
William Lallemand4d03e432019-06-14 15:35:37 +02007819 See also "2.3. Environment variables" for other variables.
7820
Simon Horman98637e52014-06-20 12:30:16 +09007821 If the command executed and exits with a zero status then the check is
7822 considered to have passed, otherwise the check is considered to have
7823 failed.
7824
7825 Example :
7826 external-check command /bin/true
7827
7828 See also : "external-check", "option external-check", "external-check path"
7829
7830
7831external-check path <path>
7832 The value of the PATH environment variable used when running an external-check
7833 May be used in sections : defaults | frontend | listen | backend
7834 yes | no | yes | yes
7835
7836 Arguments :
7837 <path> is the path used when executing external command to run
7838
7839 The default path is "".
7840
7841 Example :
7842 external-check path "/usr/bin:/bin"
7843
7844 See also : "external-check", "option external-check",
7845 "external-check command"
7846
7847
Emeric Brun647caf12009-06-30 17:57:00 +02007848persist rdp-cookie
Hervé COMMOWICKa3eb39c2011-08-05 18:48:51 +02007849persist rdp-cookie(<name>)
Emeric Brun647caf12009-06-30 17:57:00 +02007850 Enable RDP cookie-based persistence
7851 May be used in sections : defaults | frontend | listen | backend
7852 yes | no | yes | yes
7853 Arguments :
7854 <name> is the optional name of the RDP cookie to check. If omitted, the
Willy Tarreau61e28f22010-05-16 22:31:05 +02007855 default cookie name "msts" will be used. There currently is no
7856 valid reason to change this name.
Emeric Brun647caf12009-06-30 17:57:00 +02007857
7858 This statement enables persistence based on an RDP cookie. The RDP cookie
7859 contains all information required to find the server in the list of known
Davor Ocelice9ed2812017-12-25 17:49:28 +01007860 servers. So when this option is set in the backend, the request is analyzed
Emeric Brun647caf12009-06-30 17:57:00 +02007861 and if an RDP cookie is found, it is decoded. If it matches a known server
7862 which is still UP (or if "option persist" is set), then the connection is
7863 forwarded to this server.
7864
7865 Note that this only makes sense in a TCP backend, but for this to work, the
7866 frontend must have waited long enough to ensure that an RDP cookie is present
7867 in the request buffer. This is the same requirement as with the "rdp-cookie"
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01007868 load-balancing method. Thus it is highly recommended to put all statements in
Emeric Brun647caf12009-06-30 17:57:00 +02007869 a single "listen" section.
7870
Willy Tarreau61e28f22010-05-16 22:31:05 +02007871 Also, it is important to understand that the terminal server will emit this
7872 RDP cookie only if it is configured for "token redirection mode", which means
7873 that the "IP address redirection" option is disabled.
7874
Emeric Brun647caf12009-06-30 17:57:00 +02007875 Example :
7876 listen tse-farm
7877 bind :3389
7878 # wait up to 5s for an RDP cookie in the request
7879 tcp-request inspect-delay 5s
7880 tcp-request content accept if RDP_COOKIE
7881 # apply RDP cookie persistence
7882 persist rdp-cookie
7883 # if server is unknown, let's balance on the same cookie.
Cyril Bontédc4d9032012-04-08 21:57:39 +02007884 # alternatively, "balance leastconn" may be useful too.
Emeric Brun647caf12009-06-30 17:57:00 +02007885 balance rdp-cookie
7886 server srv1 1.1.1.1:3389
7887 server srv2 1.1.1.2:3389
7888
Simon Hormanab814e02011-06-24 14:50:20 +09007889 See also : "balance rdp-cookie", "tcp-request", the "req_rdp_cookie" ACL and
7890 the rdp_cookie pattern fetch function.
Emeric Brun647caf12009-06-30 17:57:00 +02007891
7892
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007893rate-limit sessions <rate>
7894 Set a limit on the number of new sessions accepted per second on a frontend
7895 May be used in sections : defaults | frontend | listen | backend
7896 yes | yes | yes | no
7897 Arguments :
7898 <rate> The <rate> parameter is an integer designating the maximum number
7899 of new sessions per second to accept on the frontend.
7900
7901 When the frontend reaches the specified number of new sessions per second, it
7902 stops accepting new connections until the rate drops below the limit again.
7903 During this time, the pending sessions will be kept in the socket's backlog
7904 (in system buffers) and haproxy will not even be aware that sessions are
7905 pending. When applying very low limit on a highly loaded service, it may make
7906 sense to increase the socket's backlog using the "backlog" keyword.
7907
7908 This feature is particularly efficient at blocking connection-based attacks
7909 or service abuse on fragile servers. Since the session rate is measured every
7910 millisecond, it is extremely accurate. Also, the limit applies immediately,
7911 no delay is needed at all to detect the threshold.
7912
7913 Example : limit the connection rate on SMTP to 10 per second max
7914 listen smtp
7915 mode tcp
7916 bind :25
7917 rate-limit sessions 10
Panagiotis Panagiotopoulos7282d8e2016-02-11 16:37:15 +02007918 server smtp1 127.0.0.1:1025
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007919
Willy Tarreaua17c2d92011-07-25 08:16:20 +02007920 Note : when the maximum rate is reached, the frontend's status is not changed
7921 but its sockets appear as "WAITING" in the statistics if the
7922 "socket-stats" option is enabled.
Willy Tarreau3a7d2072009-03-05 23:48:25 +01007923
7924 See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion.
7925
7926
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007927redirect location <loc> [code <code>] <option> [{if | unless} <condition>]
7928redirect prefix <pfx> [code <code>] <option> [{if | unless} <condition>]
7929redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007930 Return an HTTP redirection if/unless a condition is matched
7931 May be used in sections : defaults | frontend | listen | backend
7932 no | yes | yes | yes
7933
7934 If/unless the condition is matched, the HTTP request will lead to a redirect
Willy Tarreauf285f542010-01-03 20:03:03 +01007935 response. If no condition is specified, the redirect applies unconditionally.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02007936
Willy Tarreau0140f252008-11-19 21:07:09 +01007937 Arguments :
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007938 <loc> With "redirect location", the exact value in <loc> is placed into
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007939 the HTTP "Location" header. When used in an "http-request" rule,
7940 <loc> value follows the log-format rules and can include some
7941 dynamic values (see Custom Log Format in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007942
7943 <pfx> With "redirect prefix", the "Location" header is built from the
7944 concatenation of <pfx> and the complete URI path, including the
7945 query string, unless the "drop-query" option is specified (see
7946 below). As a special case, if <pfx> equals exactly "/", then
7947 nothing is inserted before the original URI. It allows one to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007948 redirect to the same URL (for instance, to insert a cookie). When
7949 used in an "http-request" rule, <pfx> value follows the log-format
7950 rules and can include some dynamic values (see Custom Log Format
7951 in section 8.2.4).
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007952
7953 <sch> With "redirect scheme", then the "Location" header is built by
7954 concatenating <sch> with "://" then the first occurrence of the
7955 "Host" header, and then the URI path, including the query string
7956 unless the "drop-query" option is specified (see below). If no
7957 path is found or if the path is "*", then "/" is used instead. If
7958 no "Host" header is found, then an empty host component will be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03007959 returned, which most recent browsers interpret as redirecting to
Willy Tarreau2e1dca82012-09-12 08:43:15 +02007960 the same host. This directive is mostly used to redirect HTTP to
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01007961 HTTPS. When used in an "http-request" rule, <sch> value follows
7962 the log-format rules and can include some dynamic values (see
7963 Custom Log Format in section 8.2.4).
Willy Tarreau0140f252008-11-19 21:07:09 +01007964
7965 <code> The code is optional. It indicates which type of HTTP redirection
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007966 is desired. Only codes 301, 302, 303, 307 and 308 are supported,
7967 with 302 used by default if no code is specified. 301 means
7968 "Moved permanently", and a browser may cache the Location. 302
Baptiste Assmannea849c02015-08-03 11:42:50 +02007969 means "Moved temporarily" and means that the browser should not
Willy Tarreaub67fdc42013-03-29 19:28:11 +01007970 cache the redirection. 303 is equivalent to 302 except that the
7971 browser will fetch the location with a GET method. 307 is just
7972 like 302 but makes it clear that the same method must be reused.
7973 Likewise, 308 replaces 301 if the same method must be used.
Willy Tarreau0140f252008-11-19 21:07:09 +01007974
7975 <option> There are several options which can be specified to adjust the
Davor Ocelice9ed2812017-12-25 17:49:28 +01007976 expected behavior of a redirection :
Willy Tarreau0140f252008-11-19 21:07:09 +01007977
7978 - "drop-query"
7979 When this keyword is used in a prefix-based redirection, then the
7980 location will be set without any possible query-string, which is useful
7981 for directing users to a non-secure page for instance. It has no effect
7982 with a location-type redirect.
7983
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01007984 - "append-slash"
7985 This keyword may be used in conjunction with "drop-query" to redirect
7986 users who use a URL not ending with a '/' to the same one with the '/'.
7987 It can be useful to ensure that search engines will only see one URL.
7988 For this, a return code 301 is preferred.
7989
Willy Tarreau0140f252008-11-19 21:07:09 +01007990 - "set-cookie NAME[=value]"
7991 A "Set-Cookie" header will be added with NAME (and optionally "=value")
7992 to the response. This is sometimes used to indicate that a user has
7993 been seen, for instance to protect against some types of DoS. No other
7994 cookie option is added, so the cookie will be a session cookie. Note
7995 that for a browser, a sole cookie name without an equal sign is
7996 different from a cookie with an equal sign.
7997
7998 - "clear-cookie NAME[=]"
7999 A "Set-Cookie" header will be added with NAME (and optionally "="), but
8000 with the "Max-Age" attribute set to zero. This will tell the browser to
8001 delete this cookie. It is useful for instance on logout pages. It is
8002 important to note that clearing the cookie "NAME" will not remove a
8003 cookie set with "NAME=value". You have to clear the cookie "NAME=" for
8004 that, because the browser makes the difference.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02008005
8006 Example: move the login URL only to HTTPS.
8007 acl clear dst_port 80
8008 acl secure dst_port 8080
8009 acl login_page url_beg /login
Willy Tarreau0140f252008-11-19 21:07:09 +01008010 acl logout url_beg /logout
Willy Tarreau79da4692008-11-19 20:03:04 +01008011 acl uid_given url_reg /login?userid=[^&]+
Willy Tarreau0140f252008-11-19 21:07:09 +01008012 acl cookie_set hdr_sub(cookie) SEEN=1
8013
8014 redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set
Willy Tarreau79da4692008-11-19 20:03:04 +01008015 redirect prefix https://mysite.com if login_page !secure
8016 redirect prefix http://mysite.com drop-query if login_page !uid_given
8017 redirect location http://mysite.com/ if !login_page secure
Willy Tarreau0140f252008-11-19 21:07:09 +01008018 redirect location / clear-cookie USERID= if logout
Willy Tarreaub463dfb2008-06-07 23:08:56 +02008019
Willy Tarreau81e3b4f2010-01-10 00:42:19 +01008020 Example: send redirects for request for articles without a '/'.
8021 acl missing_slash path_reg ^/article/[^/]*$
8022 redirect code 301 prefix / drop-query append-slash if missing_slash
8023
Willy Tarreau2e1dca82012-09-12 08:43:15 +02008024 Example: redirect all HTTP traffic to HTTPS when SSL is handled by haproxy.
David BERARDe7153042012-11-03 00:11:31 +01008025 redirect scheme https if !{ ssl_fc }
Willy Tarreau2e1dca82012-09-12 08:43:15 +02008026
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01008027 Example: append 'www.' prefix in front of all hosts not having it
Coen Rosdorff596659b2016-04-11 11:33:49 +02008028 http-request redirect code 301 location \
8029 http://www.%[hdr(host)]%[capture.req.uri] \
8030 unless { hdr_beg(host) -i www }
Thierry FOURNIERd18cd0f2013-11-29 12:15:45 +01008031
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008032 See section 7 about ACL usage.
Willy Tarreaub463dfb2008-06-07 23:08:56 +02008033
8034
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008035redisp (deprecated)
8036redispatch (deprecated)
8037 Enable or disable session redistribution in case of connection failure
8038 May be used in sections: defaults | frontend | listen | backend
8039 yes | no | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008040 Arguments : none
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008041
8042 In HTTP mode, if a server designated by a cookie is down, clients may
8043 definitely stick to it because they cannot flush the cookie, so they will not
8044 be able to access the service anymore.
8045
8046 Specifying "redispatch" will allow the proxy to break their persistence and
8047 redistribute them to a working server.
8048
8049 It also allows to retry last connection to another server in case of multiple
8050 connection failures. Of course, it requires having "retries" set to a nonzero
8051 value.
Willy Tarreaud72758d2010-01-12 10:42:19 +01008052
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008053 This form is deprecated, do not use it in any new configuration, use the new
8054 "option redispatch" instead.
8055
8056 See also : "option redispatch"
8057
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008058
Willy Tarreau96d51952019-05-22 20:34:35 +02008059reqadd <string> [{if | unless} <cond>] (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008060 Add a header at the end of the HTTP request
8061 May be used in sections : defaults | frontend | listen | backend
8062 no | yes | yes | yes
8063 Arguments :
8064 <string> is the complete line to be added. Any space or known delimiter
8065 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008066 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01008067
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01008068 <cond> is an optional matching condition built from ACLs. It makes it
8069 possible to ignore this rule when other conditions are not met.
8070
Willy Tarreau303c0352008-01-17 19:01:39 +01008071 A new line consisting in <string> followed by a line feed will be added after
8072 the last header of an HTTP request.
8073
8074 Header transformations only apply to traffic which passes through HAProxy,
8075 and not to traffic generated by HAProxy, such as health-checks or error
8076 responses.
8077
Willy Tarreau8abd4cd2010-01-31 14:30:44 +01008078 Example : add "X-Proto: SSL" to requests coming via port 81
8079 acl is-ssl dst_port 81
8080 reqadd X-Proto:\ SSL if is-ssl
8081
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008082 See also: "rspadd", "http-request", section 6 about HTTP header manipulation,
8083 and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008084
8085
Willy Tarreau96d51952019-05-22 20:34:35 +02008086reqallow <search> [{if | unless} <cond>] (deprecated)
8087reqiallow <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008088 Definitely allow an HTTP request if a line matches a regular expression
8089 May be used in sections : defaults | frontend | listen | backend
8090 no | yes | yes | yes
8091 Arguments :
8092 <search> is the regular expression applied to HTTP headers and to the
8093 request line. This is an extended regular expression. Parenthesis
8094 grouping is supported and no preliminary backslash is required.
8095 Any space or known delimiter must be escaped using a backslash
8096 ('\'). The pattern applies to a full line at a time. The
8097 "reqallow" keyword strictly matches case while "reqiallow"
8098 ignores case.
8099
Willy Tarreau5321c422010-01-28 20:35:13 +01008100 <cond> is an optional matching condition built from ACLs. It makes it
8101 possible to ignore this rule when other conditions are not met.
8102
Willy Tarreau303c0352008-01-17 19:01:39 +01008103 A request containing any line which matches extended regular expression
8104 <search> will mark the request as allowed, even if any later test would
8105 result in a deny. The test applies both to the request line and to request
8106 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01008107 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01008108
8109 It is easier, faster and more powerful to use ACLs to write access policies.
8110 Reqdeny, reqallow and reqpass should be avoided in new designs.
8111
8112 Example :
8113 # allow www.* but refuse *.local
8114 reqiallow ^Host:\ www\.
8115 reqideny ^Host:\ .*\.local
8116
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008117 See also: "reqdeny", "block", "http-request", section 6 about HTTP header
8118 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008119
8120
Willy Tarreau96d51952019-05-22 20:34:35 +02008121reqdel <search> [{if | unless} <cond>] (deprecated)
8122reqidel <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008123 Delete all headers matching a regular expression in an HTTP request
8124 May be used in sections : defaults | frontend | listen | backend
8125 no | yes | yes | yes
8126 Arguments :
8127 <search> is the regular expression applied to HTTP headers and to the
8128 request line. This is an extended regular expression. Parenthesis
8129 grouping is supported and no preliminary backslash is required.
8130 Any space or known delimiter must be escaped using a backslash
8131 ('\'). The pattern applies to a full line at a time. The "reqdel"
8132 keyword strictly matches case while "reqidel" ignores case.
8133
Willy Tarreau5321c422010-01-28 20:35:13 +01008134 <cond> is an optional matching condition built from ACLs. It makes it
8135 possible to ignore this rule when other conditions are not met.
8136
Willy Tarreau303c0352008-01-17 19:01:39 +01008137 Any header line matching extended regular expression <search> in the request
8138 will be completely deleted. Most common use of this is to remove unwanted
8139 and/or dangerous headers or cookies from a request before passing it to the
8140 next servers.
8141
8142 Header transformations only apply to traffic which passes through HAProxy,
8143 and not to traffic generated by HAProxy, such as health-checks or error
8144 responses. Keep in mind that header names are not case-sensitive.
8145
8146 Example :
8147 # remove X-Forwarded-For header and SERVER cookie
8148 reqidel ^X-Forwarded-For:.*
8149 reqidel ^Cookie:.*SERVER=
8150
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008151 See also: "reqadd", "reqrep", "rspdel", "http-request", section 6 about
8152 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008153
8154
Willy Tarreau96d51952019-05-22 20:34:35 +02008155reqdeny <search> [{if | unless} <cond>] (deprecated)
8156reqideny <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008157 Deny an HTTP request if a line matches a regular expression
8158 May be used in sections : defaults | frontend | listen | backend
8159 no | yes | yes | yes
8160 Arguments :
8161 <search> is the regular expression applied to HTTP headers and to the
8162 request line. This is an extended regular expression. Parenthesis
8163 grouping is supported and no preliminary backslash is required.
8164 Any space or known delimiter must be escaped using a backslash
8165 ('\'). The pattern applies to a full line at a time. The
8166 "reqdeny" keyword strictly matches case while "reqideny" ignores
8167 case.
8168
Willy Tarreau5321c422010-01-28 20:35:13 +01008169 <cond> is an optional matching condition built from ACLs. It makes it
8170 possible to ignore this rule when other conditions are not met.
8171
Willy Tarreau303c0352008-01-17 19:01:39 +01008172 A request containing any line which matches extended regular expression
8173 <search> will mark the request as denied, even if any later test would
8174 result in an allow. The test applies both to the request line and to request
8175 headers. Keep in mind that URLs in request line are case-sensitive while
Willy Tarreaud72758d2010-01-12 10:42:19 +01008176 header names are not.
Willy Tarreau303c0352008-01-17 19:01:39 +01008177
Willy Tarreauced27012008-01-17 20:35:34 +01008178 A denied request will generate an "HTTP 403 forbidden" response once the
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008179 complete request has been parsed. This is consistent with what is practiced
Willy Tarreaud72758d2010-01-12 10:42:19 +01008180 using ACLs.
Willy Tarreauced27012008-01-17 20:35:34 +01008181
Willy Tarreau303c0352008-01-17 19:01:39 +01008182 It is easier, faster and more powerful to use ACLs to write access policies.
8183 Reqdeny, reqallow and reqpass should be avoided in new designs.
8184
8185 Example :
8186 # refuse *.local, then allow www.*
8187 reqideny ^Host:\ .*\.local
8188 reqiallow ^Host:\ www\.
8189
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008190 See also: "reqallow", "rspdeny", "block", "http-request", section 6 about
8191 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008192
8193
Willy Tarreau96d51952019-05-22 20:34:35 +02008194reqpass <search> [{if | unless} <cond>] (deprecated)
8195reqipass <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008196 Ignore any HTTP request line matching a regular expression in next rules
8197 May be used in sections : defaults | frontend | listen | backend
8198 no | yes | yes | yes
8199 Arguments :
8200 <search> is the regular expression applied to HTTP headers and to the
8201 request line. This is an extended regular expression. Parenthesis
8202 grouping is supported and no preliminary backslash is required.
8203 Any space or known delimiter must be escaped using a backslash
8204 ('\'). The pattern applies to a full line at a time. The
8205 "reqpass" keyword strictly matches case while "reqipass" ignores
8206 case.
8207
Willy Tarreau5321c422010-01-28 20:35:13 +01008208 <cond> is an optional matching condition built from ACLs. It makes it
8209 possible to ignore this rule when other conditions are not met.
8210
Willy Tarreau303c0352008-01-17 19:01:39 +01008211 A request containing any line which matches extended regular expression
8212 <search> will skip next rules, without assigning any deny or allow verdict.
8213 The test applies both to the request line and to request headers. Keep in
8214 mind that URLs in request line are case-sensitive while header names are not.
8215
8216 It is easier, faster and more powerful to use ACLs to write access policies.
8217 Reqdeny, reqallow and reqpass should be avoided in new designs.
8218
8219 Example :
8220 # refuse *.local, then allow www.*, but ignore "www.private.local"
8221 reqipass ^Host:\ www.private\.local
8222 reqideny ^Host:\ .*\.local
8223 reqiallow ^Host:\ www\.
8224
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008225 See also: "reqallow", "reqdeny", "block", "http-request", section 6 about
8226 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008227
8228
Willy Tarreau96d51952019-05-22 20:34:35 +02008229reqrep <search> <string> [{if | unless} <cond>] (deprecated)
8230reqirep <search> <string> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008231 Replace a regular expression with a string in an HTTP request line
8232 May be used in sections : defaults | frontend | listen | backend
8233 no | yes | yes | yes
8234 Arguments :
8235 <search> is the regular expression applied to HTTP headers and to the
8236 request line. This is an extended regular expression. Parenthesis
8237 grouping is supported and no preliminary backslash is required.
8238 Any space or known delimiter must be escaped using a backslash
8239 ('\'). The pattern applies to a full line at a time. The "reqrep"
8240 keyword strictly matches case while "reqirep" ignores case.
8241
8242 <string> is the complete line to be added. Any space or known delimiter
8243 must be escaped using a backslash ('\'). References to matched
8244 pattern groups are possible using the common \N form, with N
8245 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008246 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01008247
Willy Tarreau5321c422010-01-28 20:35:13 +01008248 <cond> is an optional matching condition built from ACLs. It makes it
8249 possible to ignore this rule when other conditions are not met.
8250
Willy Tarreau303c0352008-01-17 19:01:39 +01008251 Any line matching extended regular expression <search> in the request (both
8252 the request line and header lines) will be completely replaced with <string>.
8253 Most common use of this is to rewrite URLs or domain names in "Host" headers.
8254
8255 Header transformations only apply to traffic which passes through HAProxy,
8256 and not to traffic generated by HAProxy, such as health-checks or error
8257 responses. Note that for increased readability, it is suggested to add enough
8258 spaces between the request and the response. Keep in mind that URLs in
8259 request line are case-sensitive while header names are not.
8260
8261 Example :
8262 # replace "/static/" with "/" at the beginning of any request path.
Dmitry Sivachenko7823de32012-05-16 14:00:26 +04008263 reqrep ^([^\ :]*)\ /static/(.*) \1\ /\2
Willy Tarreau303c0352008-01-17 19:01:39 +01008264 # replace "www.mydomain.com" with "www" in the host name.
8265 reqirep ^Host:\ www.mydomain.com Host:\ www
8266
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008267 See also: "reqadd", "reqdel", "rsprep", "tune.bufsize", "http-request",
8268 section 6 about HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008269
8270
Willy Tarreau96d51952019-05-22 20:34:35 +02008271reqtarpit <search> [{if | unless} <cond>] (deprecated)
8272reqitarpit <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008273 Tarpit an HTTP request containing a line matching a regular expression
8274 May be used in sections : defaults | frontend | listen | backend
8275 no | yes | yes | yes
8276 Arguments :
8277 <search> is the regular expression applied to HTTP headers and to the
8278 request line. This is an extended regular expression. Parenthesis
8279 grouping is supported and no preliminary backslash is required.
8280 Any space or known delimiter must be escaped using a backslash
8281 ('\'). The pattern applies to a full line at a time. The
8282 "reqtarpit" keyword strictly matches case while "reqitarpit"
8283 ignores case.
8284
Willy Tarreau5321c422010-01-28 20:35:13 +01008285 <cond> is an optional matching condition built from ACLs. It makes it
8286 possible to ignore this rule when other conditions are not met.
8287
Willy Tarreau303c0352008-01-17 19:01:39 +01008288 A request containing any line which matches extended regular expression
8289 <search> will be tarpitted, which means that it will connect to nowhere, will
Willy Tarreauced27012008-01-17 20:35:34 +01008290 be kept open for a pre-defined time, then will return an HTTP error 500 so
8291 that the attacker does not suspect it has been tarpitted. The status 500 will
8292 be reported in the logs, but the completion flags will indicate "PT". The
Willy Tarreau303c0352008-01-17 19:01:39 +01008293 delay is defined by "timeout tarpit", or "timeout connect" if the former is
8294 not set.
8295
8296 The goal of the tarpit is to slow down robots attacking servers with
8297 identifiable requests. Many robots limit their outgoing number of connections
8298 and stay connected waiting for a reply which can take several minutes to
8299 come. Depending on the environment and attack, it may be particularly
8300 efficient at reducing the load on the network and firewalls.
8301
Willy Tarreau5321c422010-01-28 20:35:13 +01008302 Examples :
Davor Ocelice9ed2812017-12-25 17:49:28 +01008303 # ignore user-agents reporting any flavor of "Mozilla" or "MSIE", but
Willy Tarreau303c0352008-01-17 19:01:39 +01008304 # block all others.
8305 reqipass ^User-Agent:\.*(Mozilla|MSIE)
8306 reqitarpit ^User-Agent:
8307
Willy Tarreau5321c422010-01-28 20:35:13 +01008308 # block bad guys
8309 acl badguys src 10.1.0.3 172.16.13.20/28
8310 reqitarpit . if badguys
8311
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008312 See also: "reqallow", "reqdeny", "reqpass", "http-request", section 6
8313 about HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008314
8315
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02008316retries <value>
8317 Set the number of retries to perform on a server after a connection failure
8318 May be used in sections: defaults | frontend | listen | backend
8319 yes | no | yes | yes
8320 Arguments :
8321 <value> is the number of times a connection attempt should be retried on
8322 a server when a connection either is refused or times out. The
8323 default value is 3.
8324
8325 It is important to understand that this value applies to the number of
8326 connection attempts, not full requests. When a connection has effectively
8327 been established to a server, there will be no more retry.
8328
8329 In order to avoid immediate reconnections to a server which is restarting,
Joseph Lynch726ab712015-05-11 23:25:34 -07008330 a turn-around timer of min("timeout connect", one second) is applied before
8331 a retry occurs.
Willy Tarreaue5c5ce92008-06-20 17:27:19 +02008332
8333 When "option redispatch" is set, the last retry may be performed on another
8334 server even if a cookie references a different server.
8335
8336 See also : "option redispatch"
8337
8338
Olivier Houcharda254a372019-04-05 15:30:12 +02008339retry-on [list of keywords]
8340 Specify when to attempt to automatically retry a failed request
8341 May be used in sections: defaults | frontend | listen | backend
8342 yes | no | yes | yes
8343 Arguments :
8344 <keywords> is a list of keywords or HTTP status codes, each representing a
8345 type of failure event on which an attempt to retry the request
8346 is desired. Please read the notes at the bottom before changing
8347 this setting. The following keywords are supported :
8348
8349 none never retry
8350
8351 conn-failure retry when the connection or the SSL handshake failed
8352 and the request could not be sent. This is the default.
8353
8354 empty-response retry when the server connection was closed after part
8355 of the request was sent, and nothing was received from
8356 the server. This type of failure may be caused by the
8357 request timeout on the server side, poor network
8358 condition, or a server crash or restart while
8359 processing the request.
8360
Olivier Houcharde3249a92019-05-03 23:01:47 +02008361 junk-response retry when the server returned something not looking
8362 like a complete HTTP response. This includes partial
8363 responses headers as well as non-HTTP contents. It
8364 usually is a bad idea to retry on such events, which
8365 may be caused a configuration issue (wrong server port)
8366 or by the request being harmful to the server (buffer
8367 overflow attack for example).
8368
Olivier Houcharda254a372019-04-05 15:30:12 +02008369 response-timeout the server timeout stroke while waiting for the server
8370 to respond to the request. This may be caused by poor
8371 network condition, the reuse of an idle connection
8372 which has expired on the path, or by the request being
8373 extremely expensive to process. It generally is a bad
8374 idea to retry on such events on servers dealing with
8375 heavy database processing (full scans, etc) as it may
8376 amplify denial of service attacks.
8377
Olivier Houchard865d8392019-05-03 22:46:27 +02008378 0rtt-rejected retry requests which were sent over early data and were
8379 rejected by the server. These requests are generally
8380 considered to be safe to retry.
8381
Olivier Houcharda254a372019-04-05 15:30:12 +02008382 <status> any HTTP status code among "404" (Not Found), "408"
8383 (Request Timeout), "425" (Too Early), "500" (Server
8384 Error), "501" (Not Implemented), "502" (Bad Gateway),
8385 "503" (Service Unavailable), "504" (Gateway Timeout).
8386
Olivier Houchardddf0e032019-05-10 18:05:40 +02008387 all-retryable-errors
8388 retry request for any error that are considered
8389 retryable. This currently activates "conn-failure",
8390 "empty-response", "junk-response", "response-timeout",
8391 "0rtt-rejected", "500", "502", "503", and "504".
8392
Olivier Houcharda254a372019-04-05 15:30:12 +02008393 Using this directive replaces any previous settings with the new ones; it is
8394 not cumulative.
8395
8396 Please note that using anything other than "none" and "conn-failure" requires
8397 to allocate a buffer and copy the whole request into it, so it has memory and
8398 performance impacts. Requests not fitting in a single buffer will never be
8399 retried (see the global tune.bufsize setting).
8400
8401 You have to make sure the application has a replay protection mechanism built
8402 in such as a unique transaction IDs passed in requests, or that replaying the
8403 same request has no consequence, or it is very dangerous to use any retry-on
8404 value beside "conn-failure" and "none". Static file servers and caches are
8405 generally considered safe against any type of retry. Using a status code can
8406 be useful to quickly leave a server showing an abnormal behavior (out of
8407 memory, file system issues, etc), but in this case it may be a good idea to
8408 immediately redispatch the connection to another server (please see "option
8409 redispatch" for this). Last, it is important to understand that most causes
8410 of failures are the requests themselves and that retrying a request causing a
8411 server to misbehave will often make the situation even worse for this server,
8412 or for the whole service in case of redispatch.
8413
8414 Unless you know exactly how the application deals with replayed requests, you
8415 should not use this directive.
8416
8417 The default is "conn-failure".
8418
8419 See also: "retries", "option redispatch", "tune.bufsize"
8420
Willy Tarreau96d51952019-05-22 20:34:35 +02008421rspadd <string> [{if | unless} <cond>] (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008422 Add a header at the end of the HTTP response
8423 May be used in sections : defaults | frontend | listen | backend
8424 no | yes | yes | yes
8425 Arguments :
8426 <string> is the complete line to be added. Any space or known delimiter
8427 must be escaped using a backslash ('\'). Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008428 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01008429
Willy Tarreaufdb563c2010-01-31 15:43:27 +01008430 <cond> is an optional matching condition built from ACLs. It makes it
8431 possible to ignore this rule when other conditions are not met.
8432
Willy Tarreau303c0352008-01-17 19:01:39 +01008433 A new line consisting in <string> followed by a line feed will be added after
8434 the last header of an HTTP response.
8435
8436 Header transformations only apply to traffic which passes through HAProxy,
8437 and not to traffic generated by HAProxy, such as health-checks or error
8438 responses.
8439
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008440 See also: "rspdel" "reqadd", "http-response", section 6 about HTTP header
8441 manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008442
8443
Willy Tarreau96d51952019-05-22 20:34:35 +02008444rspdel <search> [{if | unless} <cond>] (deprecated)
8445rspidel <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008446 Delete all headers matching a regular expression in an HTTP response
8447 May be used in sections : defaults | frontend | listen | backend
8448 no | yes | yes | yes
8449 Arguments :
8450 <search> is the regular expression applied to HTTP headers and to the
8451 response line. This is an extended regular expression, so
8452 parenthesis grouping is supported and no preliminary backslash
8453 is required. Any space or known delimiter must be escaped using
8454 a backslash ('\'). The pattern applies to a full line at a time.
8455 The "rspdel" keyword strictly matches case while "rspidel"
8456 ignores case.
8457
Willy Tarreaufdb563c2010-01-31 15:43:27 +01008458 <cond> is an optional matching condition built from ACLs. It makes it
8459 possible to ignore this rule when other conditions are not met.
8460
Willy Tarreau303c0352008-01-17 19:01:39 +01008461 Any header line matching extended regular expression <search> in the response
8462 will be completely deleted. Most common use of this is to remove unwanted
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02008463 and/or sensitive headers or cookies from a response before passing it to the
Willy Tarreau303c0352008-01-17 19:01:39 +01008464 client.
8465
8466 Header transformations only apply to traffic which passes through HAProxy,
8467 and not to traffic generated by HAProxy, such as health-checks or error
8468 responses. Keep in mind that header names are not case-sensitive.
8469
8470 Example :
8471 # remove the Server header from responses
Willy Tarreau5e80e022013-05-25 08:31:25 +02008472 rspidel ^Server:.*
Willy Tarreau303c0352008-01-17 19:01:39 +01008473
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008474 See also: "rspadd", "rsprep", "reqdel", "http-response", section 6 about
8475 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008476
8477
Willy Tarreau96d51952019-05-22 20:34:35 +02008478rspdeny <search> [{if | unless} <cond>] (deprecated)
8479rspideny <search> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008480 Block an HTTP response if a line matches a regular expression
8481 May be used in sections : defaults | frontend | listen | backend
8482 no | yes | yes | yes
8483 Arguments :
8484 <search> is the regular expression applied to HTTP headers and to the
8485 response line. This is an extended regular expression, so
8486 parenthesis grouping is supported and no preliminary backslash
8487 is required. Any space or known delimiter must be escaped using
8488 a backslash ('\'). The pattern applies to a full line at a time.
8489 The "rspdeny" keyword strictly matches case while "rspideny"
8490 ignores case.
8491
Willy Tarreaufdb563c2010-01-31 15:43:27 +01008492 <cond> is an optional matching condition built from ACLs. It makes it
8493 possible to ignore this rule when other conditions are not met.
8494
Willy Tarreau303c0352008-01-17 19:01:39 +01008495 A response containing any line which matches extended regular expression
8496 <search> will mark the request as denied. The test applies both to the
8497 response line and to response headers. Keep in mind that header names are not
8498 case-sensitive.
8499
8500 Main use of this keyword is to prevent sensitive information leak and to
Willy Tarreauced27012008-01-17 20:35:34 +01008501 block the response before it reaches the client. If a response is denied, it
8502 will be replaced with an HTTP 502 error so that the client never retrieves
8503 any sensitive data.
Willy Tarreau303c0352008-01-17 19:01:39 +01008504
8505 It is easier, faster and more powerful to use ACLs to write access policies.
8506 Rspdeny should be avoided in new designs.
8507
8508 Example :
8509 # Ensure that no content type matching ms-word will leak
8510 rspideny ^Content-type:\.*/ms-word
8511
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008512 See also: "reqdeny", "acl", "block", "http-response", section 6 about
8513 HTTP header manipulation and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008514
8515
Willy Tarreau96d51952019-05-22 20:34:35 +02008516rsprep <search> <string> [{if | unless} <cond>] (deprecated)
8517rspirep <search> <string> [{if | unless} <cond>] (ignore case) (deprecated)
Willy Tarreau303c0352008-01-17 19:01:39 +01008518 Replace a regular expression with a string in an HTTP response line
8519 May be used in sections : defaults | frontend | listen | backend
8520 no | yes | yes | yes
8521 Arguments :
8522 <search> is the regular expression applied to HTTP headers and to the
8523 response line. This is an extended regular expression, so
8524 parenthesis grouping is supported and no preliminary backslash
8525 is required. Any space or known delimiter must be escaped using
8526 a backslash ('\'). The pattern applies to a full line at a time.
8527 The "rsprep" keyword strictly matches case while "rspirep"
8528 ignores case.
8529
8530 <string> is the complete line to be added. Any space or known delimiter
8531 must be escaped using a backslash ('\'). References to matched
8532 pattern groups are possible using the common \N form, with N
8533 being a single digit between 0 and 9. Please refer to section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008534 6 about HTTP header manipulation for more information.
Willy Tarreau303c0352008-01-17 19:01:39 +01008535
Willy Tarreaufdb563c2010-01-31 15:43:27 +01008536 <cond> is an optional matching condition built from ACLs. It makes it
8537 possible to ignore this rule when other conditions are not met.
8538
Willy Tarreau303c0352008-01-17 19:01:39 +01008539 Any line matching extended regular expression <search> in the response (both
8540 the response line and header lines) will be completely replaced with
8541 <string>. Most common use of this is to rewrite Location headers.
8542
8543 Header transformations only apply to traffic which passes through HAProxy,
8544 and not to traffic generated by HAProxy, such as health-checks or error
8545 responses. Note that for increased readability, it is suggested to add enough
8546 spaces between the request and the response. Keep in mind that header names
8547 are not case-sensitive.
8548
8549 Example :
8550 # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com"
8551 rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com
8552
Ruoshan Huangeb5a3632015-12-08 21:00:23 +08008553 See also: "rspadd", "rspdel", "reqrep", "http-response", section 6 about
8554 HTTP header manipulation, and section 7 about ACLs.
Willy Tarreau303c0352008-01-17 19:01:39 +01008555
8556
David du Colombier486df472011-03-17 10:40:26 +01008557server <name> <address>[:[port]] [param*]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008558 Declare a server in a backend
8559 May be used in sections : defaults | frontend | listen | backend
8560 no | no | yes | yes
8561 Arguments :
8562 <name> is the internal name assigned to this server. This name will
Davor Ocelice9ed2812017-12-25 17:49:28 +01008563 appear in logs and alerts. If "http-send-name-header" is
Mark Lamourinec2247f02012-01-04 13:02:01 -05008564 set, it will be added to the request header sent to the server.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008565
David du Colombier486df472011-03-17 10:40:26 +01008566 <address> is the IPv4 or IPv6 address of the server. Alternatively, a
8567 resolvable hostname is supported, but this name will be resolved
8568 during start-up. Address "0.0.0.0" or "*" has a special meaning.
8569 It indicates that the connection will be forwarded to the same IP
Willy Tarreaud669a4f2010-07-13 14:49:50 +02008570 address as the one from the client connection. This is useful in
8571 transparent proxy architectures where the client's connection is
8572 intercepted and haproxy must forward to the original destination
8573 address. This is more or less what the "transparent" keyword does
8574 except that with a server it's possible to limit concurrency and
Willy Tarreau24709282013-03-10 21:32:12 +01008575 to report statistics. Optionally, an address family prefix may be
8576 used before the address to force the family regardless of the
8577 address format, which can be useful to specify a path to a unix
8578 socket with no slash ('/'). Currently supported prefixes are :
8579 - 'ipv4@' -> address is always IPv4
8580 - 'ipv6@' -> address is always IPv6
8581 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02008582 - 'abns@' -> address is in abstract namespace (Linux only)
William Lallemand2fe7dd02018-09-11 16:51:29 +02008583 - 'sockpair@' -> address is the FD of a connected unix
8584 socket or of a socketpair. During a connection, the
8585 backend creates a pair of connected sockets, and passes
8586 one of them over the FD. The bind part will use the
8587 received socket as the client FD. Should be used
8588 carefully.
William Lallemandb2f07452015-05-12 14:27:13 +02008589 You may want to reference some environment variables in the
8590 address parameter, see section 2.3 about environment
Willy Tarreau6a031d12016-11-07 19:42:35 +01008591 variables. The "init-addr" setting can be used to modify the way
8592 IP addresses should be resolved upon startup.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008593
Willy Tarreaub6205fd2012-09-24 12:27:33 +02008594 <port> is an optional port specification. If set, all connections will
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008595 be sent to this port. If unset, the same port the client
8596 connected to will be used. The port may also be prefixed by a "+"
8597 or a "-". In this case, the server's port will be determined by
8598 adding this value to the client's port.
8599
8600 <param*> is a list of parameters for this server. The "server" keywords
8601 accepts an important number of options and has a complete section
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008602 dedicated to it. Please refer to section 5 for more details.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008603
8604 Examples :
8605 server first 10.1.1.1:1080 cookie first check inter 1000
8606 server second 10.1.1.2:1080 cookie second check inter 1000
Willy Tarreau24709282013-03-10 21:32:12 +01008607 server transp ipv4@
William Lallemandb2f07452015-05-12 14:27:13 +02008608 server backup "${SRV_BACKUP}:1080" backup
8609 server www1_dc1 "${LAN_DC1}.101:80"
8610 server www1_dc2 "${LAN_DC2}.101:80"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008611
Willy Tarreau55dcaf62015-09-27 15:03:15 +02008612 Note: regarding Linux's abstract namespace sockets, HAProxy uses the whole
8613 sun_path length is used for the address length. Some other programs
8614 such as socat use the string length only by default. Pass the option
8615 ",unix-tightsocklen=0" to any abstract socket definition in socat to
8616 make it compatible with HAProxy's.
8617
Mark Lamourinec2247f02012-01-04 13:02:01 -05008618 See also: "default-server", "http-send-name-header" and section 5 about
8619 server options
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008620
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02008621server-state-file-name [<file>]
8622 Set the server state file to read, load and apply to servers available in
8623 this backend. It only applies when the directive "load-server-state-from-file"
8624 is set to "local". When <file> is not provided or if this directive is not
8625 set, then backend name is used. If <file> starts with a slash '/', then it is
8626 considered as an absolute path. Otherwise, <file> is concatenated to the
8627 global directive "server-state-file-base".
8628
8629 Example: the minimal configuration below would make HAProxy look for the
8630 state server file '/etc/haproxy/states/bk':
8631
8632 global
8633 server-state-file-base /etc/haproxy/states
8634
Willy Tarreau750bb0c2020-03-05 16:03:58 +01008635 backend bk
Baptiste Assmann01c6cc32015-08-23 11:45:29 +02008636 load-server-state-from-file
8637
8638 See also: "server-state-file-base", "load-server-state-from-file", and
8639 "show servers state"
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008640
Frédéric Lécaillecb4502e2017-04-20 13:36:25 +02008641server-template <prefix> <num | range> <fqdn>[:<port>] [params*]
8642 Set a template to initialize servers with shared parameters.
8643 The names of these servers are built from <prefix> and <num | range> parameters.
8644 May be used in sections : defaults | frontend | listen | backend
8645 no | no | yes | yes
8646
8647 Arguments:
8648 <prefix> A prefix for the server names to be built.
8649
8650 <num | range>
8651 If <num> is provided, this template initializes <num> servers
8652 with 1 up to <num> as server name suffixes. A range of numbers
8653 <num_low>-<num_high> may also be used to use <num_low> up to
8654 <num_high> as server name suffixes.
8655
8656 <fqdn> A FQDN for all the servers this template initializes.
8657
8658 <port> Same meaning as "server" <port> argument (see "server" keyword).
8659
8660 <params*>
8661 Remaining server parameters among all those supported by "server"
8662 keyword.
8663
8664 Examples:
8665 # Initializes 3 servers with srv1, srv2 and srv3 as names,
8666 # google.com as FQDN, and health-check enabled.
8667 server-template srv 1-3 google.com:80 check
8668
8669 # or
8670 server-template srv 3 google.com:80 check
8671
8672 # would be equivalent to:
8673 server srv1 google.com:80 check
8674 server srv2 google.com:80 check
8675 server srv3 google.com:80 check
8676
8677
8678
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008679source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +02008680source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreaud53f96b2009-02-04 18:46:54 +01008681source <addr>[:<port>] [interface <name>]
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008682 Set the source address for outgoing connections
8683 May be used in sections : defaults | frontend | listen | backend
8684 yes | no | yes | yes
8685 Arguments :
8686 <addr> is the IPv4 address HAProxy will bind to before connecting to a
8687 server. This address is also used as a source for health checks.
Willy Tarreau24709282013-03-10 21:32:12 +01008688
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008689 The default value of 0.0.0.0 means that the system will select
Willy Tarreau24709282013-03-10 21:32:12 +01008690 the most appropriate address to reach its destination. Optionally
8691 an address family prefix may be used before the address to force
8692 the family regardless of the address format, which can be useful
8693 to specify a path to a unix socket with no slash ('/'). Currently
8694 supported prefixes are :
8695 - 'ipv4@' -> address is always IPv4
8696 - 'ipv6@' -> address is always IPv6
8697 - 'unix@' -> address is a path to a local unix socket
Willy Tarreauccfccef2014-05-10 01:49:15 +02008698 - 'abns@' -> address is in abstract namespace (Linux only)
Cyril Bonté307ee1e2015-09-28 23:16:06 +02008699 You may want to reference some environment variables in the
8700 address parameter, see section 2.3 about environment variables.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008701
8702 <port> is an optional port. It is normally not needed but may be useful
8703 in some very specific contexts. The default value of zero means
Willy Tarreauc6f4ce82009-06-10 11:09:37 +02008704 the system will select a free port. Note that port ranges are not
8705 supported in the backend. If you want to force port ranges, you
8706 have to specify them on each "server" line.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008707
8708 <addr2> is the IP address to present to the server when connections are
8709 forwarded in full transparent proxy mode. This is currently only
8710 supported on some patched Linux kernels. When this address is
8711 specified, clients connecting to the server will be presented
8712 with this address, while health checks will still use the address
8713 <addr>.
8714
8715 <port2> is the optional port to present to the server when connections
8716 are forwarded in full transparent proxy mode (see <addr2> above).
8717 The default value of zero means the system will select a free
8718 port.
8719
Willy Tarreaubce70882009-09-07 11:51:47 +02008720 <hdr> is the name of a HTTP header in which to fetch the IP to bind to.
8721 This is the name of a comma-separated header list which can
8722 contain multiple IP addresses. By default, the last occurrence is
8723 used. This is designed to work with the X-Forwarded-For header
Baptiste Assmannea3e73b2013-02-02 23:47:49 +01008724 and to automatically bind to the client's IP address as seen
Willy Tarreaubce70882009-09-07 11:51:47 +02008725 by previous proxy, typically Stunnel. In order to use another
8726 occurrence from the last one, please see the <occ> parameter
8727 below. When the header (or occurrence) is not found, no binding
8728 is performed so that the proxy's default IP address is used. Also
8729 keep in mind that the header name is case insensitive, as for any
8730 HTTP header.
8731
8732 <occ> is the occurrence number of a value to be used in a multi-value
8733 header. This is to be used in conjunction with "hdr_ip(<hdr>)",
Jamie Gloudonaaa21002012-08-25 00:18:33 -04008734 in order to specify which occurrence to use for the source IP
Willy Tarreaubce70882009-09-07 11:51:47 +02008735 address. Positive values indicate a position from the first
8736 occurrence, 1 being the first one. Negative values indicate
8737 positions relative to the last one, -1 being the last one. This
8738 is helpful for situations where an X-Forwarded-For header is set
8739 at the entry point of an infrastructure and must be used several
8740 proxy layers away. When this value is not specified, -1 is
8741 assumed. Passing a zero here disables the feature.
8742
Willy Tarreaud53f96b2009-02-04 18:46:54 +01008743 <name> is an optional interface name to which to bind to for outgoing
8744 traffic. On systems supporting this features (currently, only
8745 Linux), this allows one to bind all traffic to the server to
8746 this interface even if it is not the one the system would select
8747 based on routing tables. This should be used with extreme care.
8748 Note that using this option requires root privileges.
8749
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008750 The "source" keyword is useful in complex environments where a specific
8751 address only is allowed to connect to the servers. It may be needed when a
8752 private address must be used through a public gateway for instance, and it is
8753 known that the system cannot determine the adequate source address by itself.
8754
8755 An extension which is available on certain patched Linux kernels may be used
8756 through the "usesrc" optional keyword. It makes it possible to connect to the
8757 servers with an IP address which does not belong to the system itself. This
8758 is called "full transparent proxy mode". For this to work, the destination
8759 servers have to route their traffic back to this address through the machine
8760 running HAProxy, and IP forwarding must generally be enabled on this machine.
8761
8762 In this "full transparent proxy" mode, it is possible to force a specific IP
8763 address to be presented to the servers. This is not much used in fact. A more
8764 common use is to tell HAProxy to present the client's IP address. For this,
8765 there are two methods :
8766
8767 - present the client's IP and port addresses. This is the most transparent
8768 mode, but it can cause problems when IP connection tracking is enabled on
8769 the machine, because a same connection may be seen twice with different
8770 states. However, this solution presents the huge advantage of not
8771 limiting the system to the 64k outgoing address+port couples, because all
8772 of the client ranges may be used.
8773
8774 - present only the client's IP address and select a spare port. This
8775 solution is still quite elegant but slightly less transparent (downstream
8776 firewalls logs will not match upstream's). It also presents the downside
8777 of limiting the number of concurrent connections to the usual 64k ports.
8778 However, since the upstream and downstream ports are different, local IP
8779 connection tracking on the machine will not be upset by the reuse of the
8780 same session.
8781
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008782 This option sets the default source for all servers in the backend. It may
8783 also be specified in a "defaults" section. Finer source address specification
8784 is possible at the server level using the "source" server option. Refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008785 section 5 for more information.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008786
Baptiste Assmann91bd3372015-07-17 21:59:42 +02008787 In order to work, "usesrc" requires root privileges.
8788
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008789 Examples :
8790 backend private
8791 # Connect to the servers using our 192.168.1.200 source address
8792 source 192.168.1.200
8793
8794 backend transparent_ssl1
8795 # Connect to the SSL farm from the client's source address
8796 source 192.168.1.200 usesrc clientip
8797
8798 backend transparent_ssl2
8799 # Connect to the SSL farm from the client's source address and port
8800 # not recommended if IP conntrack is present on the local machine.
8801 source 192.168.1.200 usesrc client
8802
8803 backend transparent_ssl3
8804 # Connect to the SSL farm from the client's source address. It
8805 # is more conntrack-friendly.
8806 source 192.168.1.200 usesrc clientip
8807
8808 backend transparent_smtp
8809 # Connect to the SMTP farm from the client's source address/port
8810 # with Tproxy version 4.
8811 source 0.0.0.0 usesrc clientip
8812
Willy Tarreaubce70882009-09-07 11:51:47 +02008813 backend transparent_http
8814 # Connect to the servers using the client's IP as seen by previous
8815 # proxy.
8816 source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1)
8817
Willy Tarreauc57f0e22009-05-10 13:12:33 +02008818 See also : the "source" server option in section 5, the Tproxy patches for
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008819 the Linux kernel on www.balabit.com, the "bind" keyword.
8820
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01008821
Willy Tarreau844e3c52008-01-11 16:28:18 +01008822srvtimeout <timeout> (deprecated)
8823 Set the maximum inactivity time on the server side.
8824 May be used in sections : defaults | frontend | listen | backend
8825 yes | no | yes | yes
8826 Arguments :
8827 <timeout> is the timeout value specified in milliseconds by default, but
8828 can be in any other unit if the number is suffixed by the unit,
8829 as explained at the top of this document.
8830
8831 The inactivity timeout applies when the server is expected to acknowledge or
8832 send data. In HTTP mode, this timeout is particularly important to consider
8833 during the first phase of the server's response, when it has to send the
8834 headers, as it directly represents the server's processing time for the
8835 request. To find out what value to put there, it's often good to start with
8836 what would be considered as unacceptable response times, then check the logs
8837 to observe the response time distribution, and adjust the value accordingly.
8838
8839 The value is specified in milliseconds by default, but can be in any other
8840 unit if the number is suffixed by the unit, as specified at the top of this
8841 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
8842 recommended that the client timeout remains equal to the server timeout in
8843 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +01008844 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +01008845 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +01008846 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreau844e3c52008-01-11 16:28:18 +01008847
8848 This parameter is specific to backends, but can be specified once for all in
8849 "defaults" sections. This is in fact one of the easiest solutions not to
8850 forget about it. An unspecified timeout results in an infinite timeout, which
8851 is not recommended. Such a usage is accepted and works but reports a warning
8852 during startup because it may results in accumulation of expired sessions in
8853 the system if the system's timeouts are not configured either.
8854
8855 This parameter is provided for compatibility but is currently deprecated.
8856 Please use "timeout server" instead.
8857
Willy Tarreauce887fd2012-05-12 12:50:00 +02008858 See also : "timeout server", "timeout tunnel", "timeout client" and
8859 "clitimeout".
Willy Tarreau844e3c52008-01-11 16:28:18 +01008860
8861
Cyril Bonté66c327d2010-10-12 00:14:37 +02008862stats admin { if | unless } <cond>
8863 Enable statistics admin level if/unless a condition is matched
8864 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008865 no | yes | yes | yes
Cyril Bonté66c327d2010-10-12 00:14:37 +02008866
8867 This statement enables the statistics admin level if/unless a condition is
8868 matched.
8869
8870 The admin level allows to enable/disable servers from the web interface. By
8871 default, statistics page is read-only for security reasons.
8872
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008873 Note : Consider not using this feature in multi-process mode (nbproc > 1)
8874 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01008875 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008876
Cyril Bonté23b39d92011-02-10 22:54:44 +01008877 Currently, the POST request is limited to the buffer size minus the reserved
8878 buffer space, which means that if the list of servers is too long, the
8879 request won't be processed. It is recommended to alter few servers at a
8880 time.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008881
8882 Example :
8883 # statistics admin level only for localhost
8884 backend stats_localhost
8885 stats enable
8886 stats admin if LOCALHOST
8887
8888 Example :
8889 # statistics admin level always enabled because of the authentication
8890 backend stats_auth
8891 stats enable
8892 stats auth admin:AdMiN123
8893 stats admin if TRUE
8894
8895 Example :
8896 # statistics admin level depends on the authenticated user
8897 userlist stats-auth
8898 group admin users admin
8899 user admin insecure-password AdMiN123
8900 group readonly users haproxy
8901 user haproxy insecure-password haproxy
8902
8903 backend stats_auth
8904 stats enable
8905 acl AUTH http_auth(stats-auth)
8906 acl AUTH_ADMIN http_auth_group(stats-auth) admin
8907 stats http-request auth unless AUTH
8908 stats admin if AUTH_ADMIN
8909
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01008910 See also : "stats enable", "stats auth", "stats http-request", "nbproc",
8911 "bind-process", section 3.4 about userlists and section 7 about
8912 ACL usage.
Cyril Bonté66c327d2010-10-12 00:14:37 +02008913
8914
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008915stats auth <user>:<passwd>
8916 Enable statistics with authentication and grant access to an account
8917 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008918 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008919 Arguments :
8920 <user> is a user name to grant access to
8921
8922 <passwd> is the cleartext password associated to this user
8923
8924 This statement enables statistics with default settings, and restricts access
8925 to declared users only. It may be repeated as many times as necessary to
8926 allow as many users as desired. When a user tries to access the statistics
8927 without a valid account, a "401 Forbidden" response will be returned so that
8928 the browser asks the user to provide a valid user and password. The real
8929 which will be returned to the browser is configurable using "stats realm".
8930
8931 Since the authentication method is HTTP Basic Authentication, the passwords
8932 circulate in cleartext on the network. Thus, it was decided that the
8933 configuration file would also use cleartext passwords to remind the users
Willy Tarreau3c92c5f2011-08-28 09:45:47 +02008934 that those ones should not be sensitive and not shared with any other account.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008935
8936 It is also possible to reduce the scope of the proxies which appear in the
8937 report using "stats scope".
8938
8939 Though this statement alone is enough to enable statistics reporting, it is
8940 recommended to set all other settings in order to avoid relying on default
8941 unobvious parameters.
8942
8943 Example :
8944 # public access (limited to this backend only)
8945 backend public_www
8946 server srv1 192.168.0.1:80
8947 stats enable
8948 stats hide-version
8949 stats scope .
8950 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008951 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008952 stats auth admin1:AdMiN123
8953 stats auth admin2:AdMiN321
8954
8955 # internal monitoring access (unlimited)
8956 backend private_monitoring
8957 stats enable
8958 stats uri /admin?stats
8959 stats refresh 5s
8960
8961 See also : "stats enable", "stats realm", "stats scope", "stats uri"
8962
8963
8964stats enable
8965 Enable statistics reporting with default settings
8966 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02008967 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008968 Arguments : none
8969
8970 This statement enables statistics reporting with default settings defined
8971 at build time. Unless stated otherwise, these settings are used :
8972 - stats uri : /haproxy?stats
8973 - stats realm : "HAProxy Statistics"
8974 - stats auth : no authentication
8975 - stats scope : no restriction
8976
8977 Though this statement alone is enough to enable statistics reporting, it is
8978 recommended to set all other settings in order to avoid relying on default
8979 unobvious parameters.
8980
8981 Example :
8982 # public access (limited to this backend only)
8983 backend public_www
8984 server srv1 192.168.0.1:80
8985 stats enable
8986 stats hide-version
8987 stats scope .
8988 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01008989 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01008990 stats auth admin1:AdMiN123
8991 stats auth admin2:AdMiN321
8992
8993 # internal monitoring access (unlimited)
8994 backend private_monitoring
8995 stats enable
8996 stats uri /admin?stats
8997 stats refresh 5s
8998
8999 See also : "stats auth", "stats realm", "stats uri"
9000
9001
Willy Tarreaud63335a2010-02-26 12:56:52 +01009002stats hide-version
9003 Enable statistics and hide HAProxy version reporting
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009004 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009005 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01009006 Arguments : none
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009007
Willy Tarreaud63335a2010-02-26 12:56:52 +01009008 By default, the stats page reports some useful status information along with
9009 the statistics. Among them is HAProxy's version. However, it is generally
9010 considered dangerous to report precise version to anyone, as it can help them
9011 target known weaknesses with specific attacks. The "stats hide-version"
9012 statement removes the version from the statistics report. This is recommended
9013 for public sites or any site with a weak login/password.
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009014
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02009015 Though this statement alone is enough to enable statistics reporting, it is
9016 recommended to set all other settings in order to avoid relying on default
9017 unobvious parameters.
9018
Willy Tarreaud63335a2010-02-26 12:56:52 +01009019 Example :
9020 # public access (limited to this backend only)
9021 backend public_www
9022 server srv1 192.168.0.1:80
Krzysztof Piotr Oledzki48cb2ae2009-10-02 22:51:14 +02009023 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01009024 stats hide-version
9025 stats scope .
9026 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009027 stats realm HAProxy\ Statistics
Willy Tarreaud63335a2010-02-26 12:56:52 +01009028 stats auth admin1:AdMiN123
9029 stats auth admin2:AdMiN321
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009030
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009031 # internal monitoring access (unlimited)
9032 backend private_monitoring
9033 stats enable
Willy Tarreaud63335a2010-02-26 12:56:52 +01009034 stats uri /admin?stats
9035 stats refresh 5s
Krzysztof Piotr Oledzki15514c22010-01-04 16:03:09 +01009036
Willy Tarreaud63335a2010-02-26 12:56:52 +01009037 See also : "stats auth", "stats enable", "stats realm", "stats uri"
Willy Tarreau1d45b7c2009-08-16 10:29:18 +02009038
Willy Tarreau983e01e2010-01-11 18:42:06 +01009039
Cyril Bonté2be1b3f2010-09-30 23:46:30 +02009040stats http-request { allow | deny | auth [realm <realm>] }
9041 [ { if | unless } <condition> ]
9042 Access control for statistics
9043
9044 May be used in sections: defaults | frontend | listen | backend
9045 no | no | yes | yes
9046
9047 As "http-request", these set of options allow to fine control access to
9048 statistics. Each option may be followed by if/unless and acl.
9049 First option with matched condition (or option without condition) is final.
9050 For "deny" a 403 error will be returned, for "allow" normal processing is
9051 performed, for "auth" a 401/407 error code is returned so the client
9052 should be asked to enter a username and password.
9053
9054 There is no fixed limit to the number of http-request statements per
9055 instance.
9056
9057 See also : "http-request", section 3.4 about userlists and section 7
9058 about ACL usage.
9059
9060
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009061stats realm <realm>
9062 Enable statistics and set authentication realm
9063 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009064 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009065 Arguments :
9066 <realm> is the name of the HTTP Basic Authentication realm reported to
9067 the browser. The browser uses it to display it in the pop-up
9068 inviting the user to enter a valid username and password.
9069
9070 The realm is read as a single word, so any spaces in it should be escaped
9071 using a backslash ('\').
9072
9073 This statement is useful only in conjunction with "stats auth" since it is
9074 only related to authentication.
9075
9076 Though this statement alone is enough to enable statistics reporting, it is
9077 recommended to set all other settings in order to avoid relying on default
9078 unobvious parameters.
9079
9080 Example :
9081 # public access (limited to this backend only)
9082 backend public_www
9083 server srv1 192.168.0.1:80
9084 stats enable
9085 stats hide-version
9086 stats scope .
9087 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009088 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009089 stats auth admin1:AdMiN123
9090 stats auth admin2:AdMiN321
9091
9092 # internal monitoring access (unlimited)
9093 backend private_monitoring
9094 stats enable
9095 stats uri /admin?stats
9096 stats refresh 5s
9097
9098 See also : "stats auth", "stats enable", "stats uri"
9099
9100
9101stats refresh <delay>
9102 Enable statistics with automatic refresh
9103 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009104 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009105 Arguments :
9106 <delay> is the suggested refresh delay, specified in seconds, which will
9107 be returned to the browser consulting the report page. While the
9108 browser is free to apply any delay, it will generally respect it
9109 and refresh the page this every seconds. The refresh interval may
9110 be specified in any other non-default time unit, by suffixing the
9111 unit after the value, as explained at the top of this document.
9112
9113 This statement is useful on monitoring displays with a permanent page
9114 reporting the load balancer's activity. When set, the HTML report page will
9115 include a link "refresh"/"stop refresh" so that the user can select whether
9116 he wants automatic refresh of the page or not.
9117
9118 Though this statement alone is enough to enable statistics reporting, it is
9119 recommended to set all other settings in order to avoid relying on default
9120 unobvious parameters.
9121
9122 Example :
9123 # public access (limited to this backend only)
9124 backend public_www
9125 server srv1 192.168.0.1:80
9126 stats enable
9127 stats hide-version
9128 stats scope .
9129 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009130 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009131 stats auth admin1:AdMiN123
9132 stats auth admin2:AdMiN321
9133
9134 # internal monitoring access (unlimited)
9135 backend private_monitoring
9136 stats enable
9137 stats uri /admin?stats
9138 stats refresh 5s
9139
9140 See also : "stats auth", "stats enable", "stats realm", "stats uri"
9141
9142
9143stats scope { <name> | "." }
9144 Enable statistics and limit access scope
9145 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009146 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009147 Arguments :
9148 <name> is the name of a listen, frontend or backend section to be
9149 reported. The special name "." (a single dot) designates the
9150 section in which the statement appears.
9151
9152 When this statement is specified, only the sections enumerated with this
9153 statement will appear in the report. All other ones will be hidden. This
9154 statement may appear as many times as needed if multiple sections need to be
9155 reported. Please note that the name checking is performed as simple string
9156 comparisons, and that it is never checked that a give section name really
9157 exists.
9158
9159 Though this statement alone is enough to enable statistics reporting, it is
9160 recommended to set all other settings in order to avoid relying on default
9161 unobvious parameters.
9162
9163 Example :
9164 # public access (limited to this backend only)
9165 backend public_www
9166 server srv1 192.168.0.1:80
9167 stats enable
9168 stats hide-version
9169 stats scope .
9170 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009171 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009172 stats auth admin1:AdMiN123
9173 stats auth admin2:AdMiN321
9174
9175 # internal monitoring access (unlimited)
9176 backend private_monitoring
9177 stats enable
9178 stats uri /admin?stats
9179 stats refresh 5s
9180
9181 See also : "stats auth", "stats enable", "stats realm", "stats uri"
9182
Willy Tarreaud63335a2010-02-26 12:56:52 +01009183
Willy Tarreauc9705a12010-07-27 20:05:50 +02009184stats show-desc [ <desc> ]
Willy Tarreaud63335a2010-02-26 12:56:52 +01009185 Enable reporting of a description on the statistics page.
9186 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009187 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01009188
Willy Tarreauc9705a12010-07-27 20:05:50 +02009189 <desc> is an optional description to be reported. If unspecified, the
Willy Tarreaud63335a2010-02-26 12:56:52 +01009190 description from global section is automatically used instead.
9191
9192 This statement is useful for users that offer shared services to their
9193 customers, where node or description should be different for each customer.
9194
9195 Though this statement alone is enough to enable statistics reporting, it is
9196 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01009197 unobvious parameters. By default description is not shown.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009198
9199 Example :
9200 # internal monitoring access (unlimited)
9201 backend private_monitoring
9202 stats enable
9203 stats show-desc Master node for Europe, Asia, Africa
9204 stats uri /admin?stats
9205 stats refresh 5s
9206
9207 See also: "show-node", "stats enable", "stats uri" and "description" in
9208 global section.
9209
9210
9211stats show-legends
Willy Tarreaued2119c2014-04-24 22:10:39 +02009212 Enable reporting additional information on the statistics page
9213 May be used in sections : defaults | frontend | listen | backend
9214 yes | yes | yes | yes
9215 Arguments : none
9216
Jarno Huuskonen0e82b922014-04-12 18:22:19 +03009217 Enable reporting additional information on the statistics page :
Willy Tarreaud63335a2010-02-26 12:56:52 +01009218 - cap: capabilities (proxy)
9219 - mode: one of tcp, http or health (proxy)
9220 - id: SNMP ID (proxy, socket, server)
9221 - IP (socket, server)
9222 - cookie (backend, server)
9223
9224 Though this statement alone is enough to enable statistics reporting, it is
9225 recommended to set all other settings in order to avoid relying on default
Davor Ocelice9ed2812017-12-25 17:49:28 +01009226 unobvious parameters. Default behavior is not to show this information.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009227
9228 See also: "stats enable", "stats uri".
9229
9230
9231stats show-node [ <name> ]
9232 Enable reporting of a host name on the statistics page.
9233 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009234 yes | yes | yes | yes
Willy Tarreaud63335a2010-02-26 12:56:52 +01009235 Arguments:
9236 <name> is an optional name to be reported. If unspecified, the
9237 node name from global section is automatically used instead.
9238
9239 This statement is useful for users that offer shared services to their
9240 customers, where node or description might be different on a stats page
Davor Ocelice9ed2812017-12-25 17:49:28 +01009241 provided for each customer. Default behavior is not to show host name.
Willy Tarreaud63335a2010-02-26 12:56:52 +01009242
9243 Though this statement alone is enough to enable statistics reporting, it is
9244 recommended to set all other settings in order to avoid relying on default
9245 unobvious parameters.
9246
9247 Example:
9248 # internal monitoring access (unlimited)
9249 backend private_monitoring
9250 stats enable
9251 stats show-node Europe-1
9252 stats uri /admin?stats
9253 stats refresh 5s
9254
9255 See also: "show-desc", "stats enable", "stats uri", and "node" in global
9256 section.
9257
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009258
9259stats uri <prefix>
9260 Enable statistics and define the URI prefix to access them
9261 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaued2119c2014-04-24 22:10:39 +02009262 yes | yes | yes | yes
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009263 Arguments :
9264 <prefix> is the prefix of any URI which will be redirected to stats. This
9265 prefix may contain a question mark ('?') to indicate part of a
9266 query string.
9267
9268 The statistics URI is intercepted on the relayed traffic, so it appears as a
9269 page within the normal application. It is strongly advised to ensure that the
9270 selected URI will never appear in the application, otherwise it will never be
9271 possible to reach it in the application.
9272
9273 The default URI compiled in haproxy is "/haproxy?stats", but this may be
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +01009274 changed at build time, so it's better to always explicitly specify it here.
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009275 It is generally a good idea to include a question mark in the URI so that
9276 intermediate proxies refrain from caching the results. Also, since any string
9277 beginning with the prefix will be accepted as a stats request, the question
9278 mark helps ensuring that no valid URI will begin with the same words.
9279
9280 It is sometimes very convenient to use "/" as the URI prefix, and put that
9281 statement in a "listen" instance of its own. That makes it easy to dedicate
9282 an address or a port to statistics only.
9283
9284 Though this statement alone is enough to enable statistics reporting, it is
9285 recommended to set all other settings in order to avoid relying on default
9286 unobvious parameters.
9287
9288 Example :
9289 # public access (limited to this backend only)
9290 backend public_www
9291 server srv1 192.168.0.1:80
9292 stats enable
9293 stats hide-version
9294 stats scope .
9295 stats uri /admin?stats
Davor Ocelice9ed2812017-12-25 17:49:28 +01009296 stats realm HAProxy\ Statistics
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009297 stats auth admin1:AdMiN123
9298 stats auth admin2:AdMiN321
9299
9300 # internal monitoring access (unlimited)
9301 backend private_monitoring
9302 stats enable
9303 stats uri /admin?stats
9304 stats refresh 5s
9305
9306 See also : "stats auth", "stats enable", "stats realm"
9307
9308
Willy Tarreaud63335a2010-02-26 12:56:52 +01009309stick match <pattern> [table <table>] [{if | unless} <cond>]
9310 Define a request pattern matching condition to stick a user to a server
Willy Tarreaueabeafa2008-01-16 16:17:06 +01009311 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaud63335a2010-02-26 12:56:52 +01009312 no | no | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009313
9314 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009315 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009316 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01009317 will be analyzed in the hope to find a matching entry in a
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009318 stickiness table. This rule is mandatory.
9319
9320 <table> is an optional stickiness table name. If unspecified, the same
9321 backend's table is used. A stickiness table is declared using
9322 the "stick-table" statement.
9323
9324 <cond> is an optional matching condition. It makes it possible to match
9325 on a certain criterion only when other conditions are met (or
9326 not met). For instance, it could be used to match on a source IP
9327 address except when a request passes through a known proxy, in
9328 which case we'd match on a header containing that IP address.
9329
9330 Some protocols or applications require complex stickiness rules and cannot
9331 always simply rely on cookies nor hashing. The "stick match" statement
9332 describes a rule to extract the stickiness criterion from an incoming request
9333 or connection. See section 7 for a complete list of possible patterns and
9334 transformation rules.
9335
9336 The table has to be declared using the "stick-table" statement. It must be of
9337 a type compatible with the pattern. By default it is the one which is present
9338 in the same backend. It is possible to share a table with other backends by
9339 referencing it using the "table" keyword. If another table is referenced,
9340 the server's ID inside the backends are used. By default, all server IDs
9341 start at 1 in each backend, so the server ordering is enough. But in case of
9342 doubt, it is highly recommended to force server IDs using their "id" setting.
9343
9344 It is possible to restrict the conditions where a "stick match" statement
9345 will apply, using "if" or "unless" followed by a condition. See section 7 for
9346 ACL based conditions.
9347
9348 There is no limit on the number of "stick match" statements. The first that
9349 applies and matches will cause the request to be directed to the same server
9350 as was used for the request which created the entry. That way, multiple
9351 matches can be used as fallbacks.
9352
9353 The stick rules are checked after the persistence cookies, so they will not
9354 affect stickiness if a cookie has already been used to select a server. That
9355 way, it becomes very easy to insert cookies and match on IP addresses in
9356 order to maintain stickiness between HTTP and HTTPS.
9357
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009358 Note : Consider not using this feature in multi-process mode (nbproc > 1)
9359 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009360 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009361
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009362 Example :
9363 # forward SMTP users to the same server they just used for POP in the
9364 # last 30 minutes
9365 backend pop
9366 mode tcp
9367 balance roundrobin
9368 stick store-request src
9369 stick-table type ip size 200k expire 30m
9370 server s1 192.168.1.1:110
9371 server s2 192.168.1.1:110
9372
9373 backend smtp
9374 mode tcp
9375 balance roundrobin
9376 stick match src table pop
9377 server s1 192.168.1.1:25
9378 server s2 192.168.1.1:25
9379
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009380 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02009381 about ACLs and samples fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009382
9383
9384stick on <pattern> [table <table>] [{if | unless} <condition>]
9385 Define a request pattern to associate a user to a server
9386 May be used in sections : defaults | frontend | listen | backend
9387 no | no | yes | yes
9388
9389 Note : This form is exactly equivalent to "stick match" followed by
9390 "stick store-request", all with the same arguments. Please refer
9391 to both keywords for details. It is only provided as a convenience
9392 for writing more maintainable configurations.
9393
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009394 Note : Consider not using this feature in multi-process mode (nbproc > 1)
9395 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009396 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009397
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009398 Examples :
9399 # The following form ...
Willy Tarreauec579d82010-02-26 19:15:04 +01009400 stick on src table pop if !localhost
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009401
9402 # ...is strictly equivalent to this one :
9403 stick match src table pop if !localhost
9404 stick store-request src table pop if !localhost
9405
9406
9407 # Use cookie persistence for HTTP, and stick on source address for HTTPS as
9408 # well as HTTP without cookie. Share the same table between both accesses.
9409 backend http
9410 mode http
9411 balance roundrobin
9412 stick on src table https
9413 cookie SRV insert indirect nocache
9414 server s1 192.168.1.1:80 cookie s1
9415 server s2 192.168.1.1:80 cookie s2
9416
9417 backend https
9418 mode tcp
9419 balance roundrobin
9420 stick-table type ip size 200k expire 30m
9421 stick on src
9422 server s1 192.168.1.1:443
9423 server s2 192.168.1.1:443
9424
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009425 See also : "stick match", "stick store-request", "nbproc" and "bind-process".
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009426
9427
9428stick store-request <pattern> [table <table>] [{if | unless} <condition>]
9429 Define a request pattern used to create an entry in a stickiness table
9430 May be used in sections : defaults | frontend | listen | backend
9431 no | no | yes | yes
9432
9433 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009434 <pattern> is a sample expression rule as described in section 7.3. It
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009435 describes what elements of the incoming request or connection
Davor Ocelice9ed2812017-12-25 17:49:28 +01009436 will be analyzed, extracted and stored in the table once a
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009437 server is selected.
9438
9439 <table> is an optional stickiness table name. If unspecified, the same
9440 backend's table is used. A stickiness table is declared using
9441 the "stick-table" statement.
9442
9443 <cond> is an optional storage condition. It makes it possible to store
9444 certain criteria only when some conditions are met (or not met).
9445 For instance, it could be used to store the source IP address
9446 except when the request passes through a known proxy, in which
9447 case we'd store a converted form of a header containing that IP
9448 address.
9449
9450 Some protocols or applications require complex stickiness rules and cannot
9451 always simply rely on cookies nor hashing. The "stick store-request" statement
9452 describes a rule to decide what to extract from the request and when to do
9453 it, in order to store it into a stickiness table for further requests to
9454 match it using the "stick match" statement. Obviously the extracted part must
9455 make sense and have a chance to be matched in a further request. Storing a
9456 client's IP address for instance often makes sense. Storing an ID found in a
9457 URL parameter also makes sense. Storing a source port will almost never make
9458 any sense because it will be randomly matched. See section 7 for a complete
9459 list of possible patterns and transformation rules.
9460
9461 The table has to be declared using the "stick-table" statement. It must be of
9462 a type compatible with the pattern. By default it is the one which is present
9463 in the same backend. It is possible to share a table with other backends by
9464 referencing it using the "table" keyword. If another table is referenced,
9465 the server's ID inside the backends are used. By default, all server IDs
9466 start at 1 in each backend, so the server ordering is enough. But in case of
9467 doubt, it is highly recommended to force server IDs using their "id" setting.
9468
9469 It is possible to restrict the conditions where a "stick store-request"
9470 statement will apply, using "if" or "unless" followed by a condition. This
9471 condition will be evaluated while parsing the request, so any criteria can be
9472 used. See section 7 for ACL based conditions.
9473
9474 There is no limit on the number of "stick store-request" statements, but
9475 there is a limit of 8 simultaneous stores per request or response. This
9476 makes it possible to store up to 8 criteria, all extracted from either the
9477 request or the response, regardless of the number of rules. Only the 8 first
9478 ones which match will be kept. Using this, it is possible to feed multiple
9479 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01009480 another protocol or access method. Using multiple store-request rules with
9481 the same table is possible and may be used to find the best criterion to rely
9482 on, by arranging the rules by decreasing preference order. Only the first
9483 extracted criterion for a given table will be stored. All subsequent store-
9484 request rules referencing the same table will be skipped and their ACLs will
9485 not be evaluated.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009486
9487 The "store-request" rules are evaluated once the server connection has been
9488 established, so that the table will contain the real server that processed
9489 the request.
9490
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009491 Note : Consider not using this feature in multi-process mode (nbproc > 1)
9492 unless you know what you do : memory is not shared between the
Davor Ocelice9ed2812017-12-25 17:49:28 +01009493 processes, which can result in random behaviors.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009494
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009495 Example :
9496 # forward SMTP users to the same server they just used for POP in the
9497 # last 30 minutes
9498 backend pop
9499 mode tcp
9500 balance roundrobin
9501 stick store-request src
9502 stick-table type ip size 200k expire 30m
9503 server s1 192.168.1.1:110
9504 server s2 192.168.1.1:110
9505
9506 backend smtp
9507 mode tcp
9508 balance roundrobin
9509 stick match src table pop
9510 server s1 192.168.1.1:25
9511 server s2 192.168.1.1:25
9512
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009513 See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7
Willy Tarreaube722a22014-06-13 16:31:59 +02009514 about ACLs and sample fetching.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009515
9516
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009517stick-table type {ip | integer | string [len <length>] | binary [len <length>]}
Emeric Brunf099e792010-09-27 12:05:28 +02009518 size <size> [expire <expire>] [nopurge] [peers <peersect>]
9519 [store <data_type>]*
Godbach64cef792013-12-04 16:08:22 +08009520 Configure the stickiness table for the current section
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009521 May be used in sections : defaults | frontend | listen | backend
Willy Tarreauc00cdc22010-06-06 16:48:26 +02009522 no | yes | yes | yes
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009523
9524 Arguments :
9525 ip a table declared with "type ip" will only store IPv4 addresses.
9526 This form is very compact (about 50 bytes per entry) and allows
9527 very fast entry lookup and stores with almost no overhead. This
9528 is mainly used to store client source IP addresses.
9529
David du Colombier9a6d3c92011-03-17 10:40:24 +01009530 ipv6 a table declared with "type ipv6" will only store IPv6 addresses.
9531 This form is very compact (about 60 bytes per entry) and allows
9532 very fast entry lookup and stores with almost no overhead. This
9533 is mainly used to store client source IP addresses.
9534
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009535 integer a table declared with "type integer" will store 32bit integers
9536 which can represent a client identifier found in a request for
9537 instance.
9538
9539 string a table declared with "type string" will store substrings of up
9540 to <len> characters. If the string provided by the pattern
9541 extractor is larger than <len>, it will be truncated before
9542 being stored. During matching, at most <len> characters will be
9543 compared between the string in the table and the extracted
9544 pattern. When not specified, the string is automatically limited
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009545 to 32 characters.
9546
9547 binary a table declared with "type binary" will store binary blocks
9548 of <len> bytes. If the block provided by the pattern
9549 extractor is larger than <len>, it will be truncated before
Willy Tarreaube722a22014-06-13 16:31:59 +02009550 being stored. If the block provided by the sample expression
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009551 is shorter than <len>, it will be padded by 0. When not
9552 specified, the block is automatically limited to 32 bytes.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009553
9554 <length> is the maximum number of characters that will be stored in a
Emeric Brun7c6b82e2010-09-24 16:34:28 +02009555 "string" type table (See type "string" above). Or the number
9556 of bytes of the block in "binary" type table. Be careful when
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009557 changing this parameter as memory usage will proportionally
9558 increase.
9559
9560 <size> is the maximum number of entries that can fit in the table. This
Cyril Bonté78caf842010-03-10 22:41:43 +01009561 value directly impacts memory usage. Count approximately
9562 50 bytes per entry, plus the size of a string if any. The size
9563 supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009564
9565 [nopurge] indicates that we refuse to purge older entries when the table
9566 is full. When not specified and the table is full when haproxy
9567 wants to store an entry in it, it will flush a few of the oldest
9568 entries in order to release some space for the new ones. This is
Davor Ocelice9ed2812017-12-25 17:49:28 +01009569 most often the desired behavior. In some specific cases, it
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009570 be desirable to refuse new entries instead of purging the older
9571 ones. That may be the case when the amount of data to store is
9572 far above the hardware limits and we prefer not to offer access
9573 to new clients than to reject the ones already connected. When
9574 using this parameter, be sure to properly set the "expire"
9575 parameter (see below).
9576
Emeric Brunf099e792010-09-27 12:05:28 +02009577 <peersect> is the name of the peers section to use for replication. Entries
9578 which associate keys to server IDs are kept synchronized with
9579 the remote peers declared in this section. All entries are also
9580 automatically learned from the local peer (old process) during a
9581 soft restart.
9582
Willy Tarreau1abc6732015-05-01 19:21:02 +02009583 NOTE : each peers section may be referenced only by tables
9584 belonging to the same unique process.
Cyril Bonté02ff8ef2010-12-14 22:48:49 +01009585
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009586 <expire> defines the maximum duration of an entry in the table since it
9587 was last created, refreshed or matched. The expiration delay is
9588 defined using the standard time format, similarly as the various
9589 timeouts. The maximum duration is slightly above 24 days. See
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03009590 section 2.4 for more information. If this delay is not specified,
Cyril Bontédc4d9032012-04-08 21:57:39 +02009591 the session won't automatically expire, but older entries will
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009592 be removed once full. Be sure not to use the "nopurge" parameter
9593 if not expiration delay is specified.
9594
Willy Tarreau08d5f982010-06-06 13:34:54 +02009595 <data_type> is used to store additional information in the stick-table. This
9596 may be used by ACLs in order to control various criteria related
9597 to the activity of the client matching the stick-table. For each
9598 item specified here, the size of each entry will be inflated so
Willy Tarreauc9705a12010-07-27 20:05:50 +02009599 that the additional data can fit. Several data types may be
9600 stored with an entry. Multiple data types may be specified after
9601 the "store" keyword, as a comma-separated list. Alternatively,
9602 it is possible to repeat the "store" keyword followed by one or
9603 several data types. Except for the "server_id" type which is
9604 automatically detected and enabled, all data types must be
9605 explicitly declared to be stored. If an ACL references a data
9606 type which is not stored, the ACL will simply not match. Some
9607 data types require an argument which must be passed just after
9608 the type between parenthesis. See below for the supported data
9609 types and their arguments.
9610
9611 The data types that can be stored with an entry are the following :
9612 - server_id : this is an integer which holds the numeric ID of the server a
9613 request was assigned to. It is used by the "stick match", "stick store",
9614 and "stick on" rules. It is automatically enabled when referenced.
9615
9616 - gpc0 : first General Purpose Counter. It is a positive 32-bit integer
9617 integer which may be used for anything. Most of the time it will be used
9618 to put a special tag on some entries, for instance to note that a
Davor Ocelice9ed2812017-12-25 17:49:28 +01009619 specific behavior was detected and must be known for future matches.
Willy Tarreauc9705a12010-07-27 20:05:50 +02009620
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009621 - gpc0_rate(<period>) : increment rate of the first General Purpose Counter
9622 over a period. It is a positive 32-bit integer integer which may be used
9623 for anything. Just like <gpc0>, it counts events, but instead of keeping
Davor Ocelice9ed2812017-12-25 17:49:28 +01009624 a cumulative number, it maintains the rate at which the counter is
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009625 incremented. Most of the time it will be used to measure the frequency of
Davor Ocelice9ed2812017-12-25 17:49:28 +01009626 occurrence of certain events (e.g. requests to a specific URL).
Willy Tarreauba2ffd12013-05-29 15:54:14 +02009627
Frédéric Lécaille6778b272018-01-29 15:22:53 +01009628 - gpc1 : second General Purpose Counter. It is a positive 32-bit integer
9629 integer which may be used for anything. Most of the time it will be used
9630 to put a special tag on some entries, for instance to note that a
9631 specific behavior was detected and must be known for future matches.
9632
9633 - gpc1_rate(<period>) : increment rate of the second General Purpose Counter
9634 over a period. It is a positive 32-bit integer integer which may be used
9635 for anything. Just like <gpc1>, it counts events, but instead of keeping
9636 a cumulative number, it maintains the rate at which the counter is
9637 incremented. Most of the time it will be used to measure the frequency of
9638 occurrence of certain events (e.g. requests to a specific URL).
9639
Willy Tarreauc9705a12010-07-27 20:05:50 +02009640 - conn_cnt : Connection Count. It is a positive 32-bit integer which counts
9641 the absolute number of connections received from clients which matched
9642 this entry. It does not mean the connections were accepted, just that
9643 they were received.
9644
9645 - conn_cur : Current Connections. It is a positive 32-bit integer which
9646 stores the concurrent connection counts for the entry. It is incremented
9647 once an incoming connection matches the entry, and decremented once the
9648 connection leaves. That way it is possible to know at any time the exact
9649 number of concurrent connections for an entry.
9650
9651 - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9652 integer parameter <period> which indicates in milliseconds the length
9653 of the period over which the average is measured. It reports the average
9654 incoming connection rate over that period, in connections per period. The
9655 result is an integer which can be matched using ACLs.
9656
9657 - sess_cnt : Session Count. It is a positive 32-bit integer which counts
9658 the absolute number of sessions received from clients which matched this
9659 entry. A session is a connection that was accepted by the layer 4 rules.
9660
9661 - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9662 integer parameter <period> which indicates in milliseconds the length
9663 of the period over which the average is measured. It reports the average
9664 incoming session rate over that period, in sessions per period. The
9665 result is an integer which can be matched using ACLs.
9666
9667 - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which
9668 counts the absolute number of HTTP requests received from clients which
9669 matched this entry. It does not matter whether they are valid requests or
9670 not. Note that this is different from sessions when keep-alive is used on
9671 the client side.
9672
9673 - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9674 integer parameter <period> which indicates in milliseconds the length
9675 of the period over which the average is measured. It reports the average
9676 HTTP request rate over that period, in requests per period. The result is
9677 an integer which can be matched using ACLs. It does not matter whether
9678 they are valid requests or not. Note that this is different from sessions
9679 when keep-alive is used on the client side.
9680
9681 - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which
9682 counts the absolute number of HTTP requests errors induced by clients
9683 which matched this entry. Errors are counted on invalid and truncated
9684 requests, as well as on denied or tarpitted requests, and on failed
9685 authentications. If the server responds with 4xx, then the request is
9686 also counted as an error since it's an error triggered by the client
Davor Ocelice9ed2812017-12-25 17:49:28 +01009687 (e.g. vulnerability scan).
Willy Tarreauc9705a12010-07-27 20:05:50 +02009688
9689 - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9690 integer parameter <period> which indicates in milliseconds the length
9691 of the period over which the average is measured. It reports the average
9692 HTTP request error rate over that period, in requests per period (see
9693 http_err_cnt above for what is accounted as an error). The result is an
9694 integer which can be matched using ACLs.
9695
9696 - bytes_in_cnt : client to server byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +01009697 integer which counts the cumulative number of bytes received from clients
Willy Tarreauc9705a12010-07-27 20:05:50 +02009698 which matched this entry. Headers are included in the count. This may be
9699 used to limit abuse of upload features on photo or video servers.
9700
9701 - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an
9702 integer parameter <period> which indicates in milliseconds the length
9703 of the period over which the average is measured. It reports the average
9704 incoming bytes rate over that period, in bytes per period. It may be used
9705 to detect users which upload too much and too fast. Warning: with large
9706 uploads, it is possible that the amount of uploaded data will be counted
9707 once upon termination, thus causing spikes in the average transfer speed
9708 instead of having a smooth one. This may partially be smoothed with
9709 "option contstats" though this is not perfect yet. Use of byte_in_cnt is
9710 recommended for better fairness.
9711
9712 - bytes_out_cnt : server to client byte count. It is a positive 64-bit
Davor Ocelice9ed2812017-12-25 17:49:28 +01009713 integer which counts the cumulative number of bytes sent to clients which
Willy Tarreauc9705a12010-07-27 20:05:50 +02009714 matched this entry. Headers are included in the count. This may be used
9715 to limit abuse of bots sucking the whole site.
9716
9717 - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes
9718 an integer parameter <period> which indicates in milliseconds the length
9719 of the period over which the average is measured. It reports the average
9720 outgoing bytes rate over that period, in bytes per period. It may be used
9721 to detect users which download too much and too fast. Warning: with large
9722 transfers, it is possible that the amount of transferred data will be
9723 counted once upon termination, thus causing spikes in the average
9724 transfer speed instead of having a smooth one. This may partially be
9725 smoothed with "option contstats" though this is not perfect yet. Use of
9726 byte_out_cnt is recommended for better fairness.
Willy Tarreau08d5f982010-06-06 13:34:54 +02009727
Willy Tarreauc00cdc22010-06-06 16:48:26 +02009728 There is only one stick-table per proxy. At the moment of writing this doc,
9729 it does not seem useful to have multiple tables per proxy. If this happens
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009730 to be required, simply create a dummy backend with a stick-table in it and
9731 reference it.
9732
9733 It is important to understand that stickiness based on learning information
9734 has some limitations, including the fact that all learned associations are
Baptiste Assmann123ff042016-03-06 23:29:28 +01009735 lost upon restart unless peers are properly configured to transfer such
9736 information upon restart (recommended). In general it can be good as a
9737 complement but not always as an exclusive stickiness.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009738
Willy Tarreauc9705a12010-07-27 20:05:50 +02009739 Last, memory requirements may be important when storing many data types.
9740 Indeed, storing all indicators above at once in each entry requires 116 bytes
9741 per entry, or 116 MB for a 1-million entries table. This is definitely not
9742 something that can be ignored.
9743
9744 Example:
9745 # Keep track of counters of up to 1 million IP addresses over 5 minutes
9746 # and store a general purpose counter and the average connection rate
9747 # computed over a sliding window of 30 seconds.
9748 stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s)
9749
Jarno Huuskonene0ee0be2017-07-04 10:35:12 +03009750 See also : "stick match", "stick on", "stick store-request", section 2.4
David du Colombiera13d1b92011-03-17 10:40:22 +01009751 about time format and section 7 about ACLs.
Willy Tarreaub937b7e2010-01-12 15:27:54 +01009752
9753
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009754stick store-response <pattern> [table <table>] [{if | unless} <condition>]
Baptiste Assmann2f2d2ec2016-03-06 23:27:24 +01009755 Define a response pattern used to create an entry in a stickiness table
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009756 May be used in sections : defaults | frontend | listen | backend
9757 no | no | yes | yes
9758
9759 Arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +02009760 <pattern> is a sample expression rule as described in section 7.3. It
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009761 describes what elements of the response or connection will
Davor Ocelice9ed2812017-12-25 17:49:28 +01009762 be analyzed, extracted and stored in the table once a
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009763 server is selected.
9764
9765 <table> is an optional stickiness table name. If unspecified, the same
9766 backend's table is used. A stickiness table is declared using
9767 the "stick-table" statement.
9768
9769 <cond> is an optional storage condition. It makes it possible to store
9770 certain criteria only when some conditions are met (or not met).
9771 For instance, it could be used to store the SSL session ID only
9772 when the response is a SSL server hello.
9773
9774 Some protocols or applications require complex stickiness rules and cannot
9775 always simply rely on cookies nor hashing. The "stick store-response"
9776 statement describes a rule to decide what to extract from the response and
9777 when to do it, in order to store it into a stickiness table for further
9778 requests to match it using the "stick match" statement. Obviously the
9779 extracted part must make sense and have a chance to be matched in a further
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009780 request. Storing an ID found in a header of a response makes sense.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009781 See section 7 for a complete list of possible patterns and transformation
9782 rules.
9783
9784 The table has to be declared using the "stick-table" statement. It must be of
9785 a type compatible with the pattern. By default it is the one which is present
9786 in the same backend. It is possible to share a table with other backends by
9787 referencing it using the "table" keyword. If another table is referenced,
9788 the server's ID inside the backends are used. By default, all server IDs
9789 start at 1 in each backend, so the server ordering is enough. But in case of
9790 doubt, it is highly recommended to force server IDs using their "id" setting.
9791
9792 It is possible to restrict the conditions where a "stick store-response"
9793 statement will apply, using "if" or "unless" followed by a condition. This
9794 condition will be evaluated while parsing the response, so any criteria can
9795 be used. See section 7 for ACL based conditions.
9796
9797 There is no limit on the number of "stick store-response" statements, but
9798 there is a limit of 8 simultaneous stores per request or response. This
9799 makes it possible to store up to 8 criteria, all extracted from either the
9800 request or the response, regardless of the number of rules. Only the 8 first
9801 ones which match will be kept. Using this, it is possible to feed multiple
9802 tables at once in the hope to increase the chance to recognize a user on
Willy Tarreau9667a802013-12-09 12:52:13 +01009803 another protocol or access method. Using multiple store-response rules with
9804 the same table is possible and may be used to find the best criterion to rely
9805 on, by arranging the rules by decreasing preference order. Only the first
9806 extracted criterion for a given table will be stored. All subsequent store-
9807 response rules referencing the same table will be skipped and their ACLs will
9808 not be evaluated. However, even if a store-request rule references a table, a
9809 store-response rule may also use the same table. This means that each table
9810 may learn exactly one element from the request and one element from the
9811 response at once.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009812
9813 The table will contain the real server that processed the request.
9814
9815 Example :
9816 # Learn SSL session ID from both request and response and create affinity.
9817 backend https
9818 mode tcp
9819 balance roundrobin
Cyril Bontédc4d9032012-04-08 21:57:39 +02009820 # maximum SSL session ID length is 32 bytes.
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009821 stick-table type binary len 32 size 30k expire 30m
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009822
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009823 acl clienthello req_ssl_hello_type 1
9824 acl serverhello rep_ssl_hello_type 2
9825
9826 # use tcp content accepts to detects ssl client and server hello.
9827 tcp-request inspect-delay 5s
9828 tcp-request content accept if clienthello
9829
9830 # no timeout on response inspect delay by default.
9831 tcp-response content accept if serverhello
Cyril Bonté108cf6e2012-04-21 23:30:29 +02009832
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009833 # SSL session ID (SSLID) may be present on a client or server hello.
9834 # Its length is coded on 1 byte at offset 43 and its value starts
9835 # at offset 44.
9836
9837 # Match and learn on request if client hello.
9838 stick on payload_lv(43,1) if clienthello
9839
9840 # Learn on response if server hello.
9841 stick store-response payload_lv(43,1) if serverhello
Cyril Bontédc4d9032012-04-08 21:57:39 +02009842
Emeric Brun6a1cefa2010-09-24 18:15:17 +02009843 server s1 192.168.1.1:443
9844 server s2 192.168.1.1:443
9845
9846 See also : "stick-table", "stick on", and section 7 about ACLs and pattern
9847 extraction.
9848
9849
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009850tcp-check connect [params*]
9851 Opens a new connection
9852 May be used in sections: defaults | frontend | listen | backend
9853 no | no | yes | yes
9854
9855 When an application lies on more than a single TCP port or when HAProxy
9856 load-balance many services in a single backend, it makes sense to probe all
9857 the services individually before considering a server as operational.
9858
9859 When there are no TCP port configured on the server line neither server port
9860 directive, then the 'tcp-check connect port <port>' must be the first step
9861 of the sequence.
9862
9863 In a tcp-check ruleset a 'connect' is required, it is also mandatory to start
9864 the ruleset with a 'connect' rule. Purpose is to ensure admin know what they
9865 do.
9866
9867 Parameters :
9868 They are optional and can be used to describe how HAProxy should open and
9869 use the TCP connection.
9870
9871 port if not set, check port or server port is used.
9872 It tells HAProxy where to open the connection to.
9873 <port> must be a valid TCP port source integer, from 1 to 65535.
9874
9875 send-proxy send a PROXY protocol string
9876
9877 ssl opens a ciphered connection
9878
9879 Examples:
9880 # check HTTP and HTTPs services on a server.
9881 # first open port 80 thanks to server line port directive, then
9882 # tcp-check opens port 443, ciphered and run a request on it:
9883 option tcp-check
9884 tcp-check connect
9885 tcp-check send GET\ /\ HTTP/1.0\r\n
9886 tcp-check send Host:\ haproxy.1wt.eu\r\n
9887 tcp-check send \r\n
9888 tcp-check expect rstring (2..|3..)
9889 tcp-check connect port 443 ssl
9890 tcp-check send GET\ /\ HTTP/1.0\r\n
9891 tcp-check send Host:\ haproxy.1wt.eu\r\n
9892 tcp-check send \r\n
9893 tcp-check expect rstring (2..|3..)
9894 server www 10.0.0.1 check port 80
9895
9896 # check both POP and IMAP from a single server:
9897 option tcp-check
9898 tcp-check connect port 110
9899 tcp-check expect string +OK\ POP3\ ready
9900 tcp-check connect port 143
9901 tcp-check expect string *\ OK\ IMAP4\ ready
9902 server mail 10.0.0.1 check
9903
9904 See also : "option tcp-check", "tcp-check send", "tcp-check expect"
9905
9906
9907tcp-check expect [!] <match> <pattern>
Davor Ocelice9ed2812017-12-25 17:49:28 +01009908 Specify data to be collected and analyzed during a generic health check
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009909 May be used in sections: defaults | frontend | listen | backend
9910 no | no | yes | yes
9911
9912 Arguments :
9913 <match> is a keyword indicating how to look for a specific pattern in the
9914 response. The keyword may be one of "string", "rstring" or
9915 binary.
9916 The keyword may be preceded by an exclamation mark ("!") to negate
9917 the match. Spaces are allowed between the exclamation mark and the
9918 keyword. See below for more details on the supported keywords.
9919
9920 <pattern> is the pattern to look for. It may be a string or a regular
9921 expression. If the pattern contains spaces, they must be escaped
9922 with the usual backslash ('\').
9923 If the match is set to binary, then the pattern must be passed as
Davor Ocelice9ed2812017-12-25 17:49:28 +01009924 a series of hexadecimal digits in an even number. Each sequence of
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009925 two digits will represent a byte. The hexadecimal digits may be
9926 used upper or lower case.
9927
9928
9929 The available matches are intentionally similar to their http-check cousins :
9930
9931 string <string> : test the exact string matches in the response buffer.
9932 A health check response will be considered valid if the
9933 response's buffer contains this exact string. If the
9934 "string" keyword is prefixed with "!", then the response
9935 will be considered invalid if the body contains this
9936 string. This can be used to look for a mandatory pattern
9937 in a protocol response, or to detect a failure when a
9938 specific error appears in a protocol banner.
9939
9940 rstring <regex> : test a regular expression on the response buffer.
9941 A health check response will be considered valid if the
9942 response's buffer matches this expression. If the
9943 "rstring" keyword is prefixed with "!", then the response
9944 will be considered invalid if the body matches the
9945 expression.
9946
9947 binary <hexstring> : test the exact string in its hexadecimal form matches
9948 in the response buffer. A health check response will
9949 be considered valid if the response's buffer contains
9950 this exact hexadecimal string.
9951 Purpose is to match data on binary protocols.
9952
9953 It is important to note that the responses will be limited to a certain size
9954 defined by the global "tune.chksize" option, which defaults to 16384 bytes.
9955 Thus, too large responses may not contain the mandatory pattern when using
9956 "string", "rstring" or binary. If a large response is absolutely required, it
9957 is possible to change the default max size by setting the global variable.
9958 However, it is worth keeping in mind that parsing very large responses can
9959 waste some CPU cycles, especially when regular expressions are used, and that
9960 it is always better to focus the checks on smaller resources. Also, in its
9961 current state, the check will not find any string nor regex past a null
9962 character in the response. Similarly it is not possible to request matching
9963 the null character.
9964
9965 Examples :
9966 # perform a POP check
9967 option tcp-check
9968 tcp-check expect string +OK\ POP3\ ready
9969
9970 # perform an IMAP check
9971 option tcp-check
9972 tcp-check expect string *\ OK\ IMAP4\ ready
9973
9974 # look for the redis master server
9975 option tcp-check
9976 tcp-check send PING\r\n
Baptiste Assmanna3322992015-08-04 10:12:18 +02009977 tcp-check expect string +PONG
Willy Tarreau938c7fe2014-04-25 14:21:39 +02009978 tcp-check send info\ replication\r\n
9979 tcp-check expect string role:master
9980 tcp-check send QUIT\r\n
9981 tcp-check expect string +OK
9982
9983
9984 See also : "option tcp-check", "tcp-check connect", "tcp-check send",
9985 "tcp-check send-binary", "http-check expect", tune.chksize
9986
9987
9988tcp-check send <data>
9989 Specify a string to be sent as a question during a generic health check
9990 May be used in sections: defaults | frontend | listen | backend
9991 no | no | yes | yes
9992
9993 <data> : the data to be sent as a question during a generic health check
9994 session. For now, <data> must be a string.
9995
9996 Examples :
9997 # look for the redis master server
9998 option tcp-check
9999 tcp-check send info\ replication\r\n
10000 tcp-check expect string role:master
10001
10002 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
10003 "tcp-check send-binary", tune.chksize
10004
10005
Davor Ocelice9ed2812017-12-25 17:49:28 +010010006tcp-check send-binary <hexstring>
10007 Specify a hex digits string to be sent as a binary question during a raw
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010008 tcp health check
10009 May be used in sections: defaults | frontend | listen | backend
10010 no | no | yes | yes
10011
10012 <data> : the data to be sent as a question during a generic health check
10013 session. For now, <data> must be a string.
Davor Ocelice9ed2812017-12-25 17:49:28 +010010014 <hexstring> : test the exact string in its hexadecimal form matches in the
Willy Tarreau938c7fe2014-04-25 14:21:39 +020010015 response buffer. A health check response will be considered
10016 valid if the response's buffer contains this exact
10017 hexadecimal string.
10018 Purpose is to send binary data to ask on binary protocols.
10019
10020 Examples :
10021 # redis check in binary
10022 option tcp-check
10023 tcp-check send-binary 50494e470d0a # PING\r\n
10024 tcp-check expect binary 2b504F4e47 # +PONG
10025
10026
10027 See also : "option tcp-check", "tcp-check connect", "tcp-check expect",
10028 "tcp-check send", tune.chksize
10029
10030
Willy Tarreaue9656522010-08-17 15:40:09 +020010031tcp-request connection <action> [{if | unless} <condition>]
10032 Perform an action on an incoming connection depending on a layer 4 condition
Willy Tarreau1a687942010-05-23 22:40:30 +020010033 May be used in sections : defaults | frontend | listen | backend
10034 no | yes | yes | no
Willy Tarreaue9656522010-08-17 15:40:09 +020010035 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020010036 <action> defines the action to perform if the condition applies. See
10037 below.
Willy Tarreau1a687942010-05-23 22:40:30 +020010038
Willy Tarreaue9656522010-08-17 15:40:09 +020010039 <condition> is a standard layer4-only ACL-based condition (see section 7).
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010040
10041 Immediately after acceptance of a new incoming connection, it is possible to
10042 evaluate some conditions to decide whether this connection must be accepted
Willy Tarreaue9656522010-08-17 15:40:09 +020010043 or dropped or have its counters tracked. Those conditions cannot make use of
10044 any data contents because the connection has not been read from yet, and the
10045 buffers are not yet allocated. This is used to selectively and very quickly
10046 accept or drop connections from various sources with a very low overhead. If
10047 some contents need to be inspected in order to take the decision, the
10048 "tcp-request content" statements must be used instead.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010049
Willy Tarreaue9656522010-08-17 15:40:09 +020010050 The "tcp-request connection" rules are evaluated in their exact declaration
10051 order. If no rule matches or if there is no rule, the default action is to
10052 accept the incoming connection. There is no specific limit to the number of
10053 rules which may be inserted.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010054
Willy Tarreaua9083d02015-05-08 15:27:59 +020010055 Four types of actions are supported :
Willy Tarreaue9656522010-08-17 15:40:09 +020010056 - accept :
10057 accepts the connection if the condition is true (when used with "if")
10058 or false (when used with "unless"). The first such rule executed ends
10059 the rules evaluation.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010060
Willy Tarreaue9656522010-08-17 15:40:09 +020010061 - reject :
10062 rejects the connection if the condition is true (when used with "if")
10063 or false (when used with "unless"). The first such rule executed ends
10064 the rules evaluation. Rejected connections do not even become a
10065 session, which is why they are accounted separately for in the stats,
10066 as "denied connections". They are not considered for the session
10067 rate-limit and are not logged either. The reason is that these rules
10068 should only be used to filter extremely high connection rates such as
10069 the ones encountered during a massive DDoS attack. Under these extreme
10070 conditions, the simple action of logging each event would make the
10071 system collapse and would considerably lower the filtering capacity. If
10072 logging is absolutely desired, then "tcp-request content" rules should
Willy Tarreau4f614292016-10-21 17:49:36 +020010073 be used instead, as "tcp-request session" rules will not log either.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010074
Willy Tarreau4f0d9192013-06-11 20:40:55 +020010075 - expect-proxy layer4 :
10076 configures the client-facing connection to receive a PROXY protocol
10077 header before any byte is read from the socket. This is equivalent to
10078 having the "accept-proxy" keyword on the "bind" line, except that using
10079 the TCP rule allows the PROXY protocol to be accepted only for certain
10080 IP address ranges using an ACL. This is convenient when multiple layers
10081 of load balancers are passed through by traffic coming from public
10082 hosts.
10083
Bertrand Jacquin90759682016-06-06 15:35:39 +010010084 - expect-netscaler-cip layer4 :
10085 configures the client-facing connection to receive a NetScaler Client
10086 IP insertion protocol header before any byte is read from the socket.
10087 This is equivalent to having the "accept-netscaler-cip" keyword on the
10088 "bind" line, except that using the TCP rule allows the PROXY protocol
10089 to be accepted only for certain IP address ranges using an ACL. This
10090 is convenient when multiple layers of load balancers are passed
10091 through by traffic coming from public hosts.
10092
Willy Tarreau18bf01e2014-06-13 16:18:52 +020010093 - capture <sample> len <length> :
10094 This only applies to "tcp-request content" rules. It captures sample
10095 expression <sample> from the request buffer, and converts it to a
10096 string of at most <len> characters. The resulting string is stored into
10097 the next request "capture" slot, so it will possibly appear next to
10098 some captured HTTP headers. It will then automatically appear in the
10099 logs, and it will be possible to extract it using sample fetch rules to
10100 feed it into headers or anything. The length should be limited given
10101 that this size will be allocated for each capture during the whole
Willy Tarreaua9083d02015-05-08 15:27:59 +020010102 session life. Please check section 7.3 (Fetching samples) and "capture
10103 request header" for more information.
Willy Tarreau18bf01e2014-06-13 16:18:52 +020010104
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010105 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
Willy Tarreaue9656522010-08-17 15:40:09 +020010106 enables tracking of sticky counters from current connection. These
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020010107 rules do not stop evaluation and do not change default action. The
10108 number of counters that may be simultaneously tracked by the same
10109 connection is set in MAX_SESS_STKCTR at build time (reported in
John Roesler27c754c2019-07-10 15:45:51 -050010110 haproxy -vv) which defaults to 3, so the track-sc number is between 0
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020010111 and (MAX_SESS_STCKTR-1). The first "track-sc0" rule executed enables
10112 tracking of the counters of the specified table as the first set. The
10113 first "track-sc1" rule executed enables tracking of the counters of the
10114 specified table as the second set. The first "track-sc2" rule executed
10115 enables tracking of the counters of the specified table as the third
10116 set. It is a recommended practice to use the first set of counters for
10117 the per-frontend counters and the second set for the per-backend ones.
10118 But this is just a guideline, all may be used everywhere.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010119
Willy Tarreaue9656522010-08-17 15:40:09 +020010120 These actions take one or two arguments :
Willy Tarreaube722a22014-06-13 16:31:59 +020010121 <key> is mandatory, and is a sample expression rule as described
Willy Tarreau74ca5042013-06-11 23:12:07 +020010122 in section 7.3. It describes what elements of the incoming
Davor Ocelice9ed2812017-12-25 17:49:28 +010010123 request or connection will be analyzed, extracted, combined,
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010124 and used to select which table entry to update the counters.
10125 Note that "tcp-request connection" cannot use content-based
10126 fetches.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010127
Willy Tarreaue9656522010-08-17 15:40:09 +020010128 <table> is an optional table to be used instead of the default one,
10129 which is the stick-table declared in the current proxy. All
10130 the counters for the matches and updates for the key will
10131 then be performed in that table until the session ends.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010132
Willy Tarreaue9656522010-08-17 15:40:09 +020010133 Once a "track-sc*" rule is executed, the key is looked up in the table
10134 and if it is not found, an entry is allocated for it. Then a pointer to
10135 that entry is kept during all the session's life, and this entry's
10136 counters are updated as often as possible, every time the session's
10137 counters are updated, and also systematically when the session ends.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010138 Counters are only updated for events that happen after the tracking has
10139 been started. For example, connection counters will not be updated when
10140 tracking layer 7 information, since the connection event happens before
10141 layer7 information is extracted.
10142
Willy Tarreaue9656522010-08-17 15:40:09 +020010143 If the entry tracks concurrent connection counters, one connection is
10144 counted for as long as the entry is tracked, and the entry will not
10145 expire during that time. Tracking counters also provides a performance
10146 advantage over just checking the keys, because only one table lookup is
10147 performed for all ACL checks that make use of it.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010148
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020010149 - sc-inc-gpc0(<sc-id>):
10150 The "sc-inc-gpc0" increments the GPC0 counter according to the sticky
10151 counter designated by <sc-id>. If an error occurs, this action silently
10152 fails and the actions evaluation continues.
10153
Frédéric Lécaille6778b272018-01-29 15:22:53 +010010154 - sc-inc-gpc1(<sc-id>):
10155 The "sc-inc-gpc1" increments the GPC1 counter according to the sticky
10156 counter designated by <sc-id>. If an error occurs, this action silently
10157 fails and the actions evaluation continues.
10158
Thierry FOURNIER236657b2015-08-19 08:25:14 +020010159 - sc-set-gpt0(<sc-id>) <int>:
10160 This action sets the GPT0 tag according to the sticky counter designated
10161 by <sc-id> and the value of <int>. The expected result is a boolean. If
10162 an error occurs, this action silently fails and the actions evaluation
10163 continues.
10164
William Lallemand2e785f22016-05-25 01:48:42 +020010165 - set-src <expr> :
10166 Is used to set the source IP address to the value of specified
10167 expression. Useful if you want to mask source IP for privacy.
10168 If you want to provide an IP from a HTTP header use "http-request
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020010169 set-src".
William Lallemand2e785f22016-05-25 01:48:42 +020010170
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020010171 Arguments:
10172 <expr> Is a standard HAProxy expression formed by a sample-fetch
10173 followed by some converters.
William Lallemand2e785f22016-05-25 01:48:42 +020010174
10175 Example:
William Lallemand2e785f22016-05-25 01:48:42 +020010176 tcp-request connection set-src src,ipmask(24)
10177
Willy Tarreau0c630532016-10-21 17:52:58 +020010178 When possible, set-src preserves the original source port as long as the
10179 address family allows it, otherwise the source port is set to 0.
William Lallemand2e785f22016-05-25 01:48:42 +020010180
William Lallemand44be6402016-05-25 01:51:35 +020010181 - set-src-port <expr> :
10182 Is used to set the source port address to the value of specified
10183 expression.
10184
Cyril Bonté6c81d5f2018-10-17 00:14:51 +020010185 Arguments:
10186 <expr> Is a standard HAProxy expression formed by a sample-fetch
10187 followed by some converters.
William Lallemand44be6402016-05-25 01:51:35 +020010188
10189 Example:
William Lallemand44be6402016-05-25 01:51:35 +020010190 tcp-request connection set-src-port int(4000)
10191
Willy Tarreau0c630532016-10-21 17:52:58 +020010192 When possible, set-src-port preserves the original source address as long
10193 as the address family supports a port, otherwise it forces the source
10194 address to IPv4 "0.0.0.0" before rewriting the port.
William Lallemand44be6402016-05-25 01:51:35 +020010195
William Lallemand13e9b0c2016-05-25 02:34:07 +020010196 - set-dst <expr> :
10197 Is used to set the destination IP address to the value of specified
10198 expression. Useful if you want to mask IP for privacy in log.
10199 If you want to provide an IP from a HTTP header use "http-request
10200 set-dst". If you want to connect to the new address/port, use
10201 '0.0.0.0:0' as a server address in the backend.
10202
10203 <expr> Is a standard HAProxy expression formed by a sample-fetch
10204 followed by some converters.
10205
10206 Example:
10207
10208 tcp-request connection set-dst dst,ipmask(24)
10209 tcp-request connection set-dst ipv4(10.0.0.1)
10210
Willy Tarreau0c630532016-10-21 17:52:58 +020010211 When possible, set-dst preserves the original destination port as long as
10212 the address family allows it, otherwise the destination port is set to 0.
10213
William Lallemand13e9b0c2016-05-25 02:34:07 +020010214 - set-dst-port <expr> :
10215 Is used to set the destination port address to the value of specified
10216 expression. If you want to connect to the new address/port, use
10217 '0.0.0.0:0' as a server address in the backend.
10218
10219
10220 <expr> Is a standard HAProxy expression formed by a sample-fetch
10221 followed by some converters.
10222
10223 Example:
10224
10225 tcp-request connection set-dst-port int(4000)
10226
Willy Tarreau0c630532016-10-21 17:52:58 +020010227 When possible, set-dst-port preserves the original destination address as
10228 long as the address family supports a port, otherwise it forces the
10229 destination address to IPv4 "0.0.0.0" before rewriting the port.
10230
Willy Tarreau2d392c22015-08-24 01:43:45 +020010231 - "silent-drop" :
10232 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +010010233 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +020010234 to prevent the client from being notified. The effect it then that the
10235 client still sees an established connection while there's none on
10236 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
10237 except that it doesn't use any local resource at all on the machine
10238 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +010010239 slow down stronger attackers. It is important to understand the impact
10240 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +020010241 client and HAProxy (firewalls, proxies, load balancers) will also keep
10242 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +010010243 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +020010244 TCP_REPAIR socket option is used to block the emission of a TCP
10245 reset. On other systems, the socket's TTL is reduced to 1 so that the
10246 TCP reset doesn't pass the first router, though it's still delivered to
10247 local networks. Do not use it unless you fully understand how it works.
10248
Willy Tarreaue9656522010-08-17 15:40:09 +020010249 Note that the "if/unless" condition is optional. If no condition is set on
10250 the action, it is simply performed unconditionally. That can be useful for
10251 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010252
Willy Tarreaue9656522010-08-17 15:40:09 +020010253 Example: accept all connections from white-listed hosts, reject too fast
10254 connection without counting them, and track accepted connections.
10255 This results in connection rate being capped from abusive sources.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010256
Willy Tarreaue9656522010-08-17 15:40:09 +020010257 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010258 tcp-request connection reject if { src_conn_rate gt 10 }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010259 tcp-request connection track-sc0 src
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010260
Willy Tarreaue9656522010-08-17 15:40:09 +020010261 Example: accept all connections from white-listed hosts, count all other
10262 connections and reject too fast ones. This results in abusive ones
10263 being blocked as long as they don't slow down.
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010264
Willy Tarreaue9656522010-08-17 15:40:09 +020010265 tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst }
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010266 tcp-request connection track-sc0 src
10267 tcp-request connection reject if { sc0_conn_rate gt 10 }
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010268
Willy Tarreau4f0d9192013-06-11 20:40:55 +020010269 Example: enable the PROXY protocol for traffic coming from all known proxies.
10270
10271 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
10272
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010273 See section 7 about ACL usage.
10274
Willy Tarreau4f614292016-10-21 17:49:36 +020010275 See also : "tcp-request session", "tcp-request content", "stick-table"
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010276
10277
Willy Tarreaue9656522010-08-17 15:40:09 +020010278tcp-request content <action> [{if | unless} <condition>]
10279 Perform an action on a new session depending on a layer 4-7 condition
Willy Tarreau62644772008-07-16 18:36:06 +020010280 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +020010281 no | yes | yes | yes
Willy Tarreaue9656522010-08-17 15:40:09 +020010282 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020010283 <action> defines the action to perform if the condition applies. See
10284 below.
Willy Tarreau62644772008-07-16 18:36:06 +020010285
Willy Tarreaue9656522010-08-17 15:40:09 +020010286 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
Willy Tarreau62644772008-07-16 18:36:06 +020010287
Davor Ocelice9ed2812017-12-25 17:49:28 +010010288 A request's contents can be analyzed at an early stage of request processing
Willy Tarreaue9656522010-08-17 15:40:09 +020010289 called "TCP content inspection". During this stage, ACL-based rules are
10290 evaluated every time the request contents are updated, until either an
10291 "accept" or a "reject" rule matches, or the TCP request inspection delay
10292 expires with no matching rule.
Willy Tarreau62644772008-07-16 18:36:06 +020010293
Willy Tarreaue9656522010-08-17 15:40:09 +020010294 The first difference between these rules and "tcp-request connection" rules
10295 is that "tcp-request content" rules can make use of contents to take a
10296 decision. Most often, these decisions will consider a protocol recognition or
10297 validity. The second difference is that content-based rules can be used in
Willy Tarreauf3338342014-01-28 21:40:28 +010010298 both frontends and backends. In case of HTTP keep-alive with the client, all
10299 tcp-request content rules are evaluated again, so haproxy keeps a record of
10300 what sticky counters were assigned by a "tcp-request connection" versus a
10301 "tcp-request content" rule, and flushes all the content-related ones after
10302 processing an HTTP request, so that they may be evaluated again by the rules
10303 being evaluated again for the next request. This is of particular importance
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010304 when the rule tracks some L7 information or when it is conditioned by an
Willy Tarreauf3338342014-01-28 21:40:28 +010010305 L7-based ACL, since tracking may change between requests.
Willy Tarreau62644772008-07-16 18:36:06 +020010306
Willy Tarreaue9656522010-08-17 15:40:09 +020010307 Content-based rules are evaluated in their exact declaration order. If no
10308 rule matches or if there is no rule, the default action is to accept the
10309 contents. There is no specific limit to the number of rules which may be
10310 inserted.
Willy Tarreau62644772008-07-16 18:36:06 +020010311
Thierry FOURNIER236657b2015-08-19 08:25:14 +020010312 Several types of actions are supported :
Willy Tarreau18bf01e2014-06-13 16:18:52 +020010313 - accept : the request is accepted
Baptiste Assmann333939c2019-01-21 08:34:50 +010010314 - do-resolve: perform a DNS resolution
Willy Tarreau18bf01e2014-06-13 16:18:52 +020010315 - reject : the request is rejected and the connection is closed
10316 - capture : the specified sample expression is captured
Patrick Hemmer268a7072018-05-11 12:52:31 -040010317 - set-priority-class <expr> | set-priority-offset <expr>
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010318 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020010319 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010010320 - sc-inc-gpc1(<sc-id>)
Thierry Fournierb9125672016-03-29 19:34:37 +020010321 - sc-set-gpt0(<sc-id>) <int>
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +020010322 - set-dst <expr>
10323 - set-dst-port <expr>
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010324 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +010010325 - unset-var(<var-name>)
Willy Tarreau2d392c22015-08-24 01:43:45 +020010326 - silent-drop
Davor Ocelice9ed2812017-12-25 17:49:28 +010010327 - send-spoe-group <engine-name> <group-name>
Christopher Faulet6bd406e2019-11-22 15:34:17 +010010328 - use-service <service-name>
Willy Tarreau62644772008-07-16 18:36:06 +020010329
Willy Tarreaue9656522010-08-17 15:40:09 +020010330 They have the same meaning as their counter-parts in "tcp-request connection"
10331 so please refer to that section for a complete description.
Baptiste Assmann333939c2019-01-21 08:34:50 +010010332 For "do-resolve" action, please check the "http-request do-resolve"
10333 configuration section.
Willy Tarreau62644772008-07-16 18:36:06 +020010334
Willy Tarreauf3338342014-01-28 21:40:28 +010010335 While there is nothing mandatory about it, it is recommended to use the
10336 track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request
10337 content" rules in the frontend, and track-sc2 for "tcp-request content"
10338 rules in the backend, because that makes the configuration more readable
10339 and easier to troubleshoot, but this is just a guideline and all counters
10340 may be used everywhere.
Willy Tarreau62644772008-07-16 18:36:06 +020010341
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010342 Note that the "if/unless" condition is optional. If no condition is set on
Willy Tarreaue9656522010-08-17 15:40:09 +020010343 the action, it is simply performed unconditionally. That can be useful for
10344 "track-sc*" actions as well as for changing the default action to a reject.
Willy Tarreau62644772008-07-16 18:36:06 +020010345
Willy Tarreaue9656522010-08-17 15:40:09 +020010346 It is perfectly possible to match layer 7 contents with "tcp-request content"
Willy Tarreauc0239e02012-04-16 14:42:55 +020010347 rules, since HTTP-specific ACL matches are able to preliminarily parse the
10348 contents of a buffer before extracting the required data. If the buffered
10349 contents do not parse as a valid HTTP message, then the ACL does not match.
10350 The parser which is involved there is exactly the same as for all other HTTP
Willy Tarreauf3338342014-01-28 21:40:28 +010010351 processing, so there is no risk of parsing something differently. In an HTTP
10352 backend connected to from an HTTP frontend, it is guaranteed that HTTP
10353 contents will always be immediately present when the rule is evaluated first.
Willy Tarreau62644772008-07-16 18:36:06 +020010354
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010355 Tracking layer7 information is also possible provided that the information
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020010356 are present when the rule is processed. The rule processing engine is able to
10357 wait until the inspect delay expires when the data to be tracked is not yet
10358 available.
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010359
Baptiste Assmanne1afd4f2019-04-18 16:21:13 +020010360 The "set-dst" and "set-dst-port" are used to set respectively the destination
10361 IP and port. More information on how to use it at "http-request set-dst".
10362
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010363 The "set-var" is used to set the content of a variable. The variable is
Willy Tarreau4f614292016-10-21 17:49:36 +020010364 declared inline. For "tcp-request session" rules, only session-level
10365 variables can be used, without any layer7 contents.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010366
Daniel Schneller0b547052016-03-21 20:46:57 +010010367 <var-name> The name of the variable starts with an indication about
10368 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010010369 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010010370 "sess" : the variable is shared with the whole session
10371 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010372 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +010010373 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010374 processing
Daniel Schneller0b547052016-03-21 20:46:57 +010010375 "res" : the variable is shared only during response
10376 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010377 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +010010378 The name may only contain characters 'a-z', 'A-Z', '0-9',
10379 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010380
10381 <expr> Is a standard HAProxy expression formed by a sample-fetch
10382 followed by some converters.
10383
Christopher Faulet85d79c92016-11-09 16:54:56 +010010384 The "unset-var" is used to unset a variable. See above for details about
10385 <var-name>.
10386
Patrick Hemmer268a7072018-05-11 12:52:31 -040010387 The "set-priority-class" is used to set the queue priority class of the
10388 current request. The value must be a sample expression which converts to an
10389 integer in the range -2047..2047. Results outside this range will be
10390 truncated. The priority class determines the order in which queued requests
10391 are processed. Lower values have higher priority.
10392
10393 The "set-priority-offset" is used to set the queue priority timestamp offset
10394 of the current request. The value must be a sample expression which converts
10395 to an integer in the range -524287..524287. Results outside this range will be
10396 truncated. When a request is queued, it is ordered first by the priority
10397 class, then by the current timestamp adjusted by the given offset in
10398 milliseconds. Lower values have higher priority.
10399 Note that the resulting timestamp is is only tracked with enough precision for
10400 524,287ms (8m44s287ms). If the request is queued long enough to where the
10401 adjusted timestamp exceeds this value, it will be misidentified as highest
10402 priority. Thus it is important to set "timeout queue" to a value, where when
10403 combined with the offset, does not exceed this limit.
10404
Christopher Faulet76c09ef2017-09-21 11:03:52 +020010405 The "send-spoe-group" is used to trigger sending of a group of SPOE
10406 messages. To do so, the SPOE engine used to send messages must be defined, as
10407 well as the SPOE group to send. Of course, the SPOE engine must refer to an
10408 existing SPOE filter. If not engine name is provided on the SPOE filter line,
10409 the SPOE agent name must be used.
10410
10411 <engine-name> The SPOE engine name.
10412
10413 <group-name> The SPOE group name as specified in the engine configuration.
10414
Christopher Faulet6bd406e2019-11-22 15:34:17 +010010415 The "use-service" is used to executes a TCP service which will reply to the
10416 request and stop the evaluation of the rules. This service may choose to
10417 reply by sending any valid response or it may immediately close the
10418 connection without sending anything. Outside natives services, it is possible
10419 to write your own services in Lua. No further "tcp-request" rules are
10420 evaluated.
10421
10422 Example:
10423 tcp-request content use-service lua.deny { src -f /etc/haproxy/blacklist.lst }
10424
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010425 Example:
10426
10427 tcp-request content set-var(sess.my_var) src
Christopher Faulet85d79c92016-11-09 16:54:56 +010010428 tcp-request content unset-var(sess.my_var2)
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010429
Willy Tarreau62644772008-07-16 18:36:06 +020010430 Example:
Willy Tarreaue9656522010-08-17 15:40:09 +020010431 # Accept HTTP requests containing a Host header saying "example.com"
10432 # and reject everything else.
10433 acl is_host_com hdr(Host) -i example.com
10434 tcp-request inspect-delay 30s
Willy Tarreauc0239e02012-04-16 14:42:55 +020010435 tcp-request content accept if is_host_com
Willy Tarreaue9656522010-08-17 15:40:09 +020010436 tcp-request content reject
10437
10438 Example:
Willy Tarreau62644772008-07-16 18:36:06 +020010439 # reject SMTP connection if client speaks first
10440 tcp-request inspect-delay 30s
10441 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010442 tcp-request content reject if content_present
Willy Tarreau62644772008-07-16 18:36:06 +020010443
10444 # Forward HTTPS connection only if client speaks
10445 tcp-request inspect-delay 30s
10446 acl content_present req_len gt 0
Willy Tarreau68c03ab2010-08-06 15:08:45 +020010447 tcp-request content accept if content_present
Willy Tarreaue9656522010-08-17 15:40:09 +020010448 tcp-request content reject
10449
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010450 Example:
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030010451 # Track the last IP(stick-table type string) from X-Forwarded-For
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010452 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020010453 tcp-request content track-sc0 hdr(x-forwarded-for,-1)
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030010454 # Or track the last IP(stick-table type ip|ipv6) from X-Forwarded-For
10455 tcp-request content track-sc0 req.hdr_ip(x-forwarded-for,-1)
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010456
10457 Example:
10458 # track request counts per "base" (concatenation of Host+URL)
10459 tcp-request inspect-delay 10s
Willy Tarreau4d54c7c2014-09-16 15:48:15 +020010460 tcp-request content track-sc0 base table req-rate
Willy Tarreau5d5b5d82012-12-09 12:00:04 +010010461
Willy Tarreaue9656522010-08-17 15:40:09 +020010462 Example: track per-frontend and per-backend counters, block abusers at the
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030010463 frontend when the backend detects abuse(and marks gpc0).
Willy Tarreaue9656522010-08-17 15:40:09 +020010464
10465 frontend http
Davor Ocelice9ed2812017-12-25 17:49:28 +010010466 # Use General Purpose Counter 0 in SC0 as a global abuse counter
Willy Tarreaue9656522010-08-17 15:40:09 +020010467 # protecting all our sites
10468 stick-table type ip size 1m expire 5m store gpc0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010469 tcp-request connection track-sc0 src
10470 tcp-request connection reject if { sc0_get_gpc0 gt 0 }
Willy Tarreaue9656522010-08-17 15:40:09 +020010471 ...
10472 use_backend http_dynamic if { path_end .php }
10473
10474 backend http_dynamic
10475 # if a source makes too fast requests to this dynamic site (tracked
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010476 # by SC1), block it globally in the frontend.
Willy Tarreaue9656522010-08-17 15:40:09 +020010477 stick-table type ip size 1m expire 5m store http_req_rate(10s)
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010478 acl click_too_fast sc1_http_req_rate gt 10
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030010479 acl mark_as_abuser sc0_inc_gpc0(http) gt 0
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020010480 tcp-request content track-sc1 src
Willy Tarreaue9656522010-08-17 15:40:09 +020010481 tcp-request content reject if click_too_fast mark_as_abuser
Willy Tarreau62644772008-07-16 18:36:06 +020010482
Willy Tarreauc57f0e22009-05-10 13:12:33 +020010483 See section 7 about ACL usage.
Willy Tarreau62644772008-07-16 18:36:06 +020010484
Jarno Huuskonen95b012b2017-04-06 13:59:14 +030010485 See also : "tcp-request connection", "tcp-request session",
10486 "tcp-request inspect-delay", and "http-request".
Willy Tarreau62644772008-07-16 18:36:06 +020010487
10488
10489tcp-request inspect-delay <timeout>
10490 Set the maximum allowed time to wait for data during content inspection
10491 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaufb356202010-08-03 14:02:05 +020010492 no | yes | yes | yes
Willy Tarreau62644772008-07-16 18:36:06 +020010493 Arguments :
10494 <timeout> is the timeout value specified in milliseconds by default, but
10495 can be in any other unit if the number is suffixed by the unit,
10496 as explained at the top of this document.
10497
10498 People using haproxy primarily as a TCP relay are often worried about the
10499 risk of passing any type of protocol to a server without any analysis. In
10500 order to be able to analyze the request contents, we must first withhold
10501 the data then analyze them. This statement simply enables withholding of
10502 data for at most the specified amount of time.
10503
Willy Tarreaufb356202010-08-03 14:02:05 +020010504 TCP content inspection applies very early when a connection reaches a
10505 frontend, then very early when the connection is forwarded to a backend. This
10506 means that a connection may experience a first delay in the frontend and a
10507 second delay in the backend if both have tcp-request rules.
10508
Willy Tarreau62644772008-07-16 18:36:06 +020010509 Note that when performing content inspection, haproxy will evaluate the whole
10510 rules for every new chunk which gets in, taking into account the fact that
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010010511 those data are partial. If no rule matches before the aforementioned delay,
Willy Tarreau62644772008-07-16 18:36:06 +020010512 a last check is performed upon expiration, this time considering that the
Willy Tarreaud869b242009-03-15 14:43:58 +010010513 contents are definitive. If no delay is set, haproxy will not wait at all
10514 and will immediately apply a verdict based on the available information.
10515 Obviously this is unlikely to be very useful and might even be racy, so such
10516 setups are not recommended.
Willy Tarreau62644772008-07-16 18:36:06 +020010517
10518 As soon as a rule matches, the request is released and continues as usual. If
10519 the timeout is reached and no rule matches, the default policy will be to let
10520 it pass through unaffected.
10521
10522 For most protocols, it is enough to set it to a few seconds, as most clients
10523 send the full request immediately upon connection. Add 3 or more seconds to
10524 cover TCP retransmits but that's all. For some protocols, it may make sense
Willy Tarreaud72758d2010-01-12 10:42:19 +010010525 to use large values, for instance to ensure that the client never talks
Davor Ocelice9ed2812017-12-25 17:49:28 +010010526 before the server (e.g. SMTP), or to wait for a client to talk before passing
10527 data to the server (e.g. SSL). Note that the client timeout must cover at
Willy Tarreaub824b002010-09-29 16:36:16 +020010528 least the inspection delay, otherwise it will expire first. If the client
10529 closes the connection or if the buffer is full, the delay immediately expires
10530 since the contents will not be able to change anymore.
Willy Tarreau62644772008-07-16 18:36:06 +020010531
Willy Tarreau55165fe2009-05-10 12:02:55 +020010532 See also : "tcp-request content accept", "tcp-request content reject",
Willy Tarreau62644772008-07-16 18:36:06 +020010533 "timeout client".
10534
10535
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010536tcp-response content <action> [{if | unless} <condition>]
10537 Perform an action on a session response depending on a layer 4-7 condition
10538 May be used in sections : defaults | frontend | listen | backend
10539 no | no | yes | yes
10540 Arguments :
Willy Tarreauc870bfd2015-09-28 18:47:38 +020010541 <action> defines the action to perform if the condition applies. See
10542 below.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010543
10544 <condition> is a standard layer 4-7 ACL-based condition (see section 7).
10545
Davor Ocelice9ed2812017-12-25 17:49:28 +010010546 Response contents can be analyzed at an early stage of response processing
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010547 called "TCP content inspection". During this stage, ACL-based rules are
10548 evaluated every time the response contents are updated, until either an
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020010549 "accept", "close" or a "reject" rule matches, or a TCP response inspection
10550 delay is set and expires with no matching rule.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010551
10552 Most often, these decisions will consider a protocol recognition or validity.
10553
10554 Content-based rules are evaluated in their exact declaration order. If no
10555 rule matches or if there is no rule, the default action is to accept the
10556 contents. There is no specific limit to the number of rules which may be
10557 inserted.
10558
Thierry FOURNIER236657b2015-08-19 08:25:14 +020010559 Several types of actions are supported :
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010560 - accept :
10561 accepts the response if the condition is true (when used with "if")
10562 or false (when used with "unless"). The first such rule executed ends
10563 the rules evaluation.
10564
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020010565 - close :
10566 immediately closes the connection with the server if the condition is
10567 true (when used with "if"), or false (when used with "unless"). The
10568 first such rule executed ends the rules evaluation. The main purpose of
10569 this action is to force a connection to be finished between a client
10570 and a server after an exchange when the application protocol expects
10571 some long time outs to elapse first. The goal is to eliminate idle
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030010572 connections which take significant resources on servers with certain
Willy Tarreaucc1e04b2013-09-11 23:20:29 +020010573 protocols.
10574
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010575 - reject :
10576 rejects the response if the condition is true (when used with "if")
10577 or false (when used with "unless"). The first such rule executed ends
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010578 the rules evaluation. Rejected session are immediately closed.
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010579
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010580 - set-var(<var-name>) <expr>
10581 Sets a variable.
10582
Christopher Faulet85d79c92016-11-09 16:54:56 +010010583 - unset-var(<var-name>)
10584 Unsets a variable.
10585
Thierry FOURNIERe0627bd2015-08-04 08:20:33 +020010586 - sc-inc-gpc0(<sc-id>):
10587 This action increments the GPC0 counter according to the sticky
10588 counter designated by <sc-id>. If an error occurs, this action fails
10589 silently and the actions evaluation continues.
10590
Frédéric Lécaille6778b272018-01-29 15:22:53 +010010591 - sc-inc-gpc1(<sc-id>):
10592 This action increments the GPC1 counter according to the sticky
10593 counter designated by <sc-id>. If an error occurs, this action fails
10594 silently and the actions evaluation continues.
10595
Thierry FOURNIER236657b2015-08-19 08:25:14 +020010596 - sc-set-gpt0(<sc-id>) <int> :
10597 This action sets the GPT0 tag according to the sticky counter designated
10598 by <sc-id> and the value of <int>. The expected result is a boolean. If
10599 an error occurs, this action silently fails and the actions evaluation
10600 continues.
10601
Willy Tarreau2d392c22015-08-24 01:43:45 +020010602 - "silent-drop" :
10603 This stops the evaluation of the rules and makes the client-facing
Davor Ocelice9ed2812017-12-25 17:49:28 +010010604 connection suddenly disappear using a system-dependent way that tries
Willy Tarreau2d392c22015-08-24 01:43:45 +020010605 to prevent the client from being notified. The effect it then that the
10606 client still sees an established connection while there's none on
10607 HAProxy. The purpose is to achieve a comparable effect to "tarpit"
10608 except that it doesn't use any local resource at all on the machine
10609 running HAProxy. It can resist much higher loads than "tarpit", and
Davor Ocelice9ed2812017-12-25 17:49:28 +010010610 slow down stronger attackers. It is important to understand the impact
10611 of using this mechanism. All stateful equipment placed between the
Willy Tarreau2d392c22015-08-24 01:43:45 +020010612 client and HAProxy (firewalls, proxies, load balancers) will also keep
10613 the established connection for a long time and may suffer from this
Davor Ocelice9ed2812017-12-25 17:49:28 +010010614 action. On modern Linux systems running with enough privileges, the
Willy Tarreau2d392c22015-08-24 01:43:45 +020010615 TCP_REPAIR socket option is used to block the emission of a TCP
10616 reset. On other systems, the socket's TTL is reduced to 1 so that the
10617 TCP reset doesn't pass the first router, though it's still delivered to
10618 local networks. Do not use it unless you fully understand how it works.
10619
Christopher Faulet76c09ef2017-09-21 11:03:52 +020010620 - send-spoe-group <engine-name> <group-name>
10621 Send a group of SPOE messages.
10622
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010623 Note that the "if/unless" condition is optional. If no condition is set on
10624 the action, it is simply performed unconditionally. That can be useful for
10625 for changing the default action to a reject.
10626
Jamie Gloudonaaa21002012-08-25 00:18:33 -040010627 It is perfectly possible to match layer 7 contents with "tcp-response
10628 content" rules, but then it is important to ensure that a full response has
10629 been buffered, otherwise no contents will match. In order to achieve this,
10630 the best solution involves detecting the HTTP protocol during the inspection
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010631 period.
10632
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010633 The "set-var" is used to set the content of a variable. The variable is
10634 declared inline.
10635
Daniel Schneller0b547052016-03-21 20:46:57 +010010636 <var-name> The name of the variable starts with an indication about
10637 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010010638 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010010639 "sess" : the variable is shared with the whole session
10640 "txn" : the variable is shared with the transaction
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010641 (request and response)
Daniel Schneller0b547052016-03-21 20:46:57 +010010642 "req" : the variable is shared only during request
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010643 processing
Daniel Schneller0b547052016-03-21 20:46:57 +010010644 "res" : the variable is shared only during response
10645 processing
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010646 This prefix is followed by a name. The separator is a '.'.
Christopher Fauletb71557a2016-10-31 10:49:03 +010010647 The name may only contain characters 'a-z', 'A-Z', '0-9',
10648 '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020010649
10650 <expr> Is a standard HAProxy expression formed by a sample-fetch
10651 followed by some converters.
10652
10653 Example:
10654
10655 tcp-request content set-var(sess.my_var) src
10656
Christopher Faulet85d79c92016-11-09 16:54:56 +010010657 The "unset-var" is used to unset a variable. See above for details about
10658 <var-name>.
10659
10660 Example:
10661
10662 tcp-request content unset-var(sess.my_var)
10663
Christopher Faulet76c09ef2017-09-21 11:03:52 +020010664 The "send-spoe-group" is used to trigger sending of a group of SPOE
10665 messages. To do so, the SPOE engine used to send messages must be defined, as
10666 well as the SPOE group to send. Of course, the SPOE engine must refer to an
10667 existing SPOE filter. If not engine name is provided on the SPOE filter line,
10668 the SPOE agent name must be used.
10669
10670 <engine-name> The SPOE engine name.
10671
10672 <group-name> The SPOE group name as specified in the engine configuration.
10673
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010674 See section 7 about ACL usage.
10675
10676 See also : "tcp-request content", "tcp-response inspect-delay"
10677
10678
Willy Tarreau4f614292016-10-21 17:49:36 +020010679tcp-request session <action> [{if | unless} <condition>]
10680 Perform an action on a validated session depending on a layer 5 condition
10681 May be used in sections : defaults | frontend | listen | backend
10682 no | yes | yes | no
10683 Arguments :
10684 <action> defines the action to perform if the condition applies. See
10685 below.
10686
10687 <condition> is a standard layer5-only ACL-based condition (see section 7).
10688
Davor Ocelice9ed2812017-12-25 17:49:28 +010010689 Once a session is validated, (i.e. after all handshakes have been completed),
Willy Tarreau4f614292016-10-21 17:49:36 +020010690 it is possible to evaluate some conditions to decide whether this session
10691 must be accepted or dropped or have its counters tracked. Those conditions
10692 cannot make use of any data contents because no buffers are allocated yet and
10693 the processing cannot wait at this stage. The main use case it to copy some
10694 early information into variables (since variables are accessible in the
10695 session), or to keep track of some information collected after the handshake,
10696 such as SSL-level elements (SNI, ciphers, client cert's CN) or information
Davor Ocelice9ed2812017-12-25 17:49:28 +010010697 from the PROXY protocol header (e.g. track a source forwarded this way). The
Willy Tarreau4f614292016-10-21 17:49:36 +020010698 extracted information can thus be copied to a variable or tracked using
10699 "track-sc" rules. Of course it is also possible to decide to accept/reject as
10700 with other rulesets. Most operations performed here could also be performed
10701 in "tcp-request content" rules, except that in HTTP these rules are evaluated
10702 for each new request, and that might not always be acceptable. For example a
10703 rule might increment a counter on each evaluation. It would also be possible
10704 that a country is resolved by geolocation from the source IP address,
10705 assigned to a session-wide variable, then the source address rewritten from
10706 an HTTP header for all requests. If some contents need to be inspected in
10707 order to take the decision, the "tcp-request content" statements must be used
10708 instead.
10709
10710 The "tcp-request session" rules are evaluated in their exact declaration
10711 order. If no rule matches or if there is no rule, the default action is to
10712 accept the incoming session. There is no specific limit to the number of
10713 rules which may be inserted.
10714
10715 Several types of actions are supported :
10716 - accept : the request is accepted
10717 - reject : the request is rejected and the connection is closed
10718 - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
10719 - sc-inc-gpc0(<sc-id>)
Frédéric Lécaille6778b272018-01-29 15:22:53 +010010720 - sc-inc-gpc1(<sc-id>)
Willy Tarreau4f614292016-10-21 17:49:36 +020010721 - sc-set-gpt0(<sc-id>) <int>
10722 - set-var(<var-name>) <expr>
Christopher Faulet85d79c92016-11-09 16:54:56 +010010723 - unset-var(<var-name>)
Willy Tarreau4f614292016-10-21 17:49:36 +020010724 - silent-drop
10725
10726 These actions have the same meaning as their respective counter-parts in
10727 "tcp-request connection" and "tcp-request content", so please refer to these
10728 sections for a complete description.
10729
10730 Note that the "if/unless" condition is optional. If no condition is set on
10731 the action, it is simply performed unconditionally. That can be useful for
10732 "track-sc*" actions as well as for changing the default action to a reject.
10733
10734 Example: track the original source address by default, or the one advertised
10735 in the PROXY protocol header for connection coming from the local
10736 proxies. The first connection-level rule enables receipt of the
10737 PROXY protocol for these ones, the second rule tracks whatever
10738 address we decide to keep after optional decoding.
10739
10740 tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
10741 tcp-request session track-sc0 src
10742
10743 Example: accept all sessions from white-listed hosts, reject too fast
10744 sessions without counting them, and track accepted sessions.
10745 This results in session rate being capped from abusive sources.
10746
10747 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
10748 tcp-request session reject if { src_sess_rate gt 10 }
10749 tcp-request session track-sc0 src
10750
10751 Example: accept all sessions from white-listed hosts, count all other
10752 sessions and reject too fast ones. This results in abusive ones
10753 being blocked as long as they don't slow down.
10754
10755 tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
10756 tcp-request session track-sc0 src
10757 tcp-request session reject if { sc0_sess_rate gt 10 }
10758
10759 See section 7 about ACL usage.
10760
10761 See also : "tcp-request connection", "tcp-request content", "stick-table"
10762
10763
Emeric Brun0a3b67f2010-09-24 15:34:53 +020010764tcp-response inspect-delay <timeout>
10765 Set the maximum allowed time to wait for a response during content inspection
10766 May be used in sections : defaults | frontend | listen | backend
10767 no | no | yes | yes
10768 Arguments :
10769 <timeout> is the timeout value specified in milliseconds by default, but
10770 can be in any other unit if the number is suffixed by the unit,
10771 as explained at the top of this document.
10772
10773 See also : "tcp-response content", "tcp-request inspect-delay".
10774
10775
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010776timeout check <timeout>
10777 Set additional check timeout, but only after a connection has been already
10778 established.
10779
10780 May be used in sections: defaults | frontend | listen | backend
10781 yes | no | yes | yes
10782 Arguments:
10783 <timeout> is the timeout value specified in milliseconds by default, but
10784 can be in any other unit if the number is suffixed by the unit,
10785 as explained at the top of this document.
10786
10787 If set, haproxy uses min("timeout connect", "inter") as a connect timeout
10788 for check and "timeout check" as an additional read timeout. The "min" is
Davor Ocelice9ed2812017-12-25 17:49:28 +010010789 used so that people running with *very* long "timeout connect" (e.g. those
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010790 who needed this due to the queue or tarpit) do not slow down their checks.
Willy Tarreaud7550a22010-02-10 05:10:19 +010010791 (Please also note that there is no valid reason to have such long connect
10792 timeouts, because "timeout queue" and "timeout tarpit" can always be used to
10793 avoid that).
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010794
10795 If "timeout check" is not set haproxy uses "inter" for complete check
10796 timeout (connect + read) exactly like all <1.3.15 version.
10797
10798 In most cases check request is much simpler and faster to handle than normal
10799 requests and people may want to kick out laggy servers so this timeout should
Willy Tarreau41a340d2008-01-22 12:25:31 +010010800 be smaller than "timeout server".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010801
10802 This parameter is specific to backends, but can be specified once for all in
10803 "defaults" sections. This is in fact one of the easiest solutions not to
10804 forget about it.
10805
Willy Tarreau41a340d2008-01-22 12:25:31 +010010806 See also: "timeout connect", "timeout queue", "timeout server",
10807 "timeout tarpit".
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010808
10809
Willy Tarreau0ba27502007-12-24 16:55:16 +010010810timeout client <timeout>
10811timeout clitimeout <timeout> (deprecated)
10812 Set the maximum inactivity time on the client side.
10813 May be used in sections : defaults | frontend | listen | backend
10814 yes | yes | yes | no
10815 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010816 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010010817 can be in any other unit if the number is suffixed by the unit,
10818 as explained at the top of this document.
10819
10820 The inactivity timeout applies when the client is expected to acknowledge or
10821 send data. In HTTP mode, this timeout is particularly important to consider
10822 during the first phase, when the client sends the request, and during the
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010010823 response while it is reading data sent by the server. That said, for the
10824 first phase, it is preferable to set the "timeout http-request" to better
10825 protect HAProxy from Slowloris like attacks. The value is specified in
10826 milliseconds by default, but can be in any other unit if the number is
Willy Tarreau0ba27502007-12-24 16:55:16 +010010827 suffixed by the unit, as specified at the top of this document. In TCP mode
10828 (and to a lesser extent, in HTTP mode), it is highly recommended that the
10829 client timeout remains equal to the server timeout in order to avoid complex
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010830 situations to debug. It is a good practice to cover one or several TCP packet
Willy Tarreau0ba27502007-12-24 16:55:16 +010010831 losses by specifying timeouts that are slightly above multiples of 3 seconds
Davor Ocelice9ed2812017-12-25 17:49:28 +010010832 (e.g. 4 or 5 seconds). If some long-lived sessions are mixed with short-lived
10833 sessions (e.g. WebSocket and HTTP), it's worth considering "timeout tunnel",
Willy Tarreau05cdd962014-05-10 14:30:07 +020010834 which overrides "timeout client" and "timeout server" for tunnels, as well as
10835 "timeout client-fin" for half-closed connections.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010836
10837 This parameter is specific to frontends, but can be specified once for all in
10838 "defaults" sections. This is in fact one of the easiest solutions not to
10839 forget about it. An unspecified timeout results in an infinite timeout, which
10840 is not recommended. Such a usage is accepted and works but reports a warning
John Roesler27c754c2019-07-10 15:45:51 -050010841 during startup because it may result in accumulation of expired sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010010842 the system if the system's timeouts are not configured either.
10843
Willy Tarreau95c4e142017-11-26 12:18:55 +010010844 This also applies to HTTP/2 connections, which will be closed with GOAWAY.
Lukas Tribus75df9d72017-11-24 19:05:12 +010010845
Willy Tarreau0ba27502007-12-24 16:55:16 +010010846 This parameter replaces the old, deprecated "clitimeout". It is recommended
10847 to use it to write new configurations. The form "timeout clitimeout" is
10848 provided only by backwards compatibility but its use is strongly discouraged.
10849
Baptiste Assmann2e1941e2016-03-06 23:24:12 +010010850 See also : "clitimeout", "timeout server", "timeout tunnel",
10851 "timeout http-request".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010852
10853
Willy Tarreau05cdd962014-05-10 14:30:07 +020010854timeout client-fin <timeout>
10855 Set the inactivity timeout on the client side for half-closed connections.
10856 May be used in sections : defaults | frontend | listen | backend
10857 yes | yes | yes | no
10858 Arguments :
10859 <timeout> is the timeout value specified in milliseconds by default, but
10860 can be in any other unit if the number is suffixed by the unit,
10861 as explained at the top of this document.
10862
10863 The inactivity timeout applies when the client is expected to acknowledge or
10864 send data while one direction is already shut down. This timeout is different
10865 from "timeout client" in that it only applies to connections which are closed
10866 in one direction. This is particularly useful to avoid keeping connections in
10867 FIN_WAIT state for too long when clients do not disconnect cleanly. This
10868 problem is particularly common long connections such as RDP or WebSocket.
10869 Note that this timeout can override "timeout tunnel" when a connection shuts
Willy Tarreau599391a2017-11-24 10:16:00 +010010870 down in one direction. It is applied to idle HTTP/2 connections once a GOAWAY
10871 frame was sent, often indicating an expectation that the connection quickly
10872 ends.
Willy Tarreau05cdd962014-05-10 14:30:07 +020010873
10874 This parameter is specific to frontends, but can be specified once for all in
10875 "defaults" sections. By default it is not set, so half-closed connections
10876 will use the other timeouts (timeout.client or timeout.tunnel).
10877
10878 See also : "timeout client", "timeout server-fin", and "timeout tunnel".
10879
10880
Willy Tarreau0ba27502007-12-24 16:55:16 +010010881timeout connect <timeout>
10882timeout contimeout <timeout> (deprecated)
10883 Set the maximum time to wait for a connection attempt to a server to succeed.
10884 May be used in sections : defaults | frontend | listen | backend
10885 yes | no | yes | yes
10886 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010887 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau0ba27502007-12-24 16:55:16 +010010888 can be in any other unit if the number is suffixed by the unit,
10889 as explained at the top of this document.
10890
10891 If the server is located on the same LAN as haproxy, the connection should be
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010010892 immediate (less than a few milliseconds). Anyway, it is a good practice to
Willy Tarreaud72758d2010-01-12 10:42:19 +010010893 cover one or several TCP packet losses by specifying timeouts that are
Davor Ocelice9ed2812017-12-25 17:49:28 +010010894 slightly above multiples of 3 seconds (e.g. 4 or 5 seconds). By default, the
Krzysztof Piotr Oledzki5259dfe2008-01-21 01:54:06 +010010895 connect timeout also presets both queue and tarpit timeouts to the same value
10896 if these have not been specified.
Willy Tarreau0ba27502007-12-24 16:55:16 +010010897
10898 This parameter is specific to backends, but can be specified once for all in
10899 "defaults" sections. This is in fact one of the easiest solutions not to
10900 forget about it. An unspecified timeout results in an infinite timeout, which
10901 is not recommended. Such a usage is accepted and works but reports a warning
John Roesler27c754c2019-07-10 15:45:51 -050010902 during startup because it may result in accumulation of failed sessions in
Willy Tarreau0ba27502007-12-24 16:55:16 +010010903 the system if the system's timeouts are not configured either.
10904
10905 This parameter replaces the old, deprecated "contimeout". It is recommended
10906 to use it to write new configurations. The form "timeout contimeout" is
10907 provided only by backwards compatibility but its use is strongly discouraged.
10908
Willy Tarreau41a340d2008-01-22 12:25:31 +010010909 See also: "timeout check", "timeout queue", "timeout server", "contimeout",
10910 "timeout tarpit".
Willy Tarreau0ba27502007-12-24 16:55:16 +010010911
10912
Willy Tarreaub16a5742010-01-10 14:46:16 +010010913timeout http-keep-alive <timeout>
10914 Set the maximum allowed time to wait for a new HTTP request to appear
10915 May be used in sections : defaults | frontend | listen | backend
10916 yes | yes | yes | yes
10917 Arguments :
10918 <timeout> is the timeout value specified in milliseconds by default, but
10919 can be in any other unit if the number is suffixed by the unit,
10920 as explained at the top of this document.
10921
10922 By default, the time to wait for a new request in case of keep-alive is set
10923 by "timeout http-request". However this is not always convenient because some
10924 people want very short keep-alive timeouts in order to release connections
10925 faster, and others prefer to have larger ones but still have short timeouts
10926 once the request has started to present itself.
10927
10928 The "http-keep-alive" timeout covers these needs. It will define how long to
10929 wait for a new HTTP request to start coming after a response was sent. Once
10930 the first byte of request has been seen, the "http-request" timeout is used
10931 to wait for the complete request to come. Note that empty lines prior to a
10932 new request do not refresh the timeout and are not counted as a new request.
10933
10934 There is also another difference between the two timeouts : when a connection
10935 expires during timeout http-keep-alive, no error is returned, the connection
10936 just closes. If the connection expires in "http-request" while waiting for a
10937 connection to complete, a HTTP 408 error is returned.
10938
10939 In general it is optimal to set this value to a few tens to hundreds of
10940 milliseconds, to allow users to fetch all objects of a page at once but
Davor Ocelice9ed2812017-12-25 17:49:28 +010010941 without waiting for further clicks. Also, if set to a very small value (e.g.
Willy Tarreaub16a5742010-01-10 14:46:16 +010010942 1 millisecond) it will probably only accept pipelined requests but not the
10943 non-pipelined ones. It may be a nice trade-off for very large sites running
Patrick Mézard2382ad62010-05-09 10:43:32 +020010944 with tens to hundreds of thousands of clients.
Willy Tarreaub16a5742010-01-10 14:46:16 +010010945
10946 If this parameter is not set, the "http-request" timeout applies, and if both
10947 are not set, "timeout client" still applies at the lower level. It should be
10948 set in the frontend to take effect, unless the frontend is in TCP mode, in
10949 which case the HTTP backend's timeout will be used.
10950
Willy Tarreau95c4e142017-11-26 12:18:55 +010010951 When using HTTP/2 "timeout client" is applied instead. This is so we can keep
10952 using short keep-alive timeouts in HTTP/1.1 while using longer ones in HTTP/2
Lukas Tribus75df9d72017-11-24 19:05:12 +010010953 (where we only have one connection per client and a connection setup).
10954
Willy Tarreaub16a5742010-01-10 14:46:16 +010010955 See also : "timeout http-request", "timeout client".
10956
10957
Willy Tarreau036fae02008-01-06 13:24:40 +010010958timeout http-request <timeout>
10959 Set the maximum allowed time to wait for a complete HTTP request
10960 May be used in sections : defaults | frontend | listen | backend
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010961 yes | yes | yes | yes
Willy Tarreau036fae02008-01-06 13:24:40 +010010962 Arguments :
Willy Tarreau844e3c52008-01-11 16:28:18 +010010963 <timeout> is the timeout value specified in milliseconds by default, but
Willy Tarreau036fae02008-01-06 13:24:40 +010010964 can be in any other unit if the number is suffixed by the unit,
10965 as explained at the top of this document.
10966
10967 In order to offer DoS protection, it may be required to lower the maximum
10968 accepted time to receive a complete HTTP request without affecting the client
10969 timeout. This helps protecting against established connections on which
10970 nothing is sent. The client timeout cannot offer a good protection against
10971 this abuse because it is an inactivity timeout, which means that if the
10972 attacker sends one character every now and then, the timeout will not
10973 trigger. With the HTTP request timeout, no matter what speed the client
Willy Tarreau2705a612014-05-23 17:38:34 +020010974 types, the request will be aborted if it does not complete in time. When the
10975 timeout expires, an HTTP 408 response is sent to the client to inform it
10976 about the problem, and the connection is closed. The logs will report
10977 termination codes "cR". Some recent browsers are having problems with this
Davor Ocelice9ed2812017-12-25 17:49:28 +010010978 standard, well-documented behavior, so it might be needed to hide the 408
Willy Tarreau0f228a02015-05-01 15:37:53 +020010979 code using "option http-ignore-probes" or "errorfile 408 /dev/null". See
10980 more details in the explanations of the "cR" termination code in section 8.5.
Willy Tarreau036fae02008-01-06 13:24:40 +010010981
Baptiste Assmanneccdf432015-10-28 13:49:01 +010010982 By default, this timeout only applies to the header part of the request,
10983 and not to any data. As soon as the empty line is received, this timeout is
10984 not used anymore. When combined with "option http-buffer-request", this
10985 timeout also applies to the body of the request..
10986 It is used again on keep-alive connections to wait for a second
Willy Tarreaub16a5742010-01-10 14:46:16 +010010987 request if "timeout http-keep-alive" is not set.
Willy Tarreau036fae02008-01-06 13:24:40 +010010988
10989 Generally it is enough to set it to a few seconds, as most clients send the
10990 full request immediately upon connection. Add 3 or more seconds to cover TCP
Davor Ocelice9ed2812017-12-25 17:49:28 +010010991 retransmits but that's all. Setting it to very low values (e.g. 50 ms) will
Willy Tarreau036fae02008-01-06 13:24:40 +010010992 generally work on local networks as long as there are no packet losses. This
10993 will prevent people from sending bare HTTP requests using telnet.
10994
10995 If this parameter is not set, the client timeout still applies between each
Willy Tarreaucd7afc02009-07-12 10:03:17 +020010996 chunk of the incoming request. It should be set in the frontend to take
10997 effect, unless the frontend is in TCP mode, in which case the HTTP backend's
10998 timeout will be used.
Willy Tarreau036fae02008-01-06 13:24:40 +010010999
Willy Tarreau0f228a02015-05-01 15:37:53 +020011000 See also : "errorfile", "http-ignore-probes", "timeout http-keep-alive", and
Baptiste Assmanneccdf432015-10-28 13:49:01 +010011001 "timeout client", "option http-buffer-request".
Willy Tarreau036fae02008-01-06 13:24:40 +010011002
Willy Tarreau844e3c52008-01-11 16:28:18 +010011003
11004timeout queue <timeout>
11005 Set the maximum time to wait in the queue for a connection slot to be free
11006 May be used in sections : defaults | frontend | listen | backend
11007 yes | no | yes | yes
11008 Arguments :
11009 <timeout> is the timeout value specified in milliseconds by default, but
11010 can be in any other unit if the number is suffixed by the unit,
11011 as explained at the top of this document.
11012
11013 When a server's maxconn is reached, connections are left pending in a queue
11014 which may be server-specific or global to the backend. In order not to wait
11015 indefinitely, a timeout is applied to requests pending in the queue. If the
11016 timeout is reached, it is considered that the request will almost never be
11017 served, so it is dropped and a 503 error is returned to the client.
11018
11019 The "timeout queue" statement allows to fix the maximum time for a request to
11020 be left pending in a queue. If unspecified, the same value as the backend's
11021 connection timeout ("timeout connect") is used, for backwards compatibility
11022 with older versions with no "timeout queue" parameter.
11023
11024 See also : "timeout connect", "contimeout".
11025
11026
11027timeout server <timeout>
11028timeout srvtimeout <timeout> (deprecated)
11029 Set the maximum inactivity time on the server side.
11030 May be used in sections : defaults | frontend | listen | backend
11031 yes | no | yes | yes
11032 Arguments :
11033 <timeout> is the timeout value specified in milliseconds by default, but
11034 can be in any other unit if the number is suffixed by the unit,
11035 as explained at the top of this document.
11036
11037 The inactivity timeout applies when the server is expected to acknowledge or
11038 send data. In HTTP mode, this timeout is particularly important to consider
11039 during the first phase of the server's response, when it has to send the
11040 headers, as it directly represents the server's processing time for the
11041 request. To find out what value to put there, it's often good to start with
11042 what would be considered as unacceptable response times, then check the logs
11043 to observe the response time distribution, and adjust the value accordingly.
11044
11045 The value is specified in milliseconds by default, but can be in any other
11046 unit if the number is suffixed by the unit, as specified at the top of this
11047 document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly
11048 recommended that the client timeout remains equal to the server timeout in
11049 order to avoid complex situations to debug. Whatever the expected server
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010011050 response times, it is a good practice to cover at least one or several TCP
Willy Tarreau844e3c52008-01-11 16:28:18 +010011051 packet losses by specifying timeouts that are slightly above multiples of 3
Davor Ocelice9ed2812017-12-25 17:49:28 +010011052 seconds (e.g. 4 or 5 seconds minimum). If some long-lived sessions are mixed
11053 with short-lived sessions (e.g. WebSocket and HTTP), it's worth considering
Willy Tarreauce887fd2012-05-12 12:50:00 +020011054 "timeout tunnel", which overrides "timeout client" and "timeout server" for
11055 tunnels.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011056
11057 This parameter is specific to backends, but can be specified once for all in
11058 "defaults" sections. This is in fact one of the easiest solutions not to
11059 forget about it. An unspecified timeout results in an infinite timeout, which
11060 is not recommended. Such a usage is accepted and works but reports a warning
John Roesler27c754c2019-07-10 15:45:51 -050011061 during startup because it may result in accumulation of expired sessions in
Willy Tarreau844e3c52008-01-11 16:28:18 +010011062 the system if the system's timeouts are not configured either.
11063
11064 This parameter replaces the old, deprecated "srvtimeout". It is recommended
11065 to use it to write new configurations. The form "timeout srvtimeout" is
11066 provided only by backwards compatibility but its use is strongly discouraged.
11067
Willy Tarreauce887fd2012-05-12 12:50:00 +020011068 See also : "srvtimeout", "timeout client" and "timeout tunnel".
Willy Tarreau844e3c52008-01-11 16:28:18 +010011069
Willy Tarreau05cdd962014-05-10 14:30:07 +020011070
11071timeout server-fin <timeout>
11072 Set the inactivity timeout on the server side for half-closed connections.
11073 May be used in sections : defaults | frontend | listen | backend
11074 yes | no | yes | yes
11075 Arguments :
11076 <timeout> is the timeout value specified in milliseconds by default, but
11077 can be in any other unit if the number is suffixed by the unit,
11078 as explained at the top of this document.
11079
11080 The inactivity timeout applies when the server is expected to acknowledge or
11081 send data while one direction is already shut down. This timeout is different
11082 from "timeout server" in that it only applies to connections which are closed
11083 in one direction. This is particularly useful to avoid keeping connections in
11084 FIN_WAIT state for too long when a remote server does not disconnect cleanly.
11085 This problem is particularly common long connections such as RDP or WebSocket.
11086 Note that this timeout can override "timeout tunnel" when a connection shuts
11087 down in one direction. This setting was provided for completeness, but in most
11088 situations, it should not be needed.
11089
11090 This parameter is specific to backends, but can be specified once for all in
11091 "defaults" sections. By default it is not set, so half-closed connections
11092 will use the other timeouts (timeout.server or timeout.tunnel).
11093
11094 See also : "timeout client-fin", "timeout server", and "timeout tunnel".
11095
Willy Tarreau844e3c52008-01-11 16:28:18 +010011096
11097timeout tarpit <timeout>
Cyril Bonté78caf842010-03-10 22:41:43 +010011098 Set the duration for which tarpitted connections will be maintained
Willy Tarreau844e3c52008-01-11 16:28:18 +010011099 May be used in sections : defaults | frontend | listen | backend
11100 yes | yes | yes | yes
11101 Arguments :
11102 <timeout> is the tarpit duration specified in milliseconds by default, but
11103 can be in any other unit if the number is suffixed by the unit,
11104 as explained at the top of this document.
11105
Jarno Huuskonene5ae7022017-04-03 14:36:21 +030011106 When a connection is tarpitted using "http-request tarpit" or
11107 "reqtarpit", it is maintained open with no activity for a certain
11108 amount of time, then closed. "timeout tarpit" defines how long it will
11109 be maintained open.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011110
11111 The value is specified in milliseconds by default, but can be in any other
11112 unit if the number is suffixed by the unit, as specified at the top of this
11113 document. If unspecified, the same value as the backend's connection timeout
11114 ("timeout connect") is used, for backwards compatibility with older versions
Cyril Bonté78caf842010-03-10 22:41:43 +010011115 with no "timeout tarpit" parameter.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011116
11117 See also : "timeout connect", "contimeout".
11118
11119
Willy Tarreauce887fd2012-05-12 12:50:00 +020011120timeout tunnel <timeout>
11121 Set the maximum inactivity time on the client and server side for tunnels.
11122 May be used in sections : defaults | frontend | listen | backend
11123 yes | no | yes | yes
11124 Arguments :
11125 <timeout> is the timeout value specified in milliseconds by default, but
11126 can be in any other unit if the number is suffixed by the unit,
11127 as explained at the top of this document.
11128
Jamie Gloudonaaa21002012-08-25 00:18:33 -040011129 The tunnel timeout applies when a bidirectional connection is established
Willy Tarreauce887fd2012-05-12 12:50:00 +020011130 between a client and a server, and the connection remains inactive in both
11131 directions. This timeout supersedes both the client and server timeouts once
11132 the connection becomes a tunnel. In TCP, this timeout is used as soon as no
Davor Ocelice9ed2812017-12-25 17:49:28 +010011133 analyzer remains attached to either connection (e.g. tcp content rules are
11134 accepted). In HTTP, this timeout is used when a connection is upgraded (e.g.
Willy Tarreauce887fd2012-05-12 12:50:00 +020011135 when switching to the WebSocket protocol, or forwarding a CONNECT request
11136 to a proxy), or after the first response when no keepalive/close option is
11137 specified.
11138
Willy Tarreau05cdd962014-05-10 14:30:07 +020011139 Since this timeout is usually used in conjunction with long-lived connections,
11140 it usually is a good idea to also set "timeout client-fin" to handle the
11141 situation where a client suddenly disappears from the net and does not
11142 acknowledge a close, or sends a shutdown and does not acknowledge pending
11143 data anymore. This can happen in lossy networks where firewalls are present,
11144 and is detected by the presence of large amounts of sessions in a FIN_WAIT
11145 state.
11146
Willy Tarreauce887fd2012-05-12 12:50:00 +020011147 The value is specified in milliseconds by default, but can be in any other
11148 unit if the number is suffixed by the unit, as specified at the top of this
11149 document. Whatever the expected normal idle time, it is a good practice to
11150 cover at least one or several TCP packet losses by specifying timeouts that
Davor Ocelice9ed2812017-12-25 17:49:28 +010011151 are slightly above multiples of 3 seconds (e.g. 4 or 5 seconds minimum).
Willy Tarreauce887fd2012-05-12 12:50:00 +020011152
11153 This parameter is specific to backends, but can be specified once for all in
11154 "defaults" sections. This is in fact one of the easiest solutions not to
11155 forget about it.
11156
11157 Example :
11158 defaults http
11159 option http-server-close
11160 timeout connect 5s
11161 timeout client 30s
Willy Tarreau05cdd962014-05-10 14:30:07 +020011162 timeout client-fin 30s
Willy Tarreauce887fd2012-05-12 12:50:00 +020011163 timeout server 30s
11164 timeout tunnel 1h # timeout to use with WebSocket and CONNECT
11165
Willy Tarreau05cdd962014-05-10 14:30:07 +020011166 See also : "timeout client", "timeout client-fin", "timeout server".
Willy Tarreauce887fd2012-05-12 12:50:00 +020011167
11168
Willy Tarreau844e3c52008-01-11 16:28:18 +010011169transparent (deprecated)
11170 Enable client-side transparent proxying
11171 May be used in sections : defaults | frontend | listen | backend
Willy Tarreau4b1f8592008-12-23 23:13:55 +010011172 yes | no | yes | yes
Willy Tarreau844e3c52008-01-11 16:28:18 +010011173 Arguments : none
11174
11175 This keyword was introduced in order to provide layer 7 persistence to layer
11176 3 load balancers. The idea is to use the OS's ability to redirect an incoming
11177 connection for a remote address to a local process (here HAProxy), and let
11178 this process know what address was initially requested. When this option is
11179 used, sessions without cookies will be forwarded to the original destination
11180 IP address of the incoming request (which should match that of another
11181 equipment), while requests with cookies will still be forwarded to the
11182 appropriate server.
11183
11184 The "transparent" keyword is deprecated, use "option transparent" instead.
11185
11186 Note that contrary to a common belief, this option does NOT make HAProxy
11187 present the client's IP to the server when establishing the connection.
11188
Willy Tarreau844e3c52008-01-11 16:28:18 +010011189 See also: "option transparent"
11190
William Lallemanda73203e2012-03-12 12:48:57 +010011191unique-id-format <string>
11192 Generate a unique ID for each request.
11193 May be used in sections : defaults | frontend | listen | backend
11194 yes | yes | yes | no
11195 Arguments :
11196 <string> is a log-format string.
11197
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011198 This keyword creates a ID for each request using the custom log format. A
11199 unique ID is useful to trace a request passing through many components of
11200 a complex infrastructure. The newly created ID may also be logged using the
11201 %ID tag the log-format string.
William Lallemanda73203e2012-03-12 12:48:57 +010011202
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011203 The format should be composed from elements that are guaranteed to be
11204 unique when combined together. For instance, if multiple haproxy instances
11205 are involved, it might be important to include the node name. It is often
11206 needed to log the incoming connection's source and destination addresses
11207 and ports. Note that since multiple requests may be performed over the same
11208 connection, including a request counter may help differentiate them.
11209 Similarly, a timestamp may protect against a rollover of the counter.
11210 Logging the process ID will avoid collisions after a service restart.
William Lallemanda73203e2012-03-12 12:48:57 +010011211
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011212 It is recommended to use hexadecimal notation for many fields since it
11213 makes them more compact and saves space in logs.
William Lallemanda73203e2012-03-12 12:48:57 +010011214
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011215 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010011216
Julien Vehentf21be322014-03-07 08:27:34 -050011217 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010011218
11219 will generate:
11220
11221 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
11222
11223 See also: "unique-id-header"
11224
11225unique-id-header <name>
11226 Add a unique ID header in the HTTP request.
11227 May be used in sections : defaults | frontend | listen | backend
11228 yes | yes | yes | no
11229 Arguments :
11230 <name> is the name of the header.
11231
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011232 Add a unique-id header in the HTTP request sent to the server, using the
11233 unique-id-format. It can't work if the unique-id-format doesn't exist.
William Lallemanda73203e2012-03-12 12:48:57 +010011234
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011235 Example:
William Lallemanda73203e2012-03-12 12:48:57 +010011236
Julien Vehentf21be322014-03-07 08:27:34 -050011237 unique-id-format %{+X}o\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid
William Lallemanda73203e2012-03-12 12:48:57 +010011238 unique-id-header X-Unique-ID
11239
11240 will generate:
11241
11242 X-Unique-ID: 7F000001:8296_7F00001E:1F90_4F7B0A69_0003:790A
11243
11244 See also: "unique-id-format"
Willy Tarreau844e3c52008-01-11 16:28:18 +010011245
Willy Tarreauf51658d2014-04-23 01:21:56 +020011246use_backend <backend> [{if | unless} <condition>]
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020011247 Switch to a specific backend if/unless an ACL-based condition is matched.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011248 May be used in sections : defaults | frontend | listen | backend
11249 no | yes | yes | no
11250 Arguments :
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010011251 <backend> is the name of a valid backend or "listen" section, or a
11252 "log-format" string resolving to a backend name.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011253
Willy Tarreauf51658d2014-04-23 01:21:56 +020011254 <condition> is a condition composed of ACLs, as described in section 7. If
11255 it is omitted, the rule is unconditionally applied.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011256
11257 When doing content-switching, connections arrive on a frontend and are then
11258 dispatched to various backends depending on a number of conditions. The
11259 relation between the conditions and the backends is described with the
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020011260 "use_backend" keyword. While it is normally used with HTTP processing, it can
Davor Ocelice9ed2812017-12-25 17:49:28 +010011261 also be used in pure TCP, either without content using stateless ACLs (e.g.
Willy Tarreau1d0dfb12009-07-07 15:10:31 +020011262 source address validation) or combined with a "tcp-request" rule to wait for
11263 some payload.
Willy Tarreau844e3c52008-01-11 16:28:18 +010011264
11265 There may be as many "use_backend" rules as desired. All of these rules are
11266 evaluated in their declaration order, and the first one which matches will
11267 assign the backend.
11268
11269 In the first form, the backend will be used if the condition is met. In the
11270 second form, the backend will be used if the condition is not met. If no
11271 condition is valid, the backend defined with "default_backend" will be used.
11272 If no default backend is defined, either the servers in the same section are
11273 used (in case of a "listen" section) or, in case of a frontend, no server is
11274 used and a 503 service unavailable response is returned.
11275
Willy Tarreau51aecc72009-07-12 09:47:04 +020011276 Note that it is possible to switch from a TCP frontend to an HTTP backend. In
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010011277 this case, either the frontend has already checked that the protocol is HTTP,
Willy Tarreau51aecc72009-07-12 09:47:04 +020011278 and backend processing will immediately follow, or the backend will wait for
11279 a complete HTTP request to get in. This feature is useful when a frontend
11280 must decode several protocols on a unique port, one of them being HTTP.
11281
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010011282 When <backend> is a simple name, it is resolved at configuration time, and an
11283 error is reported if the specified backend does not exist. If <backend> is
11284 a log-format string instead, no check may be done at configuration time, so
11285 the backend name is resolved dynamically at run time. If the resulting
11286 backend name does not correspond to any valid backend, no other rule is
11287 evaluated, and the default_backend directive is applied instead. Note that
11288 when using dynamic backend names, it is highly recommended to use a prefix
11289 that no other backend uses in order to ensure that an unauthorized backend
11290 cannot be forced from the request.
11291
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011292 It is worth mentioning that "use_backend" rules with an explicit name are
Bertrand Jacquin702d44f2013-11-19 11:43:06 +010011293 used to detect the association between frontends and backends to compute the
11294 backend's "fullconn" setting. This cannot be done for dynamic names.
11295
11296 See also: "default_backend", "tcp-request", "fullconn", "log-format", and
11297 section 7 about ACLs.
Willy Tarreaud72758d2010-01-12 10:42:19 +010011298
Willy Tarreau036fae02008-01-06 13:24:40 +010011299
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011300use-server <server> if <condition>
11301use-server <server> unless <condition>
11302 Only use a specific server if/unless an ACL-based condition is matched.
11303 May be used in sections : defaults | frontend | listen | backend
11304 no | no | yes | yes
11305 Arguments :
Cyril Bonté108cf6e2012-04-21 23:30:29 +020011306 <server> is the name of a valid server in the same backend section.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011307
11308 <condition> is a condition composed of ACLs, as described in section 7.
11309
11310 By default, connections which arrive to a backend are load-balanced across
11311 the available servers according to the configured algorithm, unless a
11312 persistence mechanism such as a cookie is used and found in the request.
11313
11314 Sometimes it is desirable to forward a particular request to a specific
11315 server without having to declare a dedicated backend for this server. This
11316 can be achieved using the "use-server" rules. These rules are evaluated after
11317 the "redirect" rules and before evaluating cookies, and they have precedence
11318 on them. There may be as many "use-server" rules as desired. All of these
11319 rules are evaluated in their declaration order, and the first one which
11320 matches will assign the server.
11321
11322 If a rule designates a server which is down, and "option persist" is not used
11323 and no force-persist rule was validated, it is ignored and evaluation goes on
11324 with the next rules until one matches.
11325
11326 In the first form, the server will be used if the condition is met. In the
11327 second form, the server will be used if the condition is not met. If no
11328 condition is valid, the processing continues and the server will be assigned
11329 according to other persistence mechanisms.
11330
11331 Note that even if a rule is matched, cookie processing is still performed but
11332 does not assign the server. This allows prefixed cookies to have their prefix
11333 stripped.
11334
11335 The "use-server" statement works both in HTTP and TCP mode. This makes it
11336 suitable for use with content-based inspection. For instance, a server could
11337 be selected in a farm according to the TLS SNI field. And if these servers
11338 have their weight set to zero, they will not be used for other traffic.
11339
11340 Example :
11341 # intercept incoming TLS requests based on the SNI field
11342 use-server www if { req_ssl_sni -i www.example.com }
11343 server www 192.168.0.1:443 weight 0
11344 use-server mail if { req_ssl_sni -i mail.example.com }
11345 server mail 192.168.0.1:587 weight 0
11346 use-server imap if { req_ssl_sni -i imap.example.com }
Lukas Tribus98a3e3f2017-03-26 12:55:35 +000011347 server imap 192.168.0.1:993 weight 0
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011348 # all the rest is forwarded to this server
11349 server default 192.168.0.2:443 check
11350
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011351 See also: "use_backend", section 5 about server and section 7 about ACLs.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020011352
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011353
Davor Ocelice9ed2812017-12-25 17:49:28 +0100113545. Bind and server options
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011355--------------------------
11356
11357The "bind", "server" and "default-server" keywords support a number of settings
11358depending on some build options and on the system HAProxy was built on. These
11359settings generally each consist in one word sometimes followed by a value,
11360written on the same line as the "bind" or "server" line. All these options are
11361described in this section.
11362
11363
113645.1. Bind options
11365-----------------
11366
11367The "bind" keyword supports a certain number of settings which are all passed
11368as arguments on the same line. The order in which those arguments appear makes
11369no importance, provided that they appear after the bind address. All of these
11370parameters are optional. Some of them consist in a single words (booleans),
11371while other ones expect a value after them. In this case, the value must be
11372provided immediately after the setting name.
11373
11374The currently supported settings are the following ones.
11375
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010011376accept-netscaler-cip <magic number>
11377 Enforces the use of the NetScaler Client IP insertion protocol over any
11378 connection accepted by any of the TCP sockets declared on the same line. The
11379 NetScaler Client IP insertion protocol dictates the layer 3/4 addresses of
11380 the incoming connection to be used everywhere an address is used, with the
11381 only exception of "tcp-request connection" rules which will only see the
11382 real connection address. Logs will reflect the addresses indicated in the
11383 protocol, unless it is violated, in which case the real address will still
11384 be used. This keyword combined with support from external components can be
11385 used as an efficient and reliable alternative to the X-Forwarded-For
Bertrand Jacquin90759682016-06-06 15:35:39 +010011386 mechanism which is not always reliable and not even always usable. See also
11387 "tcp-request connection expect-netscaler-cip" for a finer-grained setting of
11388 which client is allowed to use the protocol.
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010011389
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011390accept-proxy
11391 Enforces the use of the PROXY protocol over any connection accepted by any of
Willy Tarreau77992672014-06-14 11:06:17 +020011392 the sockets declared on the same line. Versions 1 and 2 of the PROXY protocol
11393 are supported and correctly detected. The PROXY protocol dictates the layer
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011394 3/4 addresses of the incoming connection to be used everywhere an address is
11395 used, with the only exception of "tcp-request connection" rules which will
11396 only see the real connection address. Logs will reflect the addresses
11397 indicated in the protocol, unless it is violated, in which case the real
Davor Ocelice9ed2812017-12-25 17:49:28 +010011398 address will still be used. This keyword combined with support from external
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011399 components can be used as an efficient and reliable alternative to the
11400 X-Forwarded-For mechanism which is not always reliable and not even always
Willy Tarreau4f0d9192013-06-11 20:40:55 +020011401 usable. See also "tcp-request connection expect-proxy" for a finer-grained
11402 setting of which client is allowed to use the protocol.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011403
Olivier Houchardc2aae742017-09-22 18:26:28 +020011404allow-0rtt
Bertrand Jacquina25282b2018-08-14 00:56:13 +010011405 Allow receiving early data when using TLSv1.3. This is disabled by default,
Olivier Houchard69752962019-01-08 15:35:32 +010011406 due to security considerations. Because it is vulnerable to replay attacks,
John Roesler27c754c2019-07-10 15:45:51 -050011407 you should only allow if for requests that are safe to replay, i.e. requests
Olivier Houchard69752962019-01-08 15:35:32 +010011408 that are idempotent. You can use the "wait-for-handshake" action for any
11409 request that wouldn't be safe with early data.
Olivier Houchardc2aae742017-09-22 18:26:28 +020011410
Willy Tarreauab861d32013-04-02 02:30:41 +020011411alpn <protocols>
11412 This enables the TLS ALPN extension and advertises the specified protocol
11413 list as supported on top of ALPN. The protocol list consists in a comma-
11414 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roesler27c754c2019-07-10 15:45:51 -050011415 quotes). This requires that the SSL library is built with support for TLS
Willy Tarreauab861d32013-04-02 02:30:41 +020011416 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
Willy Tarreau95c4e142017-11-26 12:18:55 +010011417 initial NPN extension. ALPN is required to enable HTTP/2 on an HTTP frontend.
11418 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
11419 now obsolete NPN extension. At the time of writing this, most browsers still
11420 support both ALPN and NPN for HTTP/2 so a fallback to NPN may still work for
11421 a while. But ALPN must be used whenever possible. If both HTTP/2 and HTTP/1.1
11422 are expected to be supported, both versions can be advertised, in order of
11423 preference, like below :
11424
11425 bind :443 ssl crt pub.pem alpn h2,http/1.1
Willy Tarreauab861d32013-04-02 02:30:41 +020011426
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011427backlog <backlog>
Willy Tarreaue2711c72019-02-27 15:39:41 +010011428 Sets the socket's backlog to this value. If unspecified or 0, the frontend's
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011429 backlog is used instead, which generally defaults to the maxconn value.
11430
Emmanuel Hocdete7f2b732017-01-09 16:15:54 +010011431curves <curves>
11432 This setting is only available when support for OpenSSL was built in. It sets
11433 the string describing the list of elliptic curves algorithms ("curve suite")
11434 that are negotiated during the SSL/TLS handshake with ECDHE. The format of the
11435 string is a colon-delimited list of curve name.
11436 Example: "X25519:P-256" (without quote)
11437 When "curves" is set, "ecdhe" parameter is ignored.
11438
Emeric Brun7fb34422012-09-28 15:26:15 +020011439ecdhe <named curve>
11440 This setting is only available when support for OpenSSL was built in. It sets
Emeric Brun6924ef82013-03-06 14:08:53 +010011441 the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
11442 used named curve is prime256v1.
Emeric Brun7fb34422012-09-28 15:26:15 +020011443
Emeric Brunfd33a262012-10-11 16:28:27 +020011444ca-file <cafile>
Emeric Brun1a073b42012-09-28 17:07:34 +020011445 This setting is only available when support for OpenSSL was built in. It
11446 designates a PEM file from which to load CA certificates used to verify
11447 client's certificate.
11448
Emeric Brunb6dc9342012-09-28 17:55:37 +020011449ca-ignore-err [all|<errorID>,...]
11450 This setting is only available when support for OpenSSL was built in.
11451 Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
11452 If set to 'all', all errors are ignored. SSL handshake is not aborted if an
11453 error is ignored.
11454
Christopher Faulet31af49d2015-06-09 17:29:50 +020011455ca-sign-file <cafile>
11456 This setting is only available when support for OpenSSL was built in. It
11457 designates a PEM file containing both the CA certificate and the CA private
11458 key used to create and sign server's certificates. This is a mandatory
11459 setting when the dynamic generation of certificates is enabled. See
11460 'generate-certificates' for details.
11461
Bertrand Jacquind4d0a232016-11-13 16:37:12 +000011462ca-sign-pass <passphrase>
Christopher Faulet31af49d2015-06-09 17:29:50 +020011463 This setting is only available when support for OpenSSL was built in. It is
11464 the CA private key passphrase. This setting is optional and used only when
11465 the dynamic generation of certificates is enabled. See
11466 'generate-certificates' for details.
11467
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011468ciphers <ciphers>
11469 This setting is only available when support for OpenSSL was built in. It sets
11470 the string describing the list of cipher algorithms ("cipher suite") that are
Bertrand Jacquin8cf7c1e2019-02-03 18:35:25 +000011471 negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000011472 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
Dirkjan Bussink415150f2018-09-14 11:14:21 +020011473 information and recommendations see e.g.
11474 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
11475 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
11476 cipher configuration, please check the "ciphersuites" keyword.
11477
11478ciphersuites <ciphersuites>
11479 This setting is only available when support for OpenSSL was built in and
11480 OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
11481 the list of cipher algorithms ("cipher suite") that are negotiated during the
11482 TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000011483 OpenSSL man pages under the "ciphersuites" section. For cipher configuration
11484 for TLSv1.2 and earlier, please check the "ciphers" keyword.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011485
Emeric Brunfd33a262012-10-11 16:28:27 +020011486crl-file <crlfile>
Emeric Brun1a073b42012-09-28 17:07:34 +020011487 This setting is only available when support for OpenSSL was built in. It
11488 designates a PEM file from which to load certificate revocation list used
11489 to verify client's certificate.
11490
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011491crt <cert>
Alex Davies0fbf0162013-03-02 16:04:50 +000011492 This setting is only available when support for OpenSSL was built in. It
11493 designates a PEM file containing both the required certificates and any
11494 associated private keys. This file can be built by concatenating multiple
11495 PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
11496 requires an intermediate certificate, this can also be concatenated into this
11497 file.
11498
11499 If the OpenSSL used supports Diffie-Hellman, parameters present in this file
11500 are loaded.
11501
11502 If a directory name is used instead of a PEM file, then all files found in
Cyril Bonté3180f7b2015-01-25 00:16:08 +010011503 that directory will be loaded in alphabetic order unless their name ends with
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010011504 '.issuer', '.ocsp' or '.sctl' (reserved extensions). This directive may be
11505 specified multiple times in order to load certificates from multiple files or
11506 directories. The certificates will be presented to clients who provide a
11507 valid TLS Server Name Indication field matching one of their CN or alt
Davor Ocelice9ed2812017-12-25 17:49:28 +010011508 subjects. Wildcards are supported, where a wildcard character '*' is used
11509 instead of the first hostname component (e.g. *.example.org matches
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010011510 www.example.org but not www.sub.example.org).
Alex Davies0fbf0162013-03-02 16:04:50 +000011511
11512 If no SNI is provided by the client or if the SSL library does not support
11513 TLS extensions, or if the client provides an SNI hostname which does not
11514 match any certificate, then the first loaded certificate will be presented.
11515 This means that when loading certificates from a directory, it is highly
Cyril Bonté3180f7b2015-01-25 00:16:08 +010011516 recommended to load the default one first as a file or to ensure that it will
11517 always be the first one in the directory.
Alex Davies0fbf0162013-03-02 16:04:50 +000011518
Emeric Brune032bfa2012-09-28 13:01:45 +020011519 Note that the same cert may be loaded multiple times without side effects.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011520
Davor Ocelice9ed2812017-12-25 17:49:28 +010011521 Some CAs (such as GoDaddy) offer a drop down list of server types that do not
Alex Davies0fbf0162013-03-02 16:04:50 +000011522 include HAProxy when obtaining a certificate. If this happens be sure to
Davor Ocelice9ed2812017-12-25 17:49:28 +010011523 choose a web server that the CA believes requires an intermediate CA (for
11524 GoDaddy, selection Apache Tomcat will get the correct bundle, but many
Alex Davies0fbf0162013-03-02 16:04:50 +000011525 others, e.g. nginx, result in a wrong bundle that will not work for some
11526 clients).
11527
Emeric Brun4147b2e2014-06-16 18:36:30 +020011528 For each PEM file, haproxy checks for the presence of file at the same path
11529 suffixed by ".ocsp". If such file is found, support for the TLS Certificate
11530 Status Request extension (also known as "OCSP stapling") is automatically
11531 enabled. The content of this file is optional. If not empty, it must contain
11532 a valid OCSP Response in DER format. In order to be valid an OCSP Response
11533 must comply with the following rules: it has to indicate a good status,
11534 it has to be a single response for the certificate of the PEM file, and it
11535 has to be valid at the moment of addition. If these rules are not respected
11536 the OCSP Response is ignored and a warning is emitted. In order to identify
11537 which certificate an OCSP Response applies to, the issuer's certificate is
11538 necessary. If the issuer's certificate is not found in the PEM file, it will
11539 be loaded from a file at the same path as the PEM file suffixed by ".issuer"
11540 if it exists otherwise it will fail with an error.
11541
Janusz Dziemidowicz2c701b52015-03-07 23:03:59 +010011542 For each PEM file, haproxy also checks for the presence of file at the same
11543 path suffixed by ".sctl". If such file is found, support for Certificate
11544 Transparency (RFC6962) TLS extension is enabled. The file must contain a
11545 valid Signed Certificate Timestamp List, as described in RFC. File is parsed
11546 to check basic syntax, but no signatures are verified.
11547
yanbzhu6c25e9e2016-01-05 12:52:02 -050011548 There are cases where it is desirable to support multiple key types, e.g. RSA
11549 and ECDSA in the cipher suites offered to the clients. This allows clients
11550 that support EC certificates to be able to use EC ciphers, while
11551 simultaneously supporting older, RSA only clients.
yanbzhud19630c2015-12-14 15:10:25 -050011552
11553 In order to provide this functionality, multiple PEM files, each with a
11554 different key type, are required. To associate these PEM files into a
11555 "cert bundle" that is recognized by haproxy, they must be named in the
11556 following way: All PEM files that are to be bundled must have the same base
11557 name, with a suffix indicating the key type. Currently, three suffixes are
11558 supported: rsa, dsa and ecdsa. For example, if www.example.com has two PEM
11559 files, an RSA file and an ECDSA file, they must be named: "example.pem.rsa"
11560 and "example.pem.ecdsa". The first part of the filename is arbitrary; only the
11561 suffix matters. To load this bundle into haproxy, specify the base name only:
11562
11563 Example : bind :8443 ssl crt example.pem
11564
yanbzhu6c25e9e2016-01-05 12:52:02 -050011565 Note that the suffix is not given to haproxy; this tells haproxy to look for
yanbzhud19630c2015-12-14 15:10:25 -050011566 a cert bundle.
11567
Davor Ocelice9ed2812017-12-25 17:49:28 +010011568 HAProxy will load all PEM files in the bundle at the same time to try to
yanbzhud19630c2015-12-14 15:10:25 -050011569 support multiple key types. PEM files are combined based on Common Name
11570 (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means
11571 that even if you give haproxy a cert bundle, if there are no shared CN/SAN
11572 entries in the certificates in that bundle, haproxy will not be able to
11573 provide multi-cert support.
11574
11575 Assuming bundle in the example above contained the following:
11576
11577 Filename | CN | SAN
11578 -------------------+-----------------+-------------------
11579 example.pem.rsa | www.example.com | rsa.example.com
yanbzhu6c25e9e2016-01-05 12:52:02 -050011580 -------------------+-----------------+-------------------
yanbzhud19630c2015-12-14 15:10:25 -050011581 example.pem.ecdsa | www.example.com | ecdsa.example.com
11582 -------------------+-----------------+-------------------
11583
11584 Users connecting with an SNI of "www.example.com" will be able
11585 to use both RSA and ECDSA cipher suites. Users connecting with an SNI of
11586 "rsa.example.com" will only be able to use RSA cipher suites, and users
11587 connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020011588 suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
11589 no need to bundle certificates. ECDSA certificate will be preferred if client
11590 support it.
yanbzhud19630c2015-12-14 15:10:25 -050011591
11592 If a directory name is given as the <cert> argument, haproxy will
11593 automatically search and load bundled files in that directory.
11594
11595 OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
11596 bundling. Each certificate can have its own .ocsp and .issuer file. At this
11597 time, sctl is not supported in multi-certificate bundling.
11598
Emeric Brunb6dc9342012-09-28 17:55:37 +020011599crt-ignore-err <errors>
Alex Davies0fbf0162013-03-02 16:04:50 +000011600 This setting is only available when support for OpenSSL was built in. Sets a
Davor Ocelice9ed2812017-12-25 17:49:28 +010011601 comma separated list of errorIDs to ignore during verify at depth == 0. If
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011602 set to 'all', all errors are ignored. SSL handshake is not aborted if an error
Alex Davies0fbf0162013-03-02 16:04:50 +000011603 is ignored.
Emeric Brunb6dc9342012-09-28 17:55:37 +020011604
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010011605crt-list <file>
11606 This setting is only available when support for OpenSSL was built in. It
Emmanuel Hocdet98263292016-12-29 18:26:15 +010011607 designates a list of PEM file with an optional ssl configuration and a SNI
11608 filter per certificate, with the following format for each line :
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010011609
Emmanuel Hocdet98263292016-12-29 18:26:15 +010011610 <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
11611
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020011612 sslbindconf support "npn", "alpn", "verify", "ca-file", "no-ca-names",
11613 crl-file", "ecdhe", "curves", "ciphers" configuration. With BoringSSL
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020011614 and Openssl >= 1.1.1 "ssl-min-ver" and "ssl-max-ver" are also supported.
Emmanuel Hocdet98263292016-12-29 18:26:15 +010011615 It override the configuration set in bind line for the certificate.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010011616
Emmanuel Hocdet7c41a1b2013-05-07 20:20:06 +020011617 Wildcards are supported in the SNI filter. Negative filter are also supported,
11618 only useful in combination with a wildcard filter to exclude a particular SNI.
11619 The certificates will be presented to clients who provide a valid TLS Server
11620 Name Indication field matching one of the SNI filters. If no SNI filter is
11621 specified, the CN and alt subjects are used. This directive may be specified
11622 multiple times. See the "crt" option for more information. The default
11623 certificate is still needed to meet OpenSSL expectations. If it is not used,
11624 the 'strict-sni' option may be used.
Emmanuel Hocdetfe616562013-01-22 15:31:15 +010011625
yanbzhu6c25e9e2016-01-05 12:52:02 -050011626 Multi-cert bundling (see "crt") is supported with crt-list, as long as only
Emmanuel Hocdetd294aea2016-05-13 11:14:06 +020011627 the base name is given in the crt-list. SNI filter will do the same work on
Emmanuel Hocdet84e417d2017-08-16 11:33:17 +020011628 all bundled certificates. With BoringSSL and Openssl >= 1.1.1 multi-cert is
11629 natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
11630 be declared in a row, and set different ssl and filter parameter.
yanbzhud19630c2015-12-14 15:10:25 -050011631
Emmanuel Hocdet98263292016-12-29 18:26:15 +010011632 crt-list file example:
11633 cert1.pem
Emmanuel Hocdet05942112017-02-20 16:11:50 +010011634 cert2.pem [alpn h2,http/1.1]
Emmanuel Hocdet98263292016-12-29 18:26:15 +010011635 certW.pem *.domain.tld !secure.domain.tld
Emmanuel Hocdet05942112017-02-20 16:11:50 +010011636 certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld
Emmanuel Hocdet98263292016-12-29 18:26:15 +010011637
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011638defer-accept
11639 Is an optional keyword which is supported only on certain Linux kernels. It
11640 states that a connection will only be accepted once some data arrive on it,
11641 or at worst after the first retransmit. This should be used only on protocols
Davor Ocelice9ed2812017-12-25 17:49:28 +010011642 for which the client talks first (e.g. HTTP). It can slightly improve
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011643 performance by ensuring that most of the request is already available when
11644 the connection is accepted. On the other hand, it will not be able to detect
11645 connections which don't talk. It is important to note that this option is
11646 broken in all kernels up to 2.6.31, as the connection is never accepted until
11647 the client talks. This can cause issues with front firewalls which would see
11648 an established connection while the proxy will only see it in SYN_RECV. This
11649 option is only supported on TCPv4/TCPv6 sockets and ignored by other ones.
11650
William Lallemandf6975e92017-05-26 17:42:10 +020011651expose-fd listeners
11652 This option is only usable with the stats socket. It gives your stats socket
11653 the capability to pass listeners FD to another HAProxy process.
William Lallemande202b1e2017-06-01 17:38:56 +020011654 During a reload with the master-worker mode, the process is automatically
11655 reexecuted adding -x and one of the stats socket with this option.
Davor Ocelice9ed2812017-12-25 17:49:28 +010011656 See also "-x" in the management guide.
William Lallemandf6975e92017-05-26 17:42:10 +020011657
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011658force-sslv3
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011659 This option enforces use of SSLv3 only on SSL connections instantiated from
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011660 this listener. SSLv3 is generally less expensive than the TLS counterparts
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011661 for high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011662 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011663
11664force-tlsv10
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011665 This option enforces use of TLSv1.0 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011666 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011667 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011668
11669force-tlsv11
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011670 This option enforces use of TLSv1.1 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011671 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011672 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011673
11674force-tlsv12
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011675 This option enforces use of TLSv1.2 only on SSL connections instantiated from
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011676 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011677 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011678
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011679force-tlsv13
11680 This option enforces use of TLSv1.3 only on SSL connections instantiated from
11681 this listener. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011682 "ssl-default-bind-options". See also "ssl-min-ver" and "ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011683
Christopher Faulet31af49d2015-06-09 17:29:50 +020011684generate-certificates
11685 This setting is only available when support for OpenSSL was built in. It
11686 enables the dynamic SSL certificates generation. A CA certificate and its
11687 private key are necessary (see 'ca-sign-file'). When HAProxy is configured as
11688 a transparent forward proxy, SSL requests generate errors because of a common
11689 name mismatch on the certificate presented to the client. With this option
11690 enabled, HAProxy will try to forge a certificate using the SNI hostname
11691 indicated by the client. This is done only if no certificate matches the SNI
11692 hostname (see 'crt-list'). If an error occurs, the default certificate is
11693 used, else the 'strict-sni' option is set.
11694 It can also be used when HAProxy is configured as a reverse proxy to ease the
11695 deployment of an architecture with many backends.
11696
11697 Creating a SSL certificate is an expensive operation, so a LRU cache is used
11698 to store forged certificates (see 'tune.ssl.ssl-ctx-cache-size'). It
Davor Ocelice9ed2812017-12-25 17:49:28 +010011699 increases the HAProxy's memory footprint to reduce latency when the same
Christopher Faulet31af49d2015-06-09 17:29:50 +020011700 certificate is used many times.
11701
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011702gid <gid>
11703 Sets the group of the UNIX sockets to the designated system gid. It can also
11704 be set by default in the global section's "unix-bind" statement. Note that
11705 some platforms simply ignore this. This setting is equivalent to the "group"
11706 setting except that the group ID is used instead of its name. This setting is
11707 ignored by non UNIX sockets.
11708
11709group <group>
11710 Sets the group of the UNIX sockets to the designated system group. It can
11711 also be set by default in the global section's "unix-bind" statement. Note
11712 that some platforms simply ignore this. This setting is equivalent to the
11713 "gid" setting except that the group name is used instead of its gid. This
11714 setting is ignored by non UNIX sockets.
11715
11716id <id>
11717 Fixes the socket ID. By default, socket IDs are automatically assigned, but
11718 sometimes it is more convenient to fix them to ease monitoring. This value
11719 must be strictly positive and unique within the listener/frontend. This
11720 option can only be used when defining only a single socket.
11721
11722interface <interface>
Lukas Tribusfce2e962013-02-12 22:13:19 +010011723 Restricts the socket to a specific interface. When specified, only packets
11724 received from that particular interface are processed by the socket. This is
11725 currently only supported on Linux. The interface must be a primary system
11726 interface, not an aliased interface. It is also possible to bind multiple
11727 frontends to the same address if they are bound to different interfaces. Note
11728 that binding to a network interface requires root privileges. This parameter
Jérôme Magnin61275192018-02-07 11:39:58 +010011729 is only compatible with TCPv4/TCPv6 sockets. When specified, return traffic
11730 uses the same interface as inbound traffic, and its associated routing table,
11731 even if there are explicit routes through different interfaces configured.
11732 This can prove useful to address asymmetric routing issues when the same
11733 client IP addresses need to be able to reach frontends hosted on different
11734 interfaces.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011735
Willy Tarreauabb175f2012-09-24 12:43:26 +020011736level <level>
11737 This setting is used with the stats sockets only to restrict the nature of
11738 the commands that can be issued on the socket. It is ignored by other
11739 sockets. <level> can be one of :
Davor Ocelice9ed2812017-12-25 17:49:28 +010011740 - "user" is the least privileged level; only non-sensitive stats can be
Willy Tarreauabb175f2012-09-24 12:43:26 +020011741 read, and no change is allowed. It would make sense on systems where it
11742 is not easy to restrict access to the socket.
11743 - "operator" is the default level and fits most common uses. All data can
Davor Ocelice9ed2812017-12-25 17:49:28 +010011744 be read, and only non-sensitive changes are permitted (e.g. clear max
Willy Tarreauabb175f2012-09-24 12:43:26 +020011745 counters).
Davor Ocelice9ed2812017-12-25 17:49:28 +010011746 - "admin" should be used with care, as everything is permitted (e.g. clear
Willy Tarreauabb175f2012-09-24 12:43:26 +020011747 all counters).
11748
Andjelko Iharosc4df59e2017-07-20 11:59:48 +020011749severity-output <format>
11750 This setting is used with the stats sockets only to configure severity
11751 level output prepended to informational feedback messages. Severity
11752 level of messages can range between 0 and 7, conforming to syslog
11753 rfc5424. Valid and successful socket commands requesting data
11754 (i.e. "show map", "get acl foo" etc.) will never have a severity level
11755 prepended. It is ignored by other sockets. <format> can be one of :
11756 - "none" (default) no severity level is prepended to feedback messages.
11757 - "number" severity level is prepended as a number.
11758 - "string" severity level is prepended as a string following the
11759 rfc5424 convention.
11760
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011761maxconn <maxconn>
11762 Limits the sockets to this number of concurrent connections. Extraneous
11763 connections will remain in the system's backlog until a connection is
11764 released. If unspecified, the limit will be the same as the frontend's
11765 maxconn. Note that in case of port ranges or multiple addresses, the same
11766 value will be applied to each socket. This setting enables different
11767 limitations on expensive sockets, for instance SSL entries which may easily
11768 eat all memory.
11769
11770mode <mode>
11771 Sets the octal mode used to define access permissions on the UNIX socket. It
11772 can also be set by default in the global section's "unix-bind" statement.
11773 Note that some platforms simply ignore this. This setting is ignored by non
11774 UNIX sockets.
11775
11776mss <maxseg>
11777 Sets the TCP Maximum Segment Size (MSS) value to be advertised on incoming
11778 connections. This can be used to force a lower MSS for certain specific
11779 ports, for instance for connections passing through a VPN. Note that this
11780 relies on a kernel feature which is theoretically supported under Linux but
11781 was buggy in all versions prior to 2.6.28. It may or may not work on other
11782 operating systems. It may also not change the advertised value but change the
11783 effective size of outgoing segments. The commonly advertised value for TCPv4
11784 over Ethernet networks is 1460 = 1500(MTU) - 40(IP+TCP). If this value is
11785 positive, it will be used as the advertised MSS. If it is negative, it will
11786 indicate by how much to reduce the incoming connection's advertised MSS for
11787 outgoing segments. This parameter is only compatible with TCP v4/v6 sockets.
11788
11789name <name>
11790 Sets an optional name for these sockets, which will be reported on the stats
11791 page.
11792
Willy Tarreaud72f0f32015-10-13 14:50:22 +020011793namespace <name>
11794 On Linux, it is possible to specify which network namespace a socket will
11795 belong to. This directive makes it possible to explicitly bind a listener to
11796 a namespace different from the default one. Please refer to your operating
11797 system's documentation to find more details about network namespaces.
11798
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011799nice <nice>
11800 Sets the 'niceness' of connections initiated from the socket. Value must be
11801 in the range -1024..1024 inclusive, and defaults to zero. Positive values
11802 means that such connections are more friendly to others and easily offer
11803 their place in the scheduler. On the opposite, negative values mean that
11804 connections want to run with a higher priority than others. The difference
11805 only happens under high loads when the system is close to saturation.
11806 Negative values are appropriate for low-latency or administration services,
11807 and high values are generally recommended for CPU intensive tasks such as SSL
11808 processing or bulk transfers which are less sensible to latency. For example,
11809 it may make sense to use a positive value for an SMTP socket and a negative
11810 one for an RDP socket.
11811
Emmanuel Hocdet174dfe52017-07-28 15:01:05 +020011812no-ca-names
11813 This setting is only available when support for OpenSSL was built in. It
11814 prevents from send CA names in server hello message when ca-file is used.
11815
Emeric Brun9b3009b2012-10-05 11:55:06 +020011816no-sslv3
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011817 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011818 disables support for SSLv3 on any sockets instantiated from the listener when
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011819 SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011820 be enabled using any configuration option. This option is also available on
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011821 global statement "ssl-default-bind-options". Use "ssl-min-ver" and
11822 "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011823
Emeric Brun90ad8722012-10-02 14:00:59 +020011824no-tls-tickets
11825 This setting is only available when support for OpenSSL was built in. It
11826 disables the stateless session resumption (RFC 5077 TLS Ticket
11827 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011828 session resumption is more expensive in CPU usage. This option is also
11829 available on global statement "ssl-default-bind-options".
Lukas Tribusd8fd6362020-03-10 00:56:09 +010011830 The TLS ticket mechanism is only used up to TLS 1.2.
11831 Forward Secrecy is compromised with TLS tickets, unless ticket keys
11832 are periodically rotated (via reload or by using "tls-ticket-keys").
Emeric Brun90ad8722012-10-02 14:00:59 +020011833
Emeric Brun9b3009b2012-10-05 11:55:06 +020011834no-tlsv10
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011835 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011836 disables support for TLSv1.0 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011837 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011838 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011839 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11840 and "ssl-max-ver" instead.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011841
Emeric Brun9b3009b2012-10-05 11:55:06 +020011842no-tlsv11
Emeric Brunf5da4932012-09-28 19:42:54 +020011843 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011844 disables support for TLSv1.1 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011845 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011846 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011847 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11848 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020011849
Emeric Brun9b3009b2012-10-05 11:55:06 +020011850no-tlsv12
Emeric Brunf5da4932012-09-28 19:42:54 +020011851 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011852 disables support for TLSv1.2 on any sockets instantiated from the listener
Emeric Brun2cb7ae52012-10-05 14:14:21 +020011853 when SSL is supported. Note that SSLv2 is forced disabled in the code and
Emeric Brun2c86cbf2014-10-30 15:56:50 +010011854 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011855 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11856 and "ssl-max-ver" instead.
Emeric Brunf5da4932012-09-28 19:42:54 +020011857
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011858no-tlsv13
11859 This setting is only available when support for OpenSSL was built in. It
11860 disables support for TLSv1.3 on any sockets instantiated from the listener
11861 when SSL is supported. Note that SSLv2 is forced disabled in the code and
11862 cannot be enabled using any configuration option. This option is also
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011863 available on global statement "ssl-default-bind-options". Use "ssl-min-ver"
11864 and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020011865
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020011866npn <protocols>
11867 This enables the NPN TLS extension and advertises the specified protocol list
11868 as supported on top of NPN. The protocol list consists in a comma-delimited
11869 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roesler27c754c2019-07-10 15:45:51 -050011870 This requires that the SSL library is built with support for TLS extensions
Willy Tarreauab861d32013-04-02 02:30:41 +020011871 enabled (check with haproxy -vv). Note that the NPN extension has been
Willy Tarreau95c4e142017-11-26 12:18:55 +010011872 replaced with the ALPN extension (see the "alpn" keyword), though this one is
11873 only available starting with OpenSSL 1.0.2. If HTTP/2 is desired on an older
11874 version of OpenSSL, NPN might still be used as most clients still support it
11875 at the time of writing this. It is possible to enable both NPN and ALPN
11876 though it probably doesn't make any sense out of testing.
Willy Tarreau6c9a3d52012-10-18 18:57:14 +020011877
Lukas Tribus53ae85c2017-05-04 15:45:40 +000011878prefer-client-ciphers
11879 Use the client's preference when selecting the cipher suite, by default
11880 the server's preference is enforced. This option is also available on
11881 global statement "ssl-default-bind-options".
Lukas Tribus926594f2018-05-18 17:55:57 +020011882 Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
11883 (without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
11884 the client cipher list.
Lukas Tribus53ae85c2017-05-04 15:45:40 +000011885
Christopher Fauletc644fa92017-11-23 22:44:11 +010011886process <process-set>[/<thread-set>]
Willy Tarreaua36b3242019-02-02 13:14:34 +010011887 This restricts the list of processes or threads on which this listener is
Christopher Fauletc644fa92017-11-23 22:44:11 +010011888 allowed to run. It does not enforce any process but eliminates those which do
Davor Ocelice9ed2812017-12-25 17:49:28 +010011889 not match. If the frontend uses a "bind-process" setting, the intersection
Christopher Fauletc644fa92017-11-23 22:44:11 +010011890 between the two is applied. If in the end the listener is not allowed to run
11891 on any remaining process, a warning is emitted, and the listener will either
11892 run on the first process of the listener if a single process was specified,
11893 or on all of its processes if multiple processes were specified. If a thread
Davor Ocelice9ed2812017-12-25 17:49:28 +010011894 set is specified, it limits the threads allowed to process incoming
Willy Tarreaua36b3242019-02-02 13:14:34 +010011895 connections for this listener, for the the process set. If multiple processes
11896 and threads are configured, a warning is emitted, as it either results from a
11897 configuration error or a misunderstanding of these models. For the unlikely
11898 case where several ranges are needed, this directive may be repeated.
11899 <process-set> and <thread-set> must use the format
Christopher Fauletc644fa92017-11-23 22:44:11 +010011900
11901 all | odd | even | number[-[number]]
11902
11903 Ranges can be partially defined. The higher bound can be omitted. In such
11904 case, it is replaced by the corresponding maximum value. The main purpose of
11905 this directive is to be used with the stats sockets and have one different
11906 socket per process. The second purpose is to have multiple bind lines sharing
11907 the same IP:port but not the same process in a listener, so that the system
11908 can distribute the incoming connections into multiple queues and allow a
11909 smoother inter-process load balancing. Currently Linux 3.9 and above is known
11910 for supporting this. See also "bind-process" and "nbproc".
Willy Tarreau6ae1ba62014-05-07 19:01:58 +020011911
Christopher Fauleta717b992018-04-10 14:43:00 +020011912proto <name>
11913 Forces the multiplexer's protocol to use for the incoming connections. It
11914 must be compatible with the mode of the frontend (TCP or HTTP). It must also
11915 be usable on the frontend side. The list of available protocols is reported
11916 in haproxy -vv.
11917 Idea behind this optipon is to bypass the selection of the best multiplexer's
11918 protocol for all connections instantiated from this listening socket. For
Joseph Herlant71b4b152018-11-13 16:55:16 -080011919 instance, it is possible to force the http/2 on clear TCP by specifying "proto
Christopher Fauleta717b992018-04-10 14:43:00 +020011920 h2" on the bind line.
11921
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011922ssl
11923 This setting is only available when support for OpenSSL was built in. It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030011924 enables SSL deciphering on connections instantiated from this listener. A
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011925 certificate is necessary (see "crt" above). All contents in the buffers will
11926 appear in clear text, so that ACLs and HTTP processing will only have access
Emmanuel Hocdetbd695fe2017-05-15 15:53:41 +020011927 to deciphered contents. SSLv3 is disabled per default, use "ssl-min-ver SSLv3"
11928 to enable it.
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011929
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020011930ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11931 This option enforces use of <version> or lower on SSL connections instantiated
11932 from this listener. This option is also available on global statement
11933 "ssl-default-bind-options". See also "ssl-min-ver".
11934
11935ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
11936 This option enforces use of <version> or upper on SSL connections instantiated
11937 from this listener. This option is also available on global statement
11938 "ssl-default-bind-options". See also "ssl-max-ver".
11939
Emmanuel Hocdet65623372013-01-24 17:17:15 +010011940strict-sni
11941 This setting is only available when support for OpenSSL was built in. The
11942 SSL/TLS negotiation is allow only if the client provided an SNI which match
11943 a certificate. The default certificate is not used.
11944 See the "crt" option for more information.
11945
Willy Tarreau2af207a2015-02-04 00:45:58 +010011946tcp-ut <delay>
Tim Düsterhus4896c442016-11-29 02:15:19 +010011947 Sets the TCP User Timeout for all incoming connections instantiated from this
Willy Tarreau2af207a2015-02-04 00:45:58 +010011948 listening socket. This option is available on Linux since version 2.6.37. It
11949 allows haproxy to configure a timeout for sockets which contain data not
Davor Ocelice9ed2812017-12-25 17:49:28 +010011950 receiving an acknowledgment for the configured delay. This is especially
Willy Tarreau2af207a2015-02-04 00:45:58 +010011951 useful on long-lived connections experiencing long idle periods such as
11952 remote terminals or database connection pools, where the client and server
11953 timeouts must remain high to allow a long period of idle, but where it is
11954 important to detect that the client has disappeared in order to release all
11955 resources associated with its connection (and the server's session). The
11956 argument is a delay expressed in milliseconds by default. This only works
11957 for regular TCP connections, and is ignored for other protocols.
11958
Willy Tarreau1c862c52012-10-05 16:21:00 +020011959tfo
Lukas Tribus0defb902013-02-13 23:35:39 +010011960 Is an optional keyword which is supported only on Linux kernels >= 3.7. It
Willy Tarreau1c862c52012-10-05 16:21:00 +020011961 enables TCP Fast Open on the listening socket, which means that clients which
11962 support this feature will be able to send a request and receive a response
11963 during the 3-way handshake starting from second connection, thus saving one
11964 round-trip after the first connection. This only makes sense with protocols
11965 that use high connection rates and where each round trip matters. This can
11966 possibly cause issues with many firewalls which do not accept data on SYN
11967 packets, so this option should only be enabled once well tested. This option
Lukas Tribus0999f762013-04-02 16:43:24 +020011968 is only supported on TCPv4/TCPv6 sockets and ignored by other ones. You may
11969 need to build HAProxy with USE_TFO=1 if your libc doesn't define
11970 TCP_FASTOPEN.
Willy Tarreau1c862c52012-10-05 16:21:00 +020011971
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010011972tls-ticket-keys <keyfile>
11973 Sets the TLS ticket keys file to load the keys from. The keys need to be 48
Emeric Brun9e754772019-01-10 17:51:55 +010011974 or 80 bytes long, depending if aes128 or aes256 is used, encoded with base64
11975 with one line per key (ex. openssl rand 80 | openssl base64 -A | xargs echo).
11976 The first key determines the key length used for next keys: you can't mix
11977 aes128 and aes256 keys. Number of keys is specified by the TLS_TICKETS_NO
11978 build option (default 3) and at least as many keys need to be present in
11979 the file. Last TLS_TICKETS_NO keys will be used for decryption and the
11980 penultimate one for encryption. This enables easy key rotation by just
11981 appending new key to the file and reloading the process. Keys must be
11982 periodically rotated (ex. every 12h) or Perfect Forward Secrecy is
11983 compromised. It is also a good idea to keep the keys off any permanent
Nenad Merdanovic188ad3e2015-02-27 19:56:50 +010011984 storage such as hard drives (hint: use tmpfs and don't swap those files).
11985 Lifetime hint can be changed using tune.ssl.timeout.
11986
Willy Tarreaub6205fd2012-09-24 12:27:33 +020011987transparent
11988 Is an optional keyword which is supported only on certain Linux kernels. It
11989 indicates that the addresses will be bound even if they do not belong to the
11990 local machine, and that packets targeting any of these addresses will be
11991 intercepted just as if the addresses were locally configured. This normally
11992 requires that IP forwarding is enabled. Caution! do not use this with the
11993 default address '*', as it would redirect any traffic for the specified port.
11994 This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1.
11995 This parameter is only compatible with TCPv4 and TCPv6 sockets, depending on
11996 kernel version. Some distribution kernels include backports of the feature,
11997 so check for support with your vendor.
11998
Willy Tarreau77e3af92012-11-24 15:07:23 +010011999v4v6
12000 Is an optional keyword which is supported only on most recent systems
12001 including Linux kernels >= 2.4.21. It is used to bind a socket to both IPv4
12002 and IPv6 when it uses the default address. Doing so is sometimes necessary
12003 on systems which bind to IPv6 only by default. It has no effect on non-IPv6
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012004 sockets, and is overridden by the "v6only" option.
Willy Tarreau77e3af92012-11-24 15:07:23 +010012005
Willy Tarreau9b6700f2012-11-24 11:55:28 +010012006v6only
12007 Is an optional keyword which is supported only on most recent systems
12008 including Linux kernels >= 2.4.21. It is used to bind a socket to IPv6 only
12009 when it uses the default address. Doing so is sometimes preferred to doing it
Willy Tarreau77e3af92012-11-24 15:07:23 +010012010 system-wide as it is per-listener. It has no effect on non-IPv6 sockets and
12011 has precedence over the "v4v6" option.
Willy Tarreau9b6700f2012-11-24 11:55:28 +010012012
Willy Tarreaub6205fd2012-09-24 12:27:33 +020012013uid <uid>
12014 Sets the owner of the UNIX sockets to the designated system uid. It can also
12015 be set by default in the global section's "unix-bind" statement. Note that
12016 some platforms simply ignore this. This setting is equivalent to the "user"
12017 setting except that the user numeric ID is used instead of its name. This
12018 setting is ignored by non UNIX sockets.
12019
12020user <user>
12021 Sets the owner of the UNIX sockets to the designated system user. It can also
12022 be set by default in the global section's "unix-bind" statement. Note that
12023 some platforms simply ignore this. This setting is equivalent to the "uid"
12024 setting except that the user name is used instead of its uid. This setting is
12025 ignored by non UNIX sockets.
12026
Emeric Brun1a073b42012-09-28 17:07:34 +020012027verify [none|optional|required]
12028 This setting is only available when support for OpenSSL was built in. If set
12029 to 'none', client certificate is not requested. This is the default. In other
12030 cases, a client certificate is requested. If the client does not provide a
12031 certificate after the request and if 'verify' is set to 'required', then the
12032 handshake is aborted, while it would have succeeded if set to 'optional'. The
Emeric Brunfd33a262012-10-11 16:28:27 +020012033 certificate provided by the client is always verified using CAs from
12034 'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
12035 is aborted, regardless of the 'verify' option, unless the error code exactly
12036 matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.
Willy Tarreau4a5cade2012-04-05 21:09:48 +020012037
Willy Tarreaub6205fd2012-09-24 12:27:33 +0200120385.2. Server and default-server options
Cyril Bontéf0c60612010-02-06 14:44:47 +010012039------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020012040
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010012041The "server" and "default-server" keywords support a certain number of settings
12042which are all passed as arguments on the server line. The order in which those
12043arguments appear does not count, and they are all optional. Some of those
12044settings are single words (booleans) while others expect one or several values
12045after them. In this case, the values must immediately follow the setting name.
12046Except default-server, all those settings must be specified after the server's
12047address if they are used:
Willy Tarreau6a06a402007-07-15 20:15:28 +020012048
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012049 server <name> <address>[:port] [settings ...]
Krzysztof Piotr Oledzkic6df0662010-01-05 16:38:49 +010012050 default-server [settings ...]
Willy Tarreau6a06a402007-07-15 20:15:28 +020012051
Frédéric Lécailled2376272017-03-21 18:52:12 +010012052Note that all these settings are supported both by "server" and "default-server"
12053keywords, except "id" which is only supported by "server".
12054
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012055The currently supported settings are the following ones.
Willy Tarreau0ba27502007-12-24 16:55:16 +010012056
Willy Tarreauceb4ac92012-04-28 00:41:46 +020012057addr <ipv4|ipv6>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012058 Using the "addr" parameter, it becomes possible to use a different IP address
Baptiste Assmann13f83532016-03-06 23:14:36 +010012059 to send health-checks or to probe the agent-check. On some servers, it may be
12060 desirable to dedicate an IP address to specific component able to perform
12061 complex tests which are more suitable to health-checks than the application.
12062 This parameter is ignored if the "check" parameter is not set. See also the
12063 "port" parameter.
Willy Tarreau6a06a402007-07-15 20:15:28 +020012064
Simon Hormand60d6912013-11-25 10:46:36 +090012065agent-check
12066 Enable an auxiliary agent check which is run independently of a regular
Willy Tarreau81f5d942013-12-09 20:51:51 +010012067 health check. An agent health check is performed by making a TCP connection
Willy Tarreau7a0139e2018-12-16 08:42:56 +010012068 to the port set by the "agent-port" parameter and reading an ASCII string
12069 terminated by the first '\r' or '\n' met. The string is made of a series of
12070 words delimited by spaces, tabs or commas in any order, each consisting of :
Simon Hormand60d6912013-11-25 10:46:36 +090012071
Willy Tarreau81f5d942013-12-09 20:51:51 +010012072 - An ASCII representation of a positive integer percentage, e.g. "75%".
Simon Hormand60d6912013-11-25 10:46:36 +090012073 Values in this format will set the weight proportional to the initial
Willy Tarreauc5af3a62014-10-07 15:27:33 +020012074 weight of a server as configured when haproxy starts. Note that a zero
12075 weight is reported on the stats page as "DRAIN" since it has the same
12076 effect on the server (it's removed from the LB farm).
Simon Hormand60d6912013-11-25 10:46:36 +090012077
Davor Ocelice9ed2812017-12-25 17:49:28 +010012078 - The string "maxconn:" followed by an integer (no space between). Values
12079 in this format will set the maxconn of a server. The maximum number of
12080 connections advertised needs to be multiplied by the number of load
12081 balancers and different backends that use this health check to get the
12082 total number of connections the server might receive. Example: maxconn:30
Nenad Merdanovic174dd372016-04-24 23:10:06 +020012083
Willy Tarreau81f5d942013-12-09 20:51:51 +010012084 - The word "ready". This will turn the server's administrative state to the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012085 READY mode, thus canceling any DRAIN or MAINT state
Simon Hormand60d6912013-11-25 10:46:36 +090012086
Willy Tarreau81f5d942013-12-09 20:51:51 +010012087 - The word "drain". This will turn the server's administrative state to the
12088 DRAIN mode, thus it will not accept any new connections other than those
12089 that are accepted via persistence.
Simon Hormand60d6912013-11-25 10:46:36 +090012090
Willy Tarreau81f5d942013-12-09 20:51:51 +010012091 - The word "maint". This will turn the server's administrative state to the
12092 MAINT mode, thus it will not accept any new connections at all, and health
12093 checks will be stopped.
Simon Hormand60d6912013-11-25 10:46:36 +090012094
Willy Tarreau81f5d942013-12-09 20:51:51 +010012095 - The words "down", "failed", or "stopped", optionally followed by a
12096 description string after a sharp ('#'). All of these mark the server's
12097 operating state as DOWN, but since the word itself is reported on the stats
12098 page, the difference allows an administrator to know if the situation was
12099 expected or not : the service may intentionally be stopped, may appear up
Davor Ocelice9ed2812017-12-25 17:49:28 +010012100 but fail some validity tests, or may be seen as down (e.g. missing process,
Willy Tarreau81f5d942013-12-09 20:51:51 +010012101 or port not responding).
Simon Hormand60d6912013-11-25 10:46:36 +090012102
Willy Tarreau81f5d942013-12-09 20:51:51 +010012103 - The word "up" sets back the server's operating state as UP if health checks
12104 also report that the service is accessible.
Simon Hormand60d6912013-11-25 10:46:36 +090012105
Willy Tarreau81f5d942013-12-09 20:51:51 +010012106 Parameters which are not advertised by the agent are not changed. For
12107 example, an agent might be designed to monitor CPU usage and only report a
12108 relative weight and never interact with the operating status. Similarly, an
12109 agent could be designed as an end-user interface with 3 radio buttons
12110 allowing an administrator to change only the administrative state. However,
12111 it is important to consider that only the agent may revert its own actions,
12112 so if a server is set to DRAIN mode or to DOWN state using the agent, the
12113 agent must implement the other equivalent actions to bring the service into
12114 operations again.
Simon Hormand60d6912013-11-25 10:46:36 +090012115
Simon Horman2f1f9552013-11-25 10:46:37 +090012116 Failure to connect to the agent is not considered an error as connectivity
12117 is tested by the regular health check which is enabled by the "check"
Willy Tarreau81f5d942013-12-09 20:51:51 +010012118 parameter. Warning though, it is not a good idea to stop an agent after it
12119 reports "down", since only an agent reporting "up" will be able to turn the
12120 server up again. Note that the CLI on the Unix stats socket is also able to
Willy Tarreau989222a2016-01-15 10:26:26 +010012121 force an agent's result in order to work around a bogus agent if needed.
Simon Horman2f1f9552013-11-25 10:46:37 +090012122
Willy Tarreau81f5d942013-12-09 20:51:51 +010012123 Requires the "agent-port" parameter to be set. See also the "agent-inter"
Frédéric Lécailled2376272017-03-21 18:52:12 +010012124 and "no-agent-check" parameters.
Simon Hormand60d6912013-11-25 10:46:36 +090012125
James Brown55f9ff12015-10-21 18:19:05 -070012126agent-send <string>
12127 If this option is specified, haproxy will send the given string (verbatim)
12128 to the agent server upon connection. You could, for example, encode
12129 the backend name into this string, which would enable your agent to send
12130 different responses based on the backend. Make sure to include a '\n' if
12131 you want to terminate your request with a newline.
12132
Simon Hormand60d6912013-11-25 10:46:36 +090012133agent-inter <delay>
12134 The "agent-inter" parameter sets the interval between two agent checks
12135 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
12136
12137 Just as with every other time-based parameter, it may be entered in any
12138 other explicit unit among { us, ms, s, m, h, d }. The "agent-inter"
12139 parameter also serves as a timeout for agent checks "timeout check" is
12140 not set. In order to reduce "resonance" effects when multiple servers are
12141 hosted on the same hardware, the agent and health checks of all servers
12142 are started with a small time offset between them. It is also possible to
12143 add some random noise in the agent and health checks interval using the
12144 global "spread-checks" keyword. This makes sense for instance when a lot
12145 of backends use the same servers.
12146
12147 See also the "agent-check" and "agent-port" parameters.
12148
Misiek768d8602017-01-09 09:52:43 +010012149agent-addr <addr>
12150 The "agent-addr" parameter sets address for agent check.
12151
12152 You can offload agent-check to another target, so you can make single place
12153 managing status and weights of servers defined in haproxy in case you can't
12154 make self-aware and self-managing services. You can specify both IP or
12155 hostname, it will be resolved.
12156
Simon Hormand60d6912013-11-25 10:46:36 +090012157agent-port <port>
12158 The "agent-port" parameter sets the TCP port used for agent checks.
12159
12160 See also the "agent-check" and "agent-inter" parameters.
12161
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020012162allow-0rtt
12163 Allow sending early data to the server when using TLS 1.3.
Olivier Houchard22c9b442019-05-06 19:01:04 +020012164 Note that early data will be sent only if the client used early data, or
12165 if the backend uses "retry-on" with the "0rtt-rejected" keyword.
Olivier Houchard8cb2d2e2019-05-06 18:58:48 +020012166
Olivier Houchardc7566002018-11-20 23:33:50 +010012167alpn <protocols>
12168 This enables the TLS ALPN extension and advertises the specified protocol
12169 list as supported on top of ALPN. The protocol list consists in a comma-
12170 delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
John Roesler27c754c2019-07-10 15:45:51 -050012171 quotes). This requires that the SSL library is built with support for TLS
Olivier Houchardc7566002018-11-20 23:33:50 +010012172 extensions enabled (check with haproxy -vv). The ALPN extension replaces the
12173 initial NPN extension. ALPN is required to connect to HTTP/2 servers.
12174 Versions of OpenSSL prior to 1.0.2 didn't support ALPN and only supposed the
12175 now obsolete NPN extension.
12176 If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can
12177 be advertised, in order of preference, like below :
12178
12179 server 127.0.0.1:443 ssl crt pub.pem alpn h2,http/1.1
12180
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012181backup
12182 When "backup" is present on a server line, the server is only used in load
12183 balancing when all other non-backup servers are unavailable. Requests coming
12184 with a persistence cookie referencing the server will always be served
12185 though. By default, only the first operational backup server is used, unless
Frédéric Lécailled2376272017-03-21 18:52:12 +010012186 the "allbackups" option is set in the backend. See also the "no-backup" and
12187 "allbackups" options.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012188
Emeric Brunef42d922012-10-11 16:11:36 +020012189ca-file <cafile>
12190 This setting is only available when support for OpenSSL was built in. It
12191 designates a PEM file from which to load CA certificates used to verify
12192 server's certificate.
12193
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012194check
12195 This option enables health checks on the server. By default, a server is
Patrick Mézardb7aeec62012-01-22 16:01:22 +010012196 always considered available. If "check" is set, the server is available when
12197 accepting periodic TCP connections, to ensure that it is really able to serve
12198 requests. The default address and port to send the tests to are those of the
12199 server, and the default source is the same as the one defined in the
12200 backend. It is possible to change the address using the "addr" parameter, the
12201 port using the "port" parameter, the source address using the "source"
12202 address, and the interval and timers using the "inter", "rise" and "fall"
Simon Hormanafc47ee2013-11-25 10:46:35 +090012203 parameters. The request method is define in the backend using the "httpchk",
12204 "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
Frédéric Lécailled2376272017-03-21 18:52:12 +010012205 refer to those options and parameters for more information. See also
12206 "no-check" option.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012207
Willy Tarreau6c16adc2012-10-05 00:04:16 +020012208check-send-proxy
12209 This option forces emission of a PROXY protocol line with outgoing health
12210 checks, regardless of whether the server uses send-proxy or not for the
12211 normal traffic. By default, the PROXY protocol is enabled for health checks
12212 if it is already enabled for normal traffic and if no "port" nor "addr"
12213 directive is present. However, if such a directive is present, the
12214 "check-send-proxy" option needs to be used to force the use of the
12215 protocol. See also the "send-proxy" option for more information.
12216
Olivier Houchard92150142018-12-21 19:47:01 +010012217check-alpn <protocols>
12218 Defines which protocols to advertise with ALPN. The protocol list consists in
12219 a comma-delimited list of protocol names, for instance: "http/1.1,http/1.0"
12220 (without quotes). If it is not set, the server ALPN is used.
12221
Jérôme Magninae9bb762018-12-09 16:08:26 +010012222check-sni <sni>
Olivier Houchard9130a962017-10-17 17:33:43 +020012223 This option allows you to specify the SNI to be used when doing health checks
Jérôme Magninae9bb762018-12-09 16:08:26 +010012224 over SSL. It is only possible to use a string to set <sni>. If you want to
12225 set a SNI for proxied traffic, see "sni".
Olivier Houchard9130a962017-10-17 17:33:43 +020012226
Willy Tarreau763a95b2012-10-04 23:15:39 +020012227check-ssl
12228 This option forces encryption of all health checks over SSL, regardless of
12229 whether the server uses SSL or not for the normal traffic. This is generally
12230 used when an explicit "port" or "addr" directive is specified and SSL health
12231 checks are not inherited. It is important to understand that this option
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030012232 inserts an SSL transport layer below the checks, so that a simple TCP connect
Willy Tarreau763a95b2012-10-04 23:15:39 +020012233 check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
12234 common use is to send HTTPS checks by combining "httpchk" with SSL checks.
Davor Ocelice9ed2812017-12-25 17:49:28 +010012235 All SSL settings are common to health checks and traffic (e.g. ciphers).
Frédéric Lécailled2376272017-03-21 18:52:12 +010012236 See the "ssl" option for more information and "no-check-ssl" to disable
12237 this option.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012238
Alexander Liu2a54bb72019-05-22 19:44:48 +080012239check-via-socks4
John Roesler27c754c2019-07-10 15:45:51 -050012240 This option enables outgoing health checks using upstream socks4 proxy. By
Alexander Liu2a54bb72019-05-22 19:44:48 +080012241 default, the health checks won't go through socks tunnel even it was enabled
12242 for normal traffic.
12243
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012244ciphers <ciphers>
Dirkjan Bussink415150f2018-09-14 11:14:21 +020012245 This setting is only available when support for OpenSSL was built in. This
12246 option sets the string describing the list of cipher algorithms that is
12247 negotiated during the SSL/TLS handshake with the server. The format of the
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000012248 string is defined in "man 1 ciphers" from OpenSSL man pages. For background
12249 information and recommendations see e.g.
12250 (https://wiki.mozilla.org/Security/Server_Side_TLS) and
12251 (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
12252 cipher configuration, please check the "ciphersuites" keyword.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012253
Dirkjan Bussink415150f2018-09-14 11:14:21 +020012254ciphersuites <ciphersuites>
12255 This setting is only available when support for OpenSSL was built in and
12256 OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string
12257 describing the list of cipher algorithms that is negotiated during the TLS
12258 1.3 handshake with the server. The format of the string is defined in
Bertrand Jacquin4f03ab02019-02-03 18:48:49 +000012259 "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section.
12260 For cipher configuration for TLSv1.2 and earlier, please check the "ciphers"
12261 keyword.
Dirkjan Bussink415150f2018-09-14 11:14:21 +020012262
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012263cookie <value>
12264 The "cookie" parameter sets the cookie value assigned to the server to
12265 <value>. This value will be checked in incoming requests, and the first
12266 operational server possessing the same value will be selected. In return, in
12267 cookie insertion or rewrite modes, this value will be assigned to the cookie
12268 sent to the client. There is nothing wrong in having several servers sharing
12269 the same cookie value, and it is in fact somewhat common between normal and
12270 backup servers. See also the "cookie" keyword in backend section.
12271
Emeric Brunef42d922012-10-11 16:11:36 +020012272crl-file <crlfile>
12273 This setting is only available when support for OpenSSL was built in. It
12274 designates a PEM file from which to load certificate revocation list used
12275 to verify server's certificate.
12276
Emeric Bruna7aa3092012-10-26 12:58:00 +020012277crt <cert>
12278 This setting is only available when support for OpenSSL was built in.
12279 It designates a PEM file from which to load both a certificate and the
12280 associated private key. This file can be built by concatenating both PEM
12281 files into one. This certificate will be sent if the server send a client
12282 certificate request.
12283
Willy Tarreau96839092010-03-29 10:02:24 +020012284disabled
12285 The "disabled" keyword starts the server in the "disabled" state. That means
12286 that it is marked down in maintenance mode, and no connection other than the
12287 ones allowed by persist mode will reach it. It is very well suited to setup
12288 new servers, because normal traffic will never reach them, while it is still
12289 possible to test the service by making use of the force-persist mechanism.
Frédéric Lécailled2376272017-03-21 18:52:12 +010012290 See also "enabled" setting.
Willy Tarreau96839092010-03-29 10:02:24 +020012291
Frédéric Lécailled2376272017-03-21 18:52:12 +010012292enabled
12293 This option may be used as 'server' setting to reset any 'disabled'
12294 setting which would have been inherited from 'default-server' directive as
12295 default value.
12296 It may also be used as 'default-server' setting to reset any previous
12297 'default-server' 'disabled' setting.
Willy Tarreau96839092010-03-29 10:02:24 +020012298
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012299error-limit <count>
Willy Tarreau983e01e2010-01-11 18:42:06 +010012300 If health observing is enabled, the "error-limit" parameter specifies the
12301 number of consecutive errors that triggers event selected by the "on-error"
12302 option. By default it is set to 10 consecutive errors.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010012303
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012304 See also the "check", "error-limit" and "on-error".
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010012305
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012306fall <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012307 The "fall" parameter states that a server will be considered as dead after
12308 <count> consecutive unsuccessful health checks. This value defaults to 3 if
12309 unspecified. See also the "check", "inter" and "rise" parameters.
12310
Emeric Brun8694b9a2012-10-05 14:39:07 +020012311force-sslv3
12312 This option enforces use of SSLv3 only when SSL is used to communicate with
12313 the server. SSLv3 is generally less expensive than the TLS counterparts for
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012314 high connection rates. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012315 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020012316
12317force-tlsv10
12318 This option enforces use of TLSv1.0 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012319 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012320 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020012321
12322force-tlsv11
12323 This option enforces use of TLSv1.1 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012324 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012325 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020012326
12327force-tlsv12
12328 This option enforces use of TLSv1.2 only when SSL is used to communicate with
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012329 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012330 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emeric Brun8694b9a2012-10-05 14:39:07 +020012331
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012332force-tlsv13
12333 This option enforces use of TLSv1.3 only when SSL is used to communicate with
12334 the server. This option is also available on global statement
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012335 "ssl-default-server-options". See also "ssl-min-ver" and ssl-max-ver".
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012336
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012337id <value>
Willy Tarreau53fb4ae2009-10-04 23:04:08 +020012338 Set a persistent ID for the server. This ID must be positive and unique for
12339 the proxy. An unused ID will automatically be assigned if unset. The first
12340 assigned value will be 1. This ID is currently only returned in statistics.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012341
Willy Tarreau6a031d12016-11-07 19:42:35 +010012342init-addr {last | libc | none | <ip>},[...]*
12343 Indicate in what order the server's address should be resolved upon startup
12344 if it uses an FQDN. Attempts are made to resolve the address by applying in
Davor Ocelice9ed2812017-12-25 17:49:28 +010012345 turn each of the methods mentioned in the comma-delimited list. The first
Willy Tarreau6a031d12016-11-07 19:42:35 +010012346 method which succeeds is used. If the end of the list is reached without
12347 finding a working method, an error is thrown. Method "last" suggests to pick
12348 the address which appears in the state file (see "server-state-file"). Method
12349 "libc" uses the libc's internal resolver (gethostbyname() or getaddrinfo()
12350 depending on the operating system and build options). Method "none"
12351 specifically indicates that the server should start without any valid IP
12352 address in a down state. It can be useful to ignore some DNS issues upon
12353 startup, waiting for the situation to get fixed later. Finally, an IP address
12354 (IPv4 or IPv6) may be provided. It can be the currently known address of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012355 server (e.g. filled by a configuration generator), or the address of a dummy
Willy Tarreau6a031d12016-11-07 19:42:35 +010012356 server used to catch old sessions and present them with a decent error
12357 message for example. When the "first" load balancing algorithm is used, this
12358 IP address could point to a fake server used to trigger the creation of new
12359 instances on the fly. This option defaults to "last,libc" indicating that the
12360 previous address found in the state file (if any) is used first, otherwise
12361 the libc's resolver is used. This ensures continued compatibility with the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012362 historic behavior.
Willy Tarreau6a031d12016-11-07 19:42:35 +010012363
12364 Example:
12365 defaults
12366 # never fail on address resolution
12367 default-server init-addr last,libc,none
12368
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012369inter <delay>
12370fastinter <delay>
12371downinter <delay>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012372 The "inter" parameter sets the interval between two consecutive health checks
12373 to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
12374 It is also possible to use "fastinter" and "downinter" to optimize delays
12375 between checks depending on the server state :
12376
Pieter Baauw44fc9df2015-09-17 21:30:46 +020012377 Server state | Interval used
12378 ----------------------------------------+----------------------------------
12379 UP 100% (non-transitional) | "inter"
12380 ----------------------------------------+----------------------------------
12381 Transitionally UP (going down "fall"), | "fastinter" if set,
12382 Transitionally DOWN (going up "rise"), | "inter" otherwise.
12383 or yet unchecked. |
12384 ----------------------------------------+----------------------------------
12385 DOWN 100% (non-transitional) | "downinter" if set,
12386 | "inter" otherwise.
12387 ----------------------------------------+----------------------------------
Willy Tarreaud72758d2010-01-12 10:42:19 +010012388
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012389 Just as with every other time-based parameter, they can be entered in any
12390 other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also
12391 serves as a timeout for health checks sent to servers if "timeout check" is
12392 not set. In order to reduce "resonance" effects when multiple servers are
Simon Hormand60d6912013-11-25 10:46:36 +090012393 hosted on the same hardware, the agent and health checks of all servers
12394 are started with a small time offset between them. It is also possible to
12395 add some random noise in the agent and health checks interval using the
12396 global "spread-checks" keyword. This makes sense for instance when a lot
12397 of backends use the same servers.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012398
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012399maxconn <maxconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012400 The "maxconn" parameter specifies the maximal number of concurrent
12401 connections that will be sent to this server. If the number of incoming
Tim Duesterhus50cfb312019-11-27 22:35:27 +010012402 concurrent connections goes higher than this value, they will be queued,
12403 waiting for a slot to be released. This parameter is very important as it can
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012404 save fragile servers from going down under extreme loads. If a "minconn"
12405 parameter is specified, the limit becomes dynamic. The default value is "0"
12406 which means unlimited. See also the "minconn" and "maxqueue" parameters, and
12407 the backend's "fullconn" keyword.
12408
Tim Duesterhus50cfb312019-11-27 22:35:27 +010012409 In HTTP mode this parameter limits the number of concurrent requests instead
12410 of the number of connections. Multiple requests might be multiplexed over a
12411 single TCP connection to the server. As an example if you specify a maxconn
12412 of 50 you might see between 1 and 50 actual server connections, but no more
12413 than 50 concurrent requests.
12414
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012415maxqueue <maxqueue>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012416 The "maxqueue" parameter specifies the maximal number of connections which
12417 will wait in the queue for this server. If this limit is reached, next
12418 requests will be redispatched to other servers instead of indefinitely
12419 waiting to be served. This will break persistence but may allow people to
12420 quickly re-log in when the server they try to connect to is dying. The
12421 default value is "0" which means the queue is unlimited. See also the
12422 "maxconn" and "minconn" parameters.
12423
Willy Tarreau9c538e02019-01-23 10:21:49 +010012424max-reuse <count>
12425 The "max-reuse" argument indicates the HTTP connection processors that they
12426 should not reuse a server connection more than this number of times to send
12427 new requests. Permitted values are -1 (the default), which disables this
12428 limit, or any positive value. Value zero will effectively disable keep-alive.
12429 This is only used to work around certain server bugs which cause them to leak
12430 resources over time. The argument is not necessarily respected by the lower
12431 layers as there might be technical limitations making it impossible to
12432 enforce. At least HTTP/2 connections to servers will respect it.
12433
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012434minconn <minconn>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012435 When the "minconn" parameter is set, the maxconn limit becomes a dynamic
12436 limit following the backend's load. The server will always accept at least
12437 <minconn> connections, never more than <maxconn>, and the limit will be on
12438 the ramp between both values when the backend has less than <fullconn>
12439 concurrent connections. This makes it possible to limit the load on the
12440 server during normal loads, but push it further for important loads without
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012441 overloading the server during exceptional loads. See also the "maxconn"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012442 and "maxqueue" parameters, as well as the "fullconn" backend keyword.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010012443
Willy Tarreaud72f0f32015-10-13 14:50:22 +020012444namespace <name>
12445 On Linux, it is possible to specify which network namespace a socket will
12446 belong to. This directive makes it possible to explicitly bind a server to
12447 a namespace different from the default one. Please refer to your operating
12448 system's documentation to find more details about network namespaces.
12449
Frédéric Lécailled2376272017-03-21 18:52:12 +010012450no-agent-check
12451 This option may be used as "server" setting to reset any "agent-check"
12452 setting which would have been inherited from "default-server" directive as
12453 default value.
12454 It may also be used as "default-server" setting to reset any previous
12455 "default-server" "agent-check" setting.
12456
12457no-backup
12458 This option may be used as "server" setting to reset any "backup"
12459 setting which would have been inherited from "default-server" directive as
12460 default value.
12461 It may also be used as "default-server" setting to reset any previous
12462 "default-server" "backup" setting.
12463
12464no-check
12465 This option may be used as "server" setting to reset any "check"
12466 setting which would have been inherited from "default-server" directive as
12467 default value.
12468 It may also be used as "default-server" setting to reset any previous
12469 "default-server" "check" setting.
12470
12471no-check-ssl
12472 This option may be used as "server" setting to reset any "check-ssl"
12473 setting which would have been inherited from "default-server" directive as
12474 default value.
12475 It may also be used as "default-server" setting to reset any previous
12476 "default-server" "check-ssl" setting.
12477
Frédéric Lécailled2376272017-03-21 18:52:12 +010012478no-send-proxy
12479 This option may be used as "server" setting to reset any "send-proxy"
12480 setting which would have been inherited from "default-server" directive as
12481 default value.
12482 It may also be used as "default-server" setting to reset any previous
12483 "default-server" "send-proxy" setting.
12484
12485no-send-proxy-v2
12486 This option may be used as "server" setting to reset any "send-proxy-v2"
12487 setting which would have been inherited from "default-server" directive as
12488 default value.
12489 It may also be used as "default-server" setting to reset any previous
12490 "default-server" "send-proxy-v2" setting.
12491
12492no-send-proxy-v2-ssl
12493 This option may be used as "server" setting to reset any "send-proxy-v2-ssl"
12494 setting which would have been inherited from "default-server" directive as
12495 default value.
12496 It may also be used as "default-server" setting to reset any previous
12497 "default-server" "send-proxy-v2-ssl" setting.
12498
12499no-send-proxy-v2-ssl-cn
12500 This option may be used as "server" setting to reset any "send-proxy-v2-ssl-cn"
12501 setting which would have been inherited from "default-server" directive as
12502 default value.
12503 It may also be used as "default-server" setting to reset any previous
12504 "default-server" "send-proxy-v2-ssl-cn" setting.
12505
12506no-ssl
12507 This option may be used as "server" setting to reset any "ssl"
12508 setting which would have been inherited from "default-server" directive as
12509 default value.
12510 It may also be used as "default-server" setting to reset any previous
12511 "default-server" "ssl" setting.
12512
Willy Tarreau2a3fb1c2015-02-05 16:47:07 +010012513no-ssl-reuse
12514 This option disables SSL session reuse when SSL is used to communicate with
12515 the server. It will force the server to perform a full handshake for every
12516 new connection. It's probably only useful for benchmarking, troubleshooting,
12517 and for paranoid users.
12518
Emeric Brun9b3009b2012-10-05 11:55:06 +020012519no-sslv3
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012520 This option disables support for SSLv3 when SSL is used to communicate with
12521 the server. Note that SSLv2 is disabled in the code and cannot be enabled
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012522 using any configuration option. Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012523
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020012524 Supported in default-server: No
12525
Emeric Brunf9c5c472012-10-11 15:28:34 +020012526no-tls-tickets
12527 This setting is only available when support for OpenSSL was built in. It
12528 disables the stateless session resumption (RFC 5077 TLS Ticket
12529 extension) and force to use stateful session resumption. Stateless
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012530 session resumption is more expensive in CPU usage for servers. This option
12531 is also available on global statement "ssl-default-server-options".
Lukas Tribusd8fd6362020-03-10 00:56:09 +010012532 The TLS ticket mechanism is only used up to TLS 1.2.
12533 Forward Secrecy is compromised with TLS tickets, unless ticket keys
12534 are periodically rotated (via reload or by using "tls-ticket-keys").
Frédéric Lécailled2376272017-03-21 18:52:12 +010012535 See also "tls-tickets".
Emeric Brunf9c5c472012-10-11 15:28:34 +020012536
Emeric Brun9b3009b2012-10-05 11:55:06 +020012537no-tlsv10
Emeric Brun8694b9a2012-10-05 14:39:07 +020012538 This option disables support for TLSv1.0 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020012539 the server. Note that SSLv2 is disabled in the code and cannot be enabled
12540 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012541 often makes sense to disable it when communicating with local servers. This
12542 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012543 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012544
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020012545 Supported in default-server: No
12546
Emeric Brun9b3009b2012-10-05 11:55:06 +020012547no-tlsv11
Emeric Brun8694b9a2012-10-05 14:39:07 +020012548 This option disables support for TLSv1.1 when SSL is used to communicate with
Emeric Brunf5da4932012-09-28 19:42:54 +020012549 the server. Note that SSLv2 is disabled in the code and cannot be enabled
12550 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012551 often makes sense to disable it when communicating with local servers. This
12552 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012553 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012554
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020012555 Supported in default-server: No
12556
Emeric Brun9b3009b2012-10-05 11:55:06 +020012557no-tlsv12
Emeric Brun8694b9a2012-10-05 14:39:07 +020012558 This option disables support for TLSv1.2 when SSL is used to communicate with
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012559 the server. Note that SSLv2 is disabled in the code and cannot be enabled
12560 using any configuration option. TLSv1 is more expensive than SSLv3 so it
Emeric Brun2c86cbf2014-10-30 15:56:50 +010012561 often makes sense to disable it when communicating with local servers. This
12562 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012563 Use "ssl-min-ver" and "ssl-max-ver" instead.
Emmanuel Hocdet42fb9802017-03-30 19:29:39 +020012564
12565 Supported in default-server: No
12566
12567no-tlsv13
12568 This option disables support for TLSv1.3 when SSL is used to communicate with
12569 the server. Note that SSLv2 is disabled in the code and cannot be enabled
12570 using any configuration option. TLSv1 is more expensive than SSLv3 so it
12571 often makes sense to disable it when communicating with local servers. This
12572 option is also available on global statement "ssl-default-server-options".
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012573 Use "ssl-min-ver" and "ssl-max-ver" instead.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012574
Emmanuel Hocdet6cb2d1e2017-03-30 14:43:31 +020012575 Supported in default-server: No
12576
Frédéric Lécailled2376272017-03-21 18:52:12 +010012577no-verifyhost
12578 This option may be used as "server" setting to reset any "verifyhost"
12579 setting which would have been inherited from "default-server" directive as
12580 default value.
12581 It may also be used as "default-server" setting to reset any previous
12582 "default-server" "verifyhost" setting.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012583
Frédéric Lécailleaeeb1c92019-07-04 14:19:06 +020012584no-tfo
12585 This option may be used as "server" setting to reset any "tfo"
12586 setting which would have been inherited from "default-server" directive as
12587 default value.
12588 It may also be used as "default-server" setting to reset any previous
12589 "default-server" "tfo" setting.
12590
Simon Hormanfa461682011-06-25 09:39:49 +090012591non-stick
12592 Never add connections allocated to this sever to a stick-table.
12593 This may be used in conjunction with backup to ensure that
12594 stick-table persistence is disabled for backup servers.
12595
Olivier Houchardc7566002018-11-20 23:33:50 +010012596npn <protocols>
12597 This enables the NPN TLS extension and advertises the specified protocol list
12598 as supported on top of NPN. The protocol list consists in a comma-delimited
12599 list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
John Roesler27c754c2019-07-10 15:45:51 -050012600 This requires that the SSL library is built with support for TLS extensions
Olivier Houchardc7566002018-11-20 23:33:50 +010012601 enabled (check with haproxy -vv). Note that the NPN extension has been
12602 replaced with the ALPN extension (see the "alpn" keyword), though this one is
12603 only available starting with OpenSSL 1.0.2.
12604
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010012605observe <mode>
12606 This option enables health adjusting based on observing communication with
12607 the server. By default this functionality is disabled and enabling it also
12608 requires to enable health checks. There are two supported modes: "layer4" and
12609 "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
12610 significant. In layer7, which is only allowed for http proxies, responses
12611 received from server are verified, like valid/wrong http code, unparsable
Willy Tarreau150d1462012-03-10 08:19:02 +010012612 headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010012613
12614 See also the "check", "on-error" and "error-limit".
12615
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012616on-error <mode>
Krzysztof Piotr Oledzki97f07b82009-12-15 22:31:24 +010012617 Select what should happen when enough consecutive errors are detected.
12618 Currently, four modes are available:
12619 - fastinter: force fastinter
12620 - fail-check: simulate a failed check, also forces fastinter (default)
12621 - sudden-death: simulate a pre-fatal failed health check, one more failed
12622 check will mark a server down, forces fastinter
12623 - mark-down: mark the server immediately down and force fastinter
12624
12625 See also the "check", "observe" and "error-limit".
12626
Simon Hormane0d1bfb2011-06-21 14:34:58 +090012627on-marked-down <action>
12628 Modify what occurs when a server is marked down.
12629 Currently one action is available:
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070012630 - shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
12631 all connections to the server are immediately terminated when the server
12632 goes down. It might be used if the health check detects more complex cases
12633 than a simple connection status, and long timeouts would cause the service
12634 to remain unresponsive for too long a time. For instance, a health check
12635 might detect that a database is stuck and that there's no chance to reuse
12636 existing connections anymore. Connections killed this way are logged with
12637 a 'D' termination code (for "Down").
Simon Hormane0d1bfb2011-06-21 14:34:58 +090012638
12639 Actions are disabled by default
12640
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070012641on-marked-up <action>
12642 Modify what occurs when a server is marked up.
12643 Currently one action is available:
12644 - shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
12645 done only if the server is not in backup state and if it is not disabled
12646 (it must have an effective weight > 0). This can be used sometimes to force
12647 an active server to take all the traffic back after recovery when dealing
Davor Ocelice9ed2812017-12-25 17:49:28 +010012648 with long sessions (e.g. LDAP, SQL, ...). Doing this can cause more trouble
12649 than it tries to solve (e.g. incomplete transactions), so use this feature
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070012650 with extreme care. Sessions killed because a server comes up are logged
12651 with an 'U' termination code (for "Up").
12652
12653 Actions are disabled by default
12654
Olivier Houchard006e3102018-12-10 18:30:32 +010012655pool-max-conn <max>
12656 Set the maximum number of idling connections for a server. -1 means unlimited
12657 connections, 0 means no idle connections. The default is -1. When idle
12658 connections are enabled, orphaned idle connections which do not belong to any
12659 client session anymore are moved to a dedicated pool so that they remain
12660 usable by future clients. This only applies to connections that can be shared
12661 according to the same principles as those applying to "http-reuse".
12662
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010012663pool-purge-delay <delay>
12664 Sets the delay to start purging idle connections. Each <delay> interval, half
Olivier Houcharda56eebf2019-03-19 16:44:02 +010012665 of the idle connections are closed. 0 means we don't keep any idle connection.
Willy Tarreaufb553652019-06-04 14:06:31 +020012666 The default is 5s.
Olivier Houchardb7b3faa2018-12-14 18:15:36 +010012667
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012668port <port>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012669 Using the "port" parameter, it becomes possible to use a different port to
12670 send health-checks. On some servers, it may be desirable to dedicate a port
12671 to a specific component able to perform complex tests which are more suitable
12672 to health-checks than the application. It is common to run a simple script in
12673 inetd for instance. This parameter is ignored if the "check" parameter is not
12674 set. See also the "addr" parameter.
12675
Christopher Faulet8ed0a3e2018-04-10 14:45:45 +020012676proto <name>
12677
12678 Forces the multiplexer's protocol to use for the outgoing connections to this
12679 server. It must be compatible with the mode of the backend (TCP or HTTP). It
12680 must also be usable on the backend side. The list of available protocols is
12681 reported in haproxy -vv.
12682 Idea behind this optipon is to bypass the selection of the best multiplexer's
12683 protocol for all connections established to this server.
12684
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012685redir <prefix>
12686 The "redir" parameter enables the redirection mode for all GET and HEAD
12687 requests addressing this server. This means that instead of having HAProxy
12688 forward the request to the server, it will send an "HTTP 302" response with
12689 the "Location" header composed of this prefix immediately followed by the
12690 requested URI beginning at the leading '/' of the path component. That means
12691 that no trailing slash should be used after <prefix>. All invalid requests
12692 will be rejected, and all non-GET or HEAD requests will be normally served by
12693 the server. Note that since the response is completely forged, no header
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010012694 mangling nor cookie insertion is possible in the response. However, cookies in
Davor Ocelice9ed2812017-12-25 17:49:28 +010012695 requests are still analyzed, making this solution completely usable to direct
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012696 users to a remote location in case of local disaster. Main use consists in
12697 increasing bandwidth for static servers by having the clients directly
12698 connect to them. Note: never use a relative location here, it would cause a
12699 loop between the client and HAProxy!
12700
12701 Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check
12702
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012703rise <count>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012704 The "rise" parameter states that a server will be considered as operational
12705 after <count> consecutive successful health checks. This value defaults to 2
12706 if unspecified. See also the "check", "inter" and "fall" parameters.
12707
Baptiste Assmann8e2d9432018-06-22 15:04:43 +020012708resolve-opts <option>,<option>,...
12709 Comma separated list of options to apply to DNS resolution linked to this
12710 server.
12711
12712 Available options:
12713
12714 * allow-dup-ip
12715 By default, HAProxy prevents IP address duplication in a backend when DNS
12716 resolution at runtime is in operation.
12717 That said, for some cases, it makes sense that two servers (in the same
12718 backend, being resolved by the same FQDN) have the same IP address.
12719 For such case, simply enable this option.
12720 This is the opposite of prevent-dup-ip.
12721
12722 * prevent-dup-ip
12723 Ensure HAProxy's default behavior is enforced on a server: prevent re-using
12724 an IP address already set to a server in the same backend and sharing the
12725 same fqdn.
12726 This is the opposite of allow-dup-ip.
12727
12728 Example:
12729 backend b_myapp
12730 default-server init-addr none resolvers dns
12731 server s1 myapp.example.com:80 check resolve-opts allow-dup-ip
12732 server s2 myapp.example.com:81 check resolve-opts allow-dup-ip
12733
12734 With the option allow-dup-ip set:
12735 * if the nameserver returns a single IP address, then both servers will use
12736 it
12737 * If the nameserver returns 2 IP addresses, then each server will pick up a
12738 different address
12739
12740 Default value: not set
12741
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012742resolve-prefer <family>
12743 When DNS resolution is enabled for a server and multiple IP addresses from
12744 different families are returned, HAProxy will prefer using an IP address
12745 from the family mentioned in the "resolve-prefer" parameter.
12746 Available families: "ipv4" and "ipv6"
12747
Baptiste Assmannc4aabae2015-08-04 22:43:06 +020012748 Default value: ipv6
12749
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012750 Example:
12751
12752 server s1 app1.domain.com:80 resolvers mydns resolve-prefer ipv6
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012753
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012754resolve-net <network>[,<network[,...]]
John Roesler27c754c2019-07-10 15:45:51 -050012755 This option prioritizes the choice of an ip address matching a network. This is
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012756 useful with clouds to prefer a local ip. In some cases, a cloud high
Tim Düsterhus4896c442016-11-29 02:15:19 +010012757 availability service can be announced with many ip addresses on many
Davor Ocelice9ed2812017-12-25 17:49:28 +010012758 different datacenters. The latency between datacenter is not negligible, so
12759 this patch permits to prefer a local datacenter. If no address matches the
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012760 configured network, another address is selected.
12761
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012762 Example:
12763
12764 server s1 app1.domain.com:80 resolvers mydns resolve-net 10.0.0.0/8
Thierry Fournierac88cfe2016-02-17 22:05:30 +010012765
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012766resolvers <id>
12767 Points to an existing "resolvers" section to resolve current server's
12768 hostname.
12769
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012770 Example:
12771
12772 server s1 app1.domain.com:80 check resolvers mydns
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012773
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020012774 See also section 5.3
Baptiste Assmann1fa66662015-04-14 00:28:47 +020012775
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010012776send-proxy
12777 The "send-proxy" parameter enforces use of the PROXY protocol over any
12778 connection established to this server. The PROXY protocol informs the other
12779 end about the layer 3/4 addresses of the incoming connection, so that it can
12780 know the client's address or the public address it accessed to, whatever the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010012781 upper layer protocol. For connections accepted by an "accept-proxy" or
12782 "accept-netscaler-cip" listener, the advertised address will be used. Only
12783 TCPv4 and TCPv6 address families are supported. Other families such as
12784 Unix sockets, will report an UNKNOWN family. Servers using this option can
12785 fully be chained to another instance of haproxy listening with an
12786 "accept-proxy" setting. This setting must not be used if the server isn't
12787 aware of the protocol. When health checks are sent to the server, the PROXY
12788 protocol is automatically used when this option is set, unless there is an
12789 explicit "port" or "addr" directive, in which case an explicit
12790 "check-send-proxy" directive would also be needed to use the PROXY protocol.
Frédéric Lécailled2376272017-03-21 18:52:12 +010012791 See also the "no-send-proxy" option of this section and "accept-proxy" and
12792 "accept-netscaler-cip" option of the "bind" keyword.
Willy Tarreau5ab04ec2011-03-20 10:32:26 +010012793
David Safb76832014-05-08 23:42:08 -040012794send-proxy-v2
12795 The "send-proxy-v2" parameter enforces use of the PROXY protocol version 2
12796 over any connection established to this server. The PROXY protocol informs
12797 the other end about the layer 3/4 addresses of the incoming connection, so
12798 that it can know the client's address or the public address it accessed to,
Emmanuel Hocdet404d9782017-10-24 10:55:14 +020012799 whatever the upper layer protocol. It also send ALPN information if an alpn
12800 have been negotiated. This setting must not be used if the server isn't aware
12801 of this version of the protocol. See also the "no-send-proxy-v2" option of
12802 this section and send-proxy" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040012803
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010012804proxy-v2-options <option>[,<option>]*
12805 The "proxy-v2-options" parameter add option to send in PROXY protocol version
12806 2 when "send-proxy-v2" is used. Options available are "ssl" (see also
Emmanuel Hocdetfa8d0f12018-02-01 15:53:52 +010012807 send-proxy-v2-ssl), "cert-cn" (see also "send-proxy-v2-ssl-cn"), "ssl-cipher":
12808 name of the used cipher, "cert-sig": signature algorithm of the used
Emmanuel Hocdet253c3b72018-02-01 18:29:59 +010012809 certificate, "cert-key": key algorithm of the used certificate), "authority":
12810 host name value passed by the client (only sni from a tls connection is
Emmanuel Hocdet4399c752018-02-05 15:26:43 +010012811 supported), "crc32c": checksum of the proxy protocol v2 header.
Emmanuel Hocdetf643b802018-02-01 15:20:32 +010012812
David Safb76832014-05-08 23:42:08 -040012813send-proxy-v2-ssl
12814 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
12815 2 over any connection established to this server. The PROXY protocol informs
12816 the other end about the layer 3/4 addresses of the incoming connection, so
12817 that it can know the client's address or the public address it accessed to,
12818 whatever the upper layer protocol. In addition, the SSL information extension
12819 of the PROXY protocol is added to the PROXY protocol header. This setting
12820 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 +010012821 See also the "no-send-proxy-v2-ssl" option of this section and the
12822 "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040012823
12824send-proxy-v2-ssl-cn
12825 The "send-proxy-v2-ssl" parameter enforces use of the PROXY protocol version
12826 2 over any connection established to this server. The PROXY protocol informs
12827 the other end about the layer 3/4 addresses of the incoming connection, so
12828 that it can know the client's address or the public address it accessed to,
12829 whatever the upper layer protocol. In addition, the SSL information extension
12830 of the PROXY protocol, along along with the Common Name from the subject of
12831 the client certificate (if any), is added to the PROXY protocol header. This
12832 setting must not be used if the server isn't aware of this version of the
Davor Ocelice9ed2812017-12-25 17:49:28 +010012833 protocol. See also the "no-send-proxy-v2-ssl-cn" option of this section and
12834 the "send-proxy-v2" option of the "bind" keyword.
David Safb76832014-05-08 23:42:08 -040012835
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012836slowstart <start_time_in_ms>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012837 The "slowstart" parameter for a server accepts a value in milliseconds which
12838 indicates after how long a server which has just come back up will run at
12839 full speed. Just as with every other time-based parameter, it can be entered
12840 in any other explicit unit among { us, ms, s, m, h, d }. The speed grows
12841 linearly from 0 to 100% during this time. The limitation applies to two
12842 parameters :
12843
12844 - maxconn: the number of connections accepted by the server will grow from 1
12845 to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn).
12846
12847 - weight: when the backend uses a dynamic weighted algorithm, the weight
12848 grows linearly from 1 to 100%. In this case, the weight is updated at every
12849 health-check. For this reason, it is important that the "inter" parameter
12850 is smaller than the "slowstart", in order to maximize the number of steps.
12851
12852 The slowstart never applies when haproxy starts, otherwise it would cause
12853 trouble to running servers. It only applies when a server has been previously
12854 seen as failed.
12855
Willy Tarreau732eac42015-07-09 11:40:25 +020012856sni <expression>
12857 The "sni" parameter evaluates the sample fetch expression, converts it to a
12858 string and uses the result as the host name sent in the SNI TLS extension to
12859 the server. A typical use case is to send the SNI received from the client in
12860 a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
Willy Tarreau2ab88672017-07-05 18:23:03 +020012861 expression, though alternatives such as req.hdr(host) can also make sense. If
12862 "verify required" is set (which is the recommended setting), the resulting
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012863 name will also be matched against the server certificate's names. See the
Jérôme Magninb36a6d22018-12-09 16:03:40 +010012864 "verify" directive for more details. If you want to set a SNI for health
12865 checks, see the "check-sni" directive for more details.
Willy Tarreau732eac42015-07-09 11:40:25 +020012866
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012867source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
Willy Tarreaubce70882009-09-07 11:51:47 +020012868source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ]
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012869source <addr>[:<pl>[-<ph>]] [interface <name>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012870 The "source" parameter sets the source address which will be used when
12871 connecting to the server. It follows the exact same parameters and principle
12872 as the backend "source" keyword, except that it only applies to the server
12873 referencing it. Please consult the "source" keyword for details.
12874
Willy Tarreauc6f4ce82009-06-10 11:09:37 +020012875 Additionally, the "source" statement on a server line allows one to specify a
12876 source port range by indicating the lower and higher bounds delimited by a
12877 dash ('-'). Some operating systems might require a valid IP address when a
12878 source port range is specified. It is permitted to have the same IP/range for
12879 several servers. Doing so makes it possible to bypass the maximum of 64k
12880 total concurrent connections. The limit will then reach 64k connections per
12881 server.
12882
Lukas Tribus7d56c6d2016-09-13 09:51:15 +000012883 Since Linux 4.2/libc 2.23 IP_BIND_ADDRESS_NO_PORT is set for connections
12884 specifying the source address without port(s).
12885
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012886ssl
Willy Tarreau44f65392013-06-25 07:56:20 +020012887 This option enables SSL ciphering on outgoing connections to the server. It
12888 is critical to verify server certificates using "verify" when using SSL to
12889 connect to servers, otherwise the communication is prone to trivial man in
12890 the-middle attacks rendering SSL useless. When this option is used, health
12891 checks are automatically sent in SSL too unless there is a "port" or an
12892 "addr" directive indicating the check should be sent to a different location.
Frédéric Lécailled2376272017-03-21 18:52:12 +010012893 See the "no-ssl" to disable "ssl" option and "check-ssl" option to force
12894 SSL health checks.
Willy Tarreau763a95b2012-10-04 23:15:39 +020012895
Emmanuel Hocdete1c722b2017-03-31 15:02:54 +020012896ssl-max-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12897 This option enforces use of <version> or lower when SSL is used to communicate
12898 with the server. This option is also available on global statement
12899 "ssl-default-server-options". See also "ssl-min-ver".
12900
12901ssl-min-ver [ SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3 ]
12902 This option enforces use of <version> or upper when SSL is used to communicate
12903 with the server. This option is also available on global statement
12904 "ssl-default-server-options". See also "ssl-max-ver".
12905
Frédéric Lécailled2376272017-03-21 18:52:12 +010012906ssl-reuse
12907 This option may be used as "server" setting to reset any "no-ssl-reuse"
12908 setting which would have been inherited from "default-server" directive as
12909 default value.
12910 It may also be used as "default-server" setting to reset any previous
12911 "default-server" "no-ssl-reuse" setting.
12912
12913stick
12914 This option may be used as "server" setting to reset any "non-stick"
12915 setting which would have been inherited from "default-server" directive as
12916 default value.
12917 It may also be used as "default-server" setting to reset any previous
12918 "default-server" "non-stick" setting.
Willy Tarreaua0ee1d02012-09-10 09:01:23 +020012919
Alexander Liu2a54bb72019-05-22 19:44:48 +080012920socks4 <addr>:<port>
John Roesler27c754c2019-07-10 15:45:51 -050012921 This option enables upstream socks4 tunnel for outgoing connections to the
Alexander Liu2a54bb72019-05-22 19:44:48 +080012922 server. Using this option won't force the health check to go via socks4 by
12923 default. You will have to use the keyword "check-via-socks4" to enable it.
12924
Willy Tarreau163d4622015-10-13 16:16:41 +020012925tcp-ut <delay>
12926 Sets the TCP User Timeout for all outgoing connections to this server. This
12927 option is available on Linux since version 2.6.37. It allows haproxy to
12928 configure a timeout for sockets which contain data not receiving an
Davor Ocelice9ed2812017-12-25 17:49:28 +010012929 acknowledgment for the configured delay. This is especially useful on
Willy Tarreau163d4622015-10-13 16:16:41 +020012930 long-lived connections experiencing long idle periods such as remote
12931 terminals or database connection pools, where the client and server timeouts
12932 must remain high to allow a long period of idle, but where it is important to
12933 detect that the server has disappeared in order to release all resources
12934 associated with its connection (and the client's session). One typical use
12935 case is also to force dead server connections to die when health checks are
12936 too slow or during a soft reload since health checks are then disabled. The
12937 argument is a delay expressed in milliseconds by default. This only works for
12938 regular TCP connections, and is ignored for other protocols.
12939
Willy Tarreau034c88c2017-01-23 23:36:45 +010012940tfo
12941 This option enables using TCP fast open when connecting to servers, on
12942 systems that support it (currently only the Linux kernel >= 4.11).
12943 See the "tfo" bind option for more information about TCP fast open.
12944 Please note that when using tfo, you should also use the "conn-failure",
12945 "empty-response" and "response-timeout" keywords for "retry-on", or haproxy
Frédéric Lécailleaeeb1c92019-07-04 14:19:06 +020012946 won't be able to retry the connection on failure. See also "no-tfo".
Willy Tarreau034c88c2017-01-23 23:36:45 +010012947
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012948track [<proxy>/]<server>
Willy Tarreau32091232014-05-16 13:52:00 +020012949 This option enables ability to set the current state of the server by tracking
12950 another one. It is possible to track a server which itself tracks another
12951 server, provided that at the end of the chain, a server has health checks
12952 enabled. If <proxy> is omitted the current one is used. If disable-on-404 is
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012953 used, it has to be enabled on both proxies.
12954
Frédéric Lécailled2376272017-03-21 18:52:12 +010012955tls-tickets
12956 This option may be used as "server" setting to reset any "no-tls-tickets"
12957 setting which would have been inherited from "default-server" directive as
12958 default value.
Lukas Tribusd8fd6362020-03-10 00:56:09 +010012959 The TLS ticket mechanism is only used up to TLS 1.2.
12960 Forward Secrecy is compromised with TLS tickets, unless ticket keys
12961 are periodically rotated (via reload or by using "tls-ticket-keys").
Frédéric Lécailled2376272017-03-21 18:52:12 +010012962 It may also be used as "default-server" setting to reset any previous
Bjoern Jacke04037d32020-02-13 14:16:16 +010012963 "default-server" "no-tls-tickets" setting.
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012964
Emeric Brunef42d922012-10-11 16:11:36 +020012965verify [none|required]
12966 This setting is only available when support for OpenSSL was built in. If set
Emeric Brun850efd52014-01-29 12:24:34 +010012967 to 'none', server certificate is not verified. In the other case, The
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012968 certificate provided by the server is verified using CAs from 'ca-file' and
12969 optional CRLs from 'crl-file' after having checked that the names provided in
Davor Ocelice9ed2812017-12-25 17:49:28 +010012970 the certificate's subject and subjectAlternateNames attributes match either
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012971 the name passed using the "sni" directive, or if not provided, the static
12972 host name passed using the "verifyhost" directive. When no name is found, the
12973 certificate's names are ignored. For this reason, without SNI it's important
12974 to use "verifyhost". On verification failure the handshake is aborted. It is
12975 critically important to verify server certificates when using SSL to connect
12976 to servers, otherwise the communication is prone to trivial man-in-the-middle
12977 attacks rendering SSL totally useless. Unless "ssl_server_verify" appears in
12978 the global section, "verify" is set to "required" by default.
Emeric Brunef42d922012-10-11 16:11:36 +020012979
Evan Broderbe554312013-06-27 00:05:25 -070012980verifyhost <hostname>
12981 This setting is only available when support for OpenSSL was built in, and
Willy Tarreauad92a9a2017-07-28 11:38:41 +020012982 only takes effect if 'verify required' is also specified. This directive sets
12983 a default static hostname to check the server's certificate against when no
12984 SNI was used to connect to the server. If SNI is not used, this is the only
12985 way to enable hostname verification. This static hostname, when set, will
12986 also be used for health checks (which cannot provide an SNI value). If none
12987 of the hostnames in the certificate match the specified hostname, the
12988 handshake is aborted. The hostnames in the server-provided certificate may
12989 include wildcards. See also "verify", "sni" and "no-verifyhost" options.
Evan Broderbe554312013-06-27 00:05:25 -070012990
Krzysztof Piotr Oledzkic53601c2010-01-06 10:50:42 +010012991weight <weight>
Willy Tarreauc57f0e22009-05-10 13:12:33 +020012992 The "weight" parameter is used to adjust the server's weight relative to
12993 other servers. All servers will receive a load proportional to their weight
12994 relative to the sum of all weights, so the higher the weight, the higher the
Willy Tarreau6704d672009-06-15 10:56:05 +020012995 load. The default weight is 1, and the maximal value is 256. A value of 0
12996 means the server will not participate in load-balancing but will still accept
12997 persistent connections. If this parameter is used to distribute the load
12998 according to server's capacity, it is recommended to start with values which
12999 can both grow and shrink, for instance between 10 and 100 to leave enough
13000 room above and below for later adjustments.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013001
13002
Cyril Bonté46175dd2015-07-02 22:45:32 +0200130035.3. Server IP address resolution using DNS
13004-------------------------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013005
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013006HAProxy allows using a host name on the server line to retrieve its IP address
13007using name servers. By default, HAProxy resolves the name when parsing the
13008configuration file, at startup and cache the result for the process' life.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013009This is not sufficient in some cases, such as in Amazon where a server's IP
13010can change after a reboot or an ELB Virtual IP can change based on current
13011workload.
13012This chapter describes how HAProxy can be configured to process server's name
13013resolution at run time.
13014Whether run time server name resolution has been enable or not, HAProxy will
13015carry on doing the first resolution when parsing the configuration.
13016
13017
Cyril Bonté46175dd2015-07-02 22:45:32 +0200130185.3.1. Global overview
13019----------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013020
13021As we've seen in introduction, name resolution in HAProxy occurs at two
13022different steps of the process life:
13023
13024 1. when starting up, HAProxy parses the server line definition and matches a
13025 host name. It uses libc functions to get the host name resolved. This
13026 resolution relies on /etc/resolv.conf file.
13027
Christopher Faulet67957bd2017-09-27 11:00:59 +020013028 2. at run time, HAProxy performs periodically name resolutions for servers
13029 requiring DNS resolutions.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013030
13031A few other events can trigger a name resolution at run time:
13032 - when a server's health check ends up in a connection timeout: this may be
13033 because the server has a new IP address. So we need to trigger a name
13034 resolution to know this new IP.
13035
Christopher Faulet67957bd2017-09-27 11:00:59 +020013036When using resolvers, the server name can either be a hostname, or a SRV label.
Davor Ocelice9ed2812017-12-25 17:49:28 +010013037HAProxy considers anything that starts with an underscore as a SRV label. If a
Christopher Faulet67957bd2017-09-27 11:00:59 +020013038SRV label is specified, then the corresponding SRV records will be retrieved
13039from the DNS server, and the provided hostnames will be used. The SRV label
13040will be checked periodically, and if any server are added or removed, haproxy
13041will automatically do the same.
Olivier Houchardecfa18d2017-08-07 17:30:03 +020013042
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013043A few things important to notice:
John Roesler27c754c2019-07-10 15:45:51 -050013044 - all the name servers are queried in the meantime. HAProxy will process the
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013045 first valid response.
13046
13047 - a resolution is considered as invalid (NX, timeout, refused), when all the
13048 servers return an error.
13049
13050
Cyril Bonté46175dd2015-07-02 22:45:32 +0200130515.3.2. The resolvers section
13052----------------------------
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013053
13054This section is dedicated to host information related to name resolution in
Christopher Faulet67957bd2017-09-27 11:00:59 +020013055HAProxy. There can be as many as resolvers section as needed. Each section can
13056contain many name servers.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013057
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013058When multiple name servers are configured in a resolvers section, then HAProxy
13059uses the first valid response. In case of invalid responses, only the last one
13060is treated. Purpose is to give the chance to a slow server to deliver a valid
13061answer after a fast faulty or outdated server.
13062
13063When each server returns a different error type, then only the last error is
Christopher Faulet67957bd2017-09-27 11:00:59 +020013064used by HAProxy. The following processing is applied on this error:
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013065
Christopher Faulet67957bd2017-09-27 11:00:59 +020013066 1. HAProxy retries the same DNS query with a new query type. The A queries are
13067 switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
13068 errors are also excluded.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013069
Christopher Faulet67957bd2017-09-27 11:00:59 +020013070 2. When the fallback on the query type was done (or not applicable), HAProxy
13071 retries the original DNS query, with the preferred query type.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013072
Christopher Faulet67957bd2017-09-27 11:00:59 +020013073 3. HAProxy retries previous steps <resolve_retires> times. If no valid
13074 response is received after that, it stops the DNS resolution and reports
13075 the error.
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013076
Christopher Faulet67957bd2017-09-27 11:00:59 +020013077For example, with 2 name servers configured in a resolvers section, the
13078following scenarios are possible:
13079
13080 - First response is valid and is applied directly, second response is
13081 ignored
13082
13083 - First response is invalid and second one is valid, then second response is
13084 applied
13085
13086 - First response is a NX domain and second one a truncated response, then
13087 HAProxy retries the query with a new type
13088
13089 - First response is a NX domain and second one is a timeout, then HAProxy
13090 retries the query with a new type
13091
13092 - Query timed out for both name servers, then HAProxy retries it with the
13093 same query type
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013094
Olivier Houcharda8c6db82017-07-06 18:46:47 +020013095As a DNS server may not answer all the IPs in one DNS request, haproxy keeps
13096a cache of previous answers, an answer will be considered obsolete after
Christopher Faulet67957bd2017-09-27 11:00:59 +020013097<hold obsolete> seconds without the IP returned.
Olivier Houcharda8c6db82017-07-06 18:46:47 +020013098
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013099
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013100resolvers <resolvers id>
Davor Ocelice9ed2812017-12-25 17:49:28 +010013101 Creates a new name server list labeled <resolvers id>
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013102
13103A resolvers section accept the following parameters:
13104
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020013105accepted_payload_size <nb>
Davor Ocelice9ed2812017-12-25 17:49:28 +010013106 Defines the maximum payload size accepted by HAProxy and announced to all the
Christopher Faulet67957bd2017-09-27 11:00:59 +020013107 name servers configured in this resolvers section.
Baptiste Assmann2af08fe2017-08-14 00:13:01 +020013108 <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
13109 by RFC 6891)
13110
Baptiste Assmann9d8dbbc2017-08-18 23:35:08 +020013111 Note: the maximum allowed value is 8192.
13112
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013113nameserver <id> <ip>:<port>
13114 DNS server description:
13115 <id> : label of the server, should be unique
13116 <ip> : IP address of the server
13117 <port> : port where the DNS service actually runs
13118
Ben Draut44e609b2018-05-29 15:40:08 -060013119parse-resolv-conf
13120 Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers
13121 list. Ordered as if each nameserver in /etc/resolv.conf was individually
13122 placed in the resolvers section in place of this directive.
13123
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013124hold <status> <period>
13125 Defines <period> during which the last name resolution should be kept based
13126 on last resolution <status>
Baptiste Assmann987e16d2016-11-02 22:23:31 +010013127 <status> : last name resolution status. Acceptable values are "nx",
Olivier Houcharda8c6db82017-07-06 18:46:47 +020013128 "other", "refused", "timeout", "valid", "obsolete".
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013129 <period> : interval between two successive name resolution when the last
13130 answer was in <status>. It follows the HAProxy time format.
13131 <period> is in milliseconds by default.
13132
Baptiste Assmann686408b2017-08-18 10:15:42 +020013133 Default value is 10s for "valid", 0s for "obsolete" and 30s for others.
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013134
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013135resolve_retries <nb>
13136 Defines the number <nb> of queries to send to resolve a server name before
13137 giving up.
13138 Default value: 3
13139
Baptiste Assmann62b75b42015-09-09 01:11:36 +020013140 A retry occurs on name server timeout or when the full sequence of DNS query
13141 type failover is over and we need to start up from the default ANY query
13142 type.
13143
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013144timeout <event> <time>
13145 Defines timeouts related to name resolution
13146 <event> : the event on which the <time> timeout period applies to.
13147 events available are:
Frédéric Lécaille93d33162019-03-06 09:35:59 +010013148 - resolve : default time to trigger name resolutions when no
13149 other time applied.
Christopher Faulet67957bd2017-09-27 11:00:59 +020013150 Default value: 1s
13151 - retry : time between two DNS queries, when no valid response
Frédéric Lécaille93d33162019-03-06 09:35:59 +010013152 have been received.
Christopher Faulet67957bd2017-09-27 11:00:59 +020013153 Default value: 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013154 <time> : time related to the event. It follows the HAProxy time format.
13155 <time> is expressed in milliseconds.
13156
Olivier Doucetaa1ea8a2016-08-05 17:15:20 +020013157 Example:
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013158
13159 resolvers mydns
13160 nameserver dns1 10.0.0.1:53
13161 nameserver dns2 10.0.0.2:53
Ben Draut44e609b2018-05-29 15:40:08 -060013162 parse-resolv-conf
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013163 resolve_retries 3
Christopher Faulet67957bd2017-09-27 11:00:59 +020013164 timeout resolve 1s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013165 timeout retry 1s
Baptiste Assmann987e16d2016-11-02 22:23:31 +010013166 hold other 30s
13167 hold refused 30s
13168 hold nx 30s
13169 hold timeout 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013170 hold valid 10s
Olivier Houcharda8c6db82017-07-06 18:46:47 +020013171 hold obsolete 30s
Baptiste Assmann1fa66662015-04-14 00:28:47 +020013172
13173
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200131746. HTTP header manipulation
13175---------------------------
13176
13177In HTTP mode, it is possible to rewrite, add or delete some of the request and
13178response headers based on regular expressions. It is also possible to block a
13179request or a response if a particular header matches a regular expression,
13180which is enough to stop most elementary protocol attacks, and to protect
Willy Tarreau70dffda2014-01-30 03:07:23 +010013181against information leak from the internal network.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013182
Willy Tarreau70dffda2014-01-30 03:07:23 +010013183If HAProxy encounters an "Informational Response" (status code 1xx), it is able
13184to process all rsp* rules which can allow, deny, rewrite or delete a header,
13185but it will refuse to add a header to any such messages as this is not
13186HTTP-compliant. The reason for still processing headers in such responses is to
13187stop and/or fix any possible information leak which may happen, for instance
13188because another downstream equipment would unconditionally add a header, or if
13189a server name appears there. When such messages are seen, normal processing
13190still occurs on the next non-informational messages.
Willy Tarreau816b9792009-09-15 21:25:21 +020013191
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013192This section covers common usage of the following keywords, described in detail
13193in section 4.2 :
13194
13195 - reqadd <string>
13196 - reqallow <search>
13197 - reqiallow <search>
13198 - reqdel <search>
13199 - reqidel <search>
13200 - reqdeny <search>
13201 - reqideny <search>
13202 - reqpass <search>
13203 - reqipass <search>
13204 - reqrep <search> <replace>
13205 - reqirep <search> <replace>
13206 - reqtarpit <search>
13207 - reqitarpit <search>
13208 - rspadd <string>
13209 - rspdel <search>
13210 - rspidel <search>
13211 - rspdeny <search>
13212 - rspideny <search>
13213 - rsprep <search> <replace>
13214 - rspirep <search> <replace>
13215
13216With all these keywords, the same conventions are used. The <search> parameter
13217is a POSIX extended regular expression (regex) which supports grouping through
13218parenthesis (without the backslash). Spaces and other delimiters must be
13219prefixed with a backslash ('\') to avoid confusion with a field delimiter.
13220Other characters may be prefixed with a backslash to change their meaning :
13221
13222 \t for a tab
13223 \r for a carriage return (CR)
13224 \n for a new line (LF)
13225 \ to mark a space and differentiate it from a delimiter
13226 \# to mark a sharp and differentiate it from a comment
13227 \\ to use a backslash in a regex
13228 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
13229 \xXX to write the ASCII hex code XX as in the C language
13230
13231The <replace> parameter contains the string to be used to replace the largest
13232portion of text matching the regex. It can make use of the special characters
13233above, and can reference a substring which is delimited by parenthesis in the
13234regex, by writing a backslash ('\') immediately followed by one digit from 0 to
132359 indicating the group position (0 designating the entire line). This practice
13236is very common to users of the "sed" program.
13237
13238The <string> parameter represents the string which will systematically be added
13239after the last header line. It can also use special character sequences above.
13240
13241Notes related to these keywords :
13242---------------------------------
13243 - these keywords are not always convenient to allow/deny based on header
13244 contents. It is strongly recommended to use ACLs with the "block" keyword
13245 instead, resulting in far more flexible and manageable rules.
13246
13247 - lines are always considered as a whole. It is not possible to reference
13248 a header name only or a value only. This is important because of the way
13249 headers are written (notably the number of spaces after the colon).
13250
13251 - the first line is always considered as a header, which makes it possible to
13252 rewrite or filter HTTP requests URIs or response codes, but in turn makes
13253 it harder to distinguish between headers and request line. The regex prefix
13254 ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix
13255 ^[^ \t:]*: matches any header name followed by a colon.
13256
13257 - for performances reasons, the number of characters added to a request or to
13258 a response is limited at build time to values between 1 and 4 kB. This
13259 should normally be far more than enough for most usages. If it is too short
13260 on occasional usages, it is possible to gain some space by removing some
13261 useless headers before adding new ones.
13262
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010013263 - keywords beginning with "reqi" and "rspi" are the same as their counterpart
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013264 without the 'i' letter except that they ignore case when matching patterns.
13265
13266 - when a request passes through a frontend then a backend, all req* rules
13267 from the frontend will be evaluated, then all req* rules from the backend
13268 will be evaluated. The reverse path is applied to responses.
13269
13270 - req* statements are applied after "block" statements, so that "block" is
13271 always the first one, but before "use_backend" in order to permit rewriting
Willy Tarreaud72758d2010-01-12 10:42:19 +010013272 before switching.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013273
13274
Willy Tarreau74ca5042013-06-11 23:12:07 +0200132757. Using ACLs and fetching samples
13276----------------------------------
13277
Davor Ocelice9ed2812017-12-25 17:49:28 +010013278HAProxy is capable of extracting data from request or response streams, from
Willy Tarreau74ca5042013-06-11 23:12:07 +020013279client or server information, from tables, environmental information etc...
13280The action of extracting such data is called fetching a sample. Once retrieved,
13281these samples may be used for various purposes such as a key to a stick-table,
13282but most common usages consist in matching them against predefined constant
13283data called patterns.
13284
13285
132867.1. ACL basics
13287---------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013288
13289The use of Access Control Lists (ACL) provides a flexible solution to perform
13290content switching and generally to take decisions based on content extracted
13291from the request, the response or any environmental status. The principle is
13292simple :
13293
Willy Tarreau74ca5042013-06-11 23:12:07 +020013294 - extract a data sample from a stream, table or the environment
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013295 - optionally apply some format conversion to the extracted sample
Willy Tarreau74ca5042013-06-11 23:12:07 +020013296 - apply one or multiple pattern matching methods on this sample
13297 - perform actions only when a pattern matches the sample
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013298
Willy Tarreau74ca5042013-06-11 23:12:07 +020013299The actions generally consist in blocking a request, selecting a backend, or
13300adding a header.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013301
13302In order to define a test, the "acl" keyword is used. The syntax is :
13303
Willy Tarreau74ca5042013-06-11 23:12:07 +020013304 acl <aclname> <criterion> [flags] [operator] [<value>] ...
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013305
13306This creates a new ACL <aclname> or completes an existing one with new tests.
13307Those tests apply to the portion of request/response specified in <criterion>
13308and may be adjusted with optional flags [flags]. Some criteria also support
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013309an operator which may be specified before the set of values. Optionally some
13310conversion operators may be applied to the sample, and they will be specified
13311as a comma-delimited list of keywords just after the first keyword. The values
13312are of the type supported by the criterion, and are separated by spaces.
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013313
13314ACL names must be formed from upper and lower case letters, digits, '-' (dash),
13315'_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive,
13316which means that "my_acl" and "My_Acl" are two different ACLs.
13317
13318There is no enforced limit to the number of ACLs. The unused ones do not affect
13319performance, they just consume a small amount of memory.
13320
Willy Tarreau74ca5042013-06-11 23:12:07 +020013321The criterion generally is the name of a sample fetch method, or one of its ACL
13322specific declinations. The default test method is implied by the output type of
13323this sample fetch method. The ACL declinations can describe alternate matching
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013324methods of a same sample fetch method. The sample fetch methods are the only
13325ones supporting a conversion.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013326
13327Sample fetch methods return data which can be of the following types :
13328 - boolean
13329 - integer (signed or unsigned)
13330 - IPv4 or IPv6 address
13331 - string
13332 - data block
13333
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013334Converters transform any of these data into any of these. For example, some
13335converters might convert a string to a lower-case string while other ones
13336would turn a string to an IPv4 address, or apply a netmask to an IP address.
13337The resulting sample is of the type of the last converter applied to the list,
13338which defaults to the type of the sample fetch method.
13339
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013340Each sample or converter returns data of a specific type, specified with its
13341keyword in this documentation. When an ACL is declared using a standard sample
13342fetch method, certain types automatically involved a default matching method
13343which are summarized in the table below :
13344
13345 +---------------------+-----------------+
13346 | Sample or converter | Default |
13347 | output type | matching method |
13348 +---------------------+-----------------+
13349 | boolean | bool |
13350 +---------------------+-----------------+
13351 | integer | int |
13352 +---------------------+-----------------+
13353 | ip | ip |
13354 +---------------------+-----------------+
13355 | string | str |
13356 +---------------------+-----------------+
13357 | binary | none, use "-m" |
13358 +---------------------+-----------------+
13359
13360Note that in order to match a binary samples, it is mandatory to specify a
13361matching method, see below.
13362
Willy Tarreau74ca5042013-06-11 23:12:07 +020013363The ACL engine can match these types against patterns of the following types :
13364 - boolean
13365 - integer or integer range
13366 - IP address / network
13367 - string (exact, substring, suffix, prefix, subdir, domain)
13368 - regular expression
13369 - hex block
13370
Willy Tarreauc57f0e22009-05-10 13:12:33 +020013371The following ACL flags are currently supported :
13372
Willy Tarreau2b5285d2010-05-09 23:45:24 +020013373 -i : ignore case during matching of all subsequent patterns.
13374 -f : load patterns from a file.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013375 -m : use a specific pattern matching method
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010013376 -n : forbid the DNS resolutions
Thierry FOURNIER9860c412014-01-29 14:23:29 +010013377 -M : load the file pointed by -f like a map file.
Thierry FOURNIER3534d882014-01-20 17:01:44 +010013378 -u : force the unique id of the ACL
Willy Tarreau6a06a402007-07-15 20:15:28 +020013379 -- : force end of flags. Useful when a string looks like one of the flags.
13380
Willy Tarreau74ca5042013-06-11 23:12:07 +020013381The "-f" flag is followed by the name of a file from which all lines will be
13382read as individual values. It is even possible to pass multiple "-f" arguments
13383if the patterns are to be loaded from multiple files. Empty lines as well as
13384lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
13385will be stripped. If it is absolutely necessary to insert a valid pattern
13386beginning with a sharp, just prefix it with a space so that it is not taken for
13387a comment. Depending on the data type and match method, haproxy may load the
13388lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
13389exact string matching. In this case, duplicates will automatically be removed.
13390
Thierry FOURNIER9860c412014-01-29 14:23:29 +010013391The "-M" flag allows an ACL to use a map file. If this flag is set, the file is
13392parsed as two column file. The first column contains the patterns used by the
13393ACL, and the second column contain the samples. The sample can be used later by
13394a map. This can be useful in some rare cases where an ACL would just be used to
13395check for the existence of a pattern in a map before a mapping is applied.
13396
Thierry FOURNIER3534d882014-01-20 17:01:44 +010013397The "-u" flag forces the unique id of the ACL. This unique id is used with the
13398socket interface to identify ACL and dynamically change its values. Note that a
13399file is always identified by its name even if an id is set.
13400
Willy Tarreau74ca5042013-06-11 23:12:07 +020013401Also, note that the "-i" flag applies to subsequent entries and not to entries
13402loaded from files preceding it. For instance :
13403
13404 acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
13405
13406In this example, each line of "exact-ua.lst" will be exactly matched against
13407the "user-agent" header of the request. Then each line of "generic-ua" will be
13408case-insensitively matched. Then the word "test" will be insensitively matched
13409as well.
13410
13411The "-m" flag is used to select a specific pattern matching method on the input
13412sample. All ACL-specific criteria imply a pattern matching method and generally
13413do not need this flag. However, this flag is useful with generic sample fetch
13414methods to describe how they're going to be matched against the patterns. This
13415is required for sample fetches which return data type for which there is no
Davor Ocelice9ed2812017-12-25 17:49:28 +010013416obvious matching method (e.g. string or binary). When "-m" is specified and
Willy Tarreau74ca5042013-06-11 23:12:07 +020013417followed by a pattern matching method name, this method is used instead of the
13418default one for the criterion. This makes it possible to match contents in ways
13419that were not initially planned, or with sample fetch methods which return a
13420string. The matching method also affects the way the patterns are parsed.
13421
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010013422The "-n" flag forbids the dns resolutions. It is used with the load of ip files.
13423By default, if the parser cannot parse ip address it considers that the parsed
13424string is maybe a domain name and try dns resolution. The flag "-n" disable this
13425resolution. It is useful for detecting malformed ip lists. Note that if the DNS
13426server is not reachable, the haproxy configuration parsing may last many minutes
John Roesler27c754c2019-07-10 15:45:51 -050013427waiting for the timeout. During this time no error messages are displayed. The
Thierry FOURNIERb7729c92014-02-11 16:24:41 +010013428flag "-n" disable this behavior. Note also that during the runtime, this
13429function is disabled for the dynamic acl modifications.
13430
Willy Tarreau74ca5042013-06-11 23:12:07 +020013431There are some restrictions however. Not all methods can be used with all
13432sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
13433be placed first. The pattern matching method must be one of the following :
Willy Tarreau5adeda12013-03-31 22:13:34 +020013434
13435 - "found" : only check if the requested sample could be found in the stream,
13436 but do not compare it against any pattern. It is recommended not
Willy Tarreau74ca5042013-06-11 23:12:07 +020013437 to pass any pattern to avoid confusion. This matching method is
13438 particularly useful to detect presence of certain contents such
13439 as headers, cookies, etc... even if they are empty and without
13440 comparing them to anything nor counting them.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013441
13442 - "bool" : check the value as a boolean. It can only be applied to fetches
13443 which return a boolean or integer value, and takes no pattern.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013444 Value zero or false does not match, all other values do match.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013445
13446 - "int" : match the value as an integer. It can be used with integer and
Willy Tarreau74ca5042013-06-11 23:12:07 +020013447 boolean samples. Boolean false is integer 0, true is integer 1.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013448
13449 - "ip" : match the value as an IPv4 or IPv6 address. It is compatible
Willy Tarreau74ca5042013-06-11 23:12:07 +020013450 with IP address samples only, so it is implied and never needed.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013451
Davor Ocelice9ed2812017-12-25 17:49:28 +010013452 - "bin" : match the contents against a hexadecimal string representing a
Willy Tarreau5adeda12013-03-31 22:13:34 +020013453 binary sequence. This may be used with binary or string samples.
13454
13455 - "len" : match the sample's length as an integer. This may be used with
13456 binary or string samples.
13457
Willy Tarreau74ca5042013-06-11 23:12:07 +020013458 - "str" : exact match : match the contents against a string. This may be
13459 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013460
Willy Tarreau74ca5042013-06-11 23:12:07 +020013461 - "sub" : substring match : check that the contents contain at least one of
13462 the provided string patterns. This may be used with binary or
13463 string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013464
Willy Tarreau74ca5042013-06-11 23:12:07 +020013465 - "reg" : regex match : match the contents against a list of regular
13466 expressions. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013467
Willy Tarreau74ca5042013-06-11 23:12:07 +020013468 - "beg" : prefix match : check that the contents begin like the provided
13469 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013470
Willy Tarreau74ca5042013-06-11 23:12:07 +020013471 - "end" : suffix match : check that the contents end like the provided
13472 string patterns. This may be used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013473
Willy Tarreau74ca5042013-06-11 23:12:07 +020013474 - "dir" : subdir match : check that a slash-delimited portion of the
13475 contents exactly matches one of the provided string patterns.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013476 This may be used with binary or string samples.
13477
Willy Tarreau74ca5042013-06-11 23:12:07 +020013478 - "dom" : domain match : check that a dot-delimited portion of the contents
13479 exactly match one of the provided string patterns. This may be
13480 used with binary or string samples.
Willy Tarreau5adeda12013-03-31 22:13:34 +020013481
13482For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
13483request, it is possible to do :
13484
13485 acl jsess_present cook(JSESSIONID) -m found
13486
13487In order to apply a regular expression on the 500 first bytes of data in the
13488buffer, one would use the following acl :
13489
13490 acl script_tag payload(0,500) -m reg -i <script>
13491
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013492On systems where the regex library is much slower when using "-i", it is
13493possible to convert the sample to lowercase before matching, like this :
13494
13495 acl script_tag payload(0,500),lower -m reg <script>
13496
Willy Tarreau74ca5042013-06-11 23:12:07 +020013497All ACL-specific criteria imply a default matching method. Most often, these
13498criteria are composed by concatenating the name of the original sample fetch
13499method and the matching method. For example, "hdr_beg" applies the "beg" match
13500to samples retrieved using the "hdr" fetch method. Since all ACL-specific
13501criteria rely on a sample fetch method, it is always possible instead to use
13502the original sample fetch method and the explicit matching method using "-m".
Willy Tarreau2b5285d2010-05-09 23:45:24 +020013503
Willy Tarreau74ca5042013-06-11 23:12:07 +020013504If an alternate match is specified using "-m" on an ACL-specific criterion,
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030013505the matching method is simply applied to the underlying sample fetch method.
13506For example, all ACLs below are exact equivalent :
Willy Tarreau2b5285d2010-05-09 23:45:24 +020013507
Willy Tarreau74ca5042013-06-11 23:12:07 +020013508 acl short_form hdr_beg(host) www.
13509 acl alternate1 hdr_beg(host) -m beg www.
13510 acl alternate2 hdr_dom(host) -m beg www.
13511 acl alternate3 hdr(host) -m beg www.
Willy Tarreau2b5285d2010-05-09 23:45:24 +020013512
Willy Tarreau2b5285d2010-05-09 23:45:24 +020013513
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013514The table below summarizes the compatibility matrix between sample or converter
13515types and the pattern types to fetch against. It indicates for each compatible
13516combination the name of the matching method to be used, surrounded with angle
13517brackets ">" and "<" when the method is the default one and will work by
13518default without "-m".
Willy Tarreau0ba27502007-12-24 16:55:16 +010013519
Willy Tarreau74ca5042013-06-11 23:12:07 +020013520 +-------------------------------------------------+
13521 | Input sample type |
13522 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013523 | pattern type | boolean | integer | ip | string | binary |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013524 +----------------------+---------+---------+---------+---------+---------+
13525 | none (presence only) | found | found | found | found | found |
13526 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013527 | none (boolean value) |> bool <| bool | | bool | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013528 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013529 | integer (value) | int |> int <| int | int | |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013530 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013531 | integer (length) | len | len | len | len | len |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013532 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013533 | IP address | | |> ip <| ip | ip |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013534 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIER2a06e392014-05-11 15:49:55 +020013535 | exact string | str | str | str |> str <| str |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013536 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013537 | prefix | beg | beg | beg | beg | beg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013538 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013539 | suffix | end | end | end | end | end |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013540 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013541 | substring | sub | sub | sub | sub | sub |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013542 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013543 | subdir | dir | dir | dir | dir | dir |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013544 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013545 | domain | dom | dom | dom | dom | dom |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013546 +----------------------+---------+---------+---------+---------+---------+
Thierry FOURNIERe3ded592013-12-06 15:36:54 +010013547 | regex | reg | reg | reg | reg | reg |
Willy Tarreau74ca5042013-06-11 23:12:07 +020013548 +----------------------+---------+---------+---------+---------+---------+
13549 | hex block | | | | bin | bin |
13550 +----------------------+---------+---------+---------+---------+---------+
Willy Tarreau6a06a402007-07-15 20:15:28 +020013551
13552
Willy Tarreau74ca5042013-06-11 23:12:07 +0200135537.1.1. Matching booleans
13554------------------------
13555
13556In order to match a boolean, no value is needed and all values are ignored.
13557Boolean matching is used by default for all fetch methods of type "boolean".
13558When boolean matching is used, the fetched value is returned as-is, which means
13559that a boolean "true" will always match and a boolean "false" will never match.
13560
13561Boolean matching may also be enforced using "-m bool" on fetch methods which
13562return an integer value. Then, integer value 0 is converted to the boolean
13563"false" and all other values are converted to "true".
13564
Willy Tarreau6a06a402007-07-15 20:15:28 +020013565
Willy Tarreau74ca5042013-06-11 23:12:07 +0200135667.1.2. Matching integers
13567------------------------
13568
13569Integer matching applies by default to integer fetch methods. It can also be
13570enforced on boolean fetches using "-m int". In this case, "false" is converted
13571to the integer 0, and "true" is converted to the integer 1.
13572
13573Integer matching also supports integer ranges and operators. Note that integer
13574matching only applies to positive values. A range is a value expressed with a
13575lower and an upper bound separated with a colon, both of which may be omitted.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013576
13577For instance, "1024:65535" is a valid range to represent a range of
13578unprivileged ports, and "1024:" would also work. "0:1023" is a valid
13579representation of privileged ports, and ":1023" would also work.
13580
Willy Tarreau62644772008-07-16 18:36:06 +020013581As a special case, some ACL functions support decimal numbers which are in fact
13582two integers separated by a dot. This is used with some version checks for
13583instance. All integer properties apply to those decimal numbers, including
13584ranges and operators.
13585
Willy Tarreau6a06a402007-07-15 20:15:28 +020013586For an easier usage, comparison operators are also supported. Note that using
Willy Tarreau0ba27502007-12-24 16:55:16 +010013587operators with ranges does not make much sense and is strongly discouraged.
13588Similarly, it does not make much sense to perform order comparisons with a set
13589of values.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013590
Willy Tarreau0ba27502007-12-24 16:55:16 +010013591Available operators for integer matching are :
Willy Tarreau6a06a402007-07-15 20:15:28 +020013592
13593 eq : true if the tested value equals at least one value
13594 ge : true if the tested value is greater than or equal to at least one value
13595 gt : true if the tested value is greater than at least one value
13596 le : true if the tested value is less than or equal to at least one value
13597 lt : true if the tested value is less than at least one value
13598
Willy Tarreau0ba27502007-12-24 16:55:16 +010013599For instance, the following ACL matches any negative Content-Length header :
Willy Tarreau6a06a402007-07-15 20:15:28 +020013600
13601 acl negative-length hdr_val(content-length) lt 0
13602
Willy Tarreau62644772008-07-16 18:36:06 +020013603This one matches SSL versions between 3.0 and 3.1 (inclusive) :
13604
13605 acl sslv3 req_ssl_ver 3:3.1
13606
Willy Tarreau6a06a402007-07-15 20:15:28 +020013607
Willy Tarreau74ca5042013-06-11 23:12:07 +0200136087.1.3. Matching strings
13609-----------------------
13610
13611String matching applies to string or binary fetch methods, and exists in 6
13612different forms :
13613
13614 - exact match (-m str) : the extracted string must exactly match the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013615 patterns;
Willy Tarreau74ca5042013-06-11 23:12:07 +020013616
13617 - substring match (-m sub) : the patterns are looked up inside the
Davor Ocelice9ed2812017-12-25 17:49:28 +010013618 extracted string, and the ACL matches if any of them is found inside;
Willy Tarreau74ca5042013-06-11 23:12:07 +020013619
13620 - prefix match (-m beg) : the patterns are compared with the beginning of
13621 the extracted string, and the ACL matches if any of them matches.
13622
13623 - suffix match (-m end) : the patterns are compared with the end of the
13624 extracted string, and the ACL matches if any of them matches.
13625
Baptiste Assmann33db6002016-03-06 23:32:10 +010013626 - subdir match (-m dir) : the patterns are looked up inside the extracted
Willy Tarreau74ca5042013-06-11 23:12:07 +020013627 string, delimited with slashes ("/"), and the ACL matches if any of them
13628 matches.
13629
13630 - domain match (-m dom) : the patterns are looked up inside the extracted
13631 string, delimited with dots ("."), and the ACL matches if any of them
13632 matches.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013633
13634String matching applies to verbatim strings as they are passed, with the
13635exception of the backslash ("\") which makes it possible to escape some
13636characters such as the space. If the "-i" flag is passed before the first
13637string, then the matching will be performed ignoring the case. In order
13638to match the string "-i", either set it second, or pass the "--" flag
Willy Tarreau0ba27502007-12-24 16:55:16 +010013639before the first string. Same applies of course to match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020013640
Mathias Weiersmuellerb2fe2232019-12-02 09:43:40 +010013641Do not use string matches for binary fetches which might contain null bytes
13642(0x00), as the comparison stops at the occurrence of the first null byte.
13643Instead, convert the binary fetch to a hex string with the hex converter first.
13644
13645Example:
13646 # matches if the string <tag> is present in the binary sample
13647 acl tag_found req.payload(0,0),hex -m sub 3C7461673E
13648
Willy Tarreau6a06a402007-07-15 20:15:28 +020013649
Willy Tarreau74ca5042013-06-11 23:12:07 +0200136507.1.4. Matching regular expressions (regexes)
13651---------------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020013652
13653Just like with string matching, regex matching applies to verbatim strings as
13654they are passed, with the exception of the backslash ("\") which makes it
13655possible to escape some characters such as the space. If the "-i" flag is
13656passed before the first regex, then the matching will be performed ignoring
13657the case. In order to match the string "-i", either set it second, or pass
Willy Tarreau0ba27502007-12-24 16:55:16 +010013658the "--" flag before the first string. Same principle applies of course to
13659match the string "--".
Willy Tarreau6a06a402007-07-15 20:15:28 +020013660
13661
Willy Tarreau74ca5042013-06-11 23:12:07 +0200136627.1.5. Matching arbitrary data blocks
13663-------------------------------------
13664
13665It is possible to match some extracted samples against a binary block which may
13666not safely be represented as a string. For this, the patterns must be passed as
13667a series of hexadecimal digits in an even number, when the match method is set
13668to binary. Each sequence of two digits will represent a byte. The hexadecimal
13669digits may be used upper or lower case.
13670
13671Example :
13672 # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
13673 acl hello payload(0,6) -m bin 48656c6c6f0a
13674
13675
136767.1.6. Matching IPv4 and IPv6 addresses
13677---------------------------------------
Willy Tarreau6a06a402007-07-15 20:15:28 +020013678
13679IPv4 addresses values can be specified either as plain addresses or with a
13680netmask appended, in which case the IPv4 address matches whenever it is
13681within the network. Plain addresses may also be replaced with a resolvable
Willy Tarreaud2a4aa22008-01-31 15:28:22 +010013682host name, but this practice is generally discouraged as it makes it more
Willy Tarreau0ba27502007-12-24 16:55:16 +010013683difficult to read and debug configurations. If hostnames are used, you should
13684at least ensure that they are present in /etc/hosts so that the configuration
13685does not depend on any random DNS match at the moment the configuration is
13686parsed.
Willy Tarreau6a06a402007-07-15 20:15:28 +020013687
Daniel Schnellereba56342016-04-13 00:26:52 +020013688The dotted IPv4 address notation is supported in both regular as well as the
13689abbreviated form with all-0-octets omitted:
13690
13691 +------------------+------------------+------------------+
13692 | Example 1 | Example 2 | Example 3 |
13693 +------------------+------------------+------------------+
13694 | 192.168.0.1 | 10.0.0.12 | 127.0.0.1 |
13695 | 192.168.1 | 10.12 | 127.1 |
13696 | 192.168.0.1/22 | 10.0.0.12/8 | 127.0.0.1/8 |
13697 | 192.168.1/22 | 10.12/8 | 127.1/8 |
13698 +------------------+------------------+------------------+
13699
13700Notice that this is different from RFC 4632 CIDR address notation in which
13701192.168.42/24 would be equivalent to 192.168.42.0/24.
13702
Willy Tarreauceb4ac92012-04-28 00:41:46 +020013703IPv6 may be entered in their usual form, with or without a netmask appended.
13704Only bit counts are accepted for IPv6 netmasks. In order to avoid any risk of
13705trouble with randomly resolved IP addresses, host names are never allowed in
13706IPv6 patterns.
13707
13708HAProxy is also able to match IPv4 addresses with IPv6 addresses in the
13709following situations :
13710 - tested address is IPv4, pattern address is IPv4, the match applies
13711 in IPv4 using the supplied mask if any.
13712 - tested address is IPv6, pattern address is IPv6, the match applies
13713 in IPv6 using the supplied mask if any.
13714 - tested address is IPv6, pattern address is IPv4, the match applies in IPv4
13715 using the pattern's mask if the IPv6 address matches with 2002:IPV4::,
13716 ::IPV4 or ::ffff:IPV4, otherwise it fails.
13717 - tested address is IPv4, pattern address is IPv6, the IPv4 address is first
13718 converted to IPv6 by prefixing ::ffff: in front of it, then the match is
13719 applied in IPv6 using the supplied IPv6 mask.
13720
Willy Tarreau74ca5042013-06-11 23:12:07 +020013721
137227.2. Using ACLs to form conditions
13723----------------------------------
13724
13725Some actions are only performed upon a valid condition. A condition is a
13726combination of ACLs with operators. 3 operators are supported :
13727
13728 - AND (implicit)
13729 - OR (explicit with the "or" keyword or the "||" operator)
13730 - Negation with the exclamation mark ("!")
Willy Tarreau6a06a402007-07-15 20:15:28 +020013731
Willy Tarreau74ca5042013-06-11 23:12:07 +020013732A condition is formed as a disjunctive form:
Willy Tarreau6a06a402007-07-15 20:15:28 +020013733
Willy Tarreau74ca5042013-06-11 23:12:07 +020013734 [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
Willy Tarreaubef91e72013-03-31 23:14:46 +020013735
Willy Tarreau74ca5042013-06-11 23:12:07 +020013736Such conditions are generally used after an "if" or "unless" statement,
13737indicating when the condition will trigger the action.
Willy Tarreaubef91e72013-03-31 23:14:46 +020013738
Willy Tarreau74ca5042013-06-11 23:12:07 +020013739For instance, to block HTTP requests to the "*" URL with methods other than
13740"OPTIONS", as well as POST requests without content-length, and GET or HEAD
13741requests with a content-length greater than 0, and finally every request which
13742is not either GET/HEAD/POST/OPTIONS !
13743
13744 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013745 http-request deny if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
13746 http-request deny if METH_GET HTTP_CONTENT
13747 http-request deny unless METH_GET or METH_POST or METH_OPTIONS
Willy Tarreau74ca5042013-06-11 23:12:07 +020013748
13749To select a different backend for requests to static contents on the "www" site
13750and to every request on the "img", "video", "download" and "ftp" hosts :
13751
13752 acl url_static path_beg /static /images /img /css
13753 acl url_static path_end .gif .png .jpg .css .js
13754 acl host_www hdr_beg(host) -i www
13755 acl host_static hdr_beg(host) -i img. video. download. ftp.
13756
Davor Ocelice9ed2812017-12-25 17:49:28 +010013757 # now use backend "static" for all static-only hosts, and for static URLs
Willy Tarreau74ca5042013-06-11 23:12:07 +020013758 # of host "www". Use backend "www" for the rest.
13759 use_backend static if host_static or host_www url_static
13760 use_backend www if host_www
13761
13762It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
13763expressions that are built on the fly without needing to be declared. They must
13764be enclosed between braces, with a space before and after each brace (because
13765the braces must be seen as independent words). Example :
13766
13767 The following rule :
13768
13769 acl missing_cl hdr_cnt(Content-length) eq 0
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013770 http-request deny if METH_POST missing_cl
Willy Tarreau74ca5042013-06-11 23:12:07 +020013771
13772 Can also be written that way :
13773
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013774 http-request deny if METH_POST { hdr_cnt(Content-length) eq 0 }
Willy Tarreau74ca5042013-06-11 23:12:07 +020013775
13776It is generally not recommended to use this construct because it's a lot easier
13777to leave errors in the configuration when written that way. However, for very
13778simple rules matching only one source IP address for instance, it can make more
13779sense to use them than to declare ACLs with random names. Another example of
13780good use is the following :
13781
13782 With named ACLs :
13783
13784 acl site_dead nbsrv(dynamic) lt 2
13785 acl site_dead nbsrv(static) lt 2
13786 monitor fail if site_dead
13787
13788 With anonymous ACLs :
13789
13790 monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
13791
Jarno Huuskonen84c51ec2017-04-03 14:20:34 +030013792See section 4.2 for detailed help on the "http-request deny" and "use_backend"
13793keywords.
Willy Tarreau74ca5042013-06-11 23:12:07 +020013794
13795
137967.3. Fetching samples
13797---------------------
13798
13799Historically, sample fetch methods were only used to retrieve data to match
13800against patterns using ACLs. With the arrival of stick-tables, a new class of
13801sample fetch methods was created, most often sharing the same syntax as their
13802ACL counterpart. These sample fetch methods are also known as "fetches". As
13803of now, ACLs and fetches have converged. All ACL fetch methods have been made
13804available as fetch methods, and ACLs may use any sample fetch method as well.
13805
13806This section details all available sample fetch methods and their output type.
13807Some sample fetch methods have deprecated aliases that are used to maintain
13808compatibility with existing configurations. They are then explicitly marked as
13809deprecated and should not be used in new setups.
13810
13811The ACL derivatives are also indicated when available, with their respective
13812matching methods. These ones all have a well defined default pattern matching
13813method, so it is never necessary (though allowed) to pass the "-m" option to
13814indicate how the sample will be matched using ACLs.
13815
13816As indicated in the sample type versus matching compatibility matrix above,
13817when using a generic sample fetch method in an ACL, the "-m" option is
13818mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
13819the same keyword exists as an ACL keyword and as a standard fetch method, the
13820ACL engine will automatically pick the ACL-only one by default.
13821
13822Some of these keywords support one or multiple mandatory arguments, and one or
13823multiple optional arguments. These arguments are strongly typed and are checked
13824when the configuration is parsed so that there is no risk of running with an
Davor Ocelice9ed2812017-12-25 17:49:28 +010013825incorrect argument (e.g. an unresolved backend name). Fetch function arguments
13826are passed between parenthesis and are delimited by commas. When an argument
Willy Tarreau74ca5042013-06-11 23:12:07 +020013827is optional, it will be indicated below between square brackets ('[ ]'). When
13828all arguments are optional, the parenthesis may be omitted.
13829
13830Thus, the syntax of a standard sample fetch method is one of the following :
13831 - name
13832 - name(arg1)
13833 - name(arg1,arg2)
13834
Thierry FOURNIER060762e2014-04-23 13:29:15 +020013835
138367.3.1. Converters
13837-----------------
13838
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013839Sample fetch methods may be combined with transformations to be applied on top
13840of the fetched sample (also called "converters"). These combinations form what
13841is called "sample expressions" and the result is a "sample". Initially this
13842was only supported by "stick on" and "stick store-request" directives but this
Davor Ocelice9ed2812017-12-25 17:49:28 +010013843has now be extended to all places where samples may be used (ACLs, log-format,
Willy Tarreaue6b11e42013-11-26 19:02:32 +010013844unique-id-format, add-header, ...).
13845
13846These transformations are enumerated as a series of specific keywords after the
13847sample fetch method. These keywords may equally be appended immediately after
13848the fetch keyword's argument, delimited by a comma. These keywords can also
Davor Ocelice9ed2812017-12-25 17:49:28 +010013849support some arguments (e.g. a netmask) which must be passed in parenthesis.
Willy Tarreau0ba27502007-12-24 16:55:16 +010013850
Willy Tarreau97707872015-01-27 15:12:13 +010013851A certain category of converters are bitwise and arithmetic operators which
13852support performing basic operations on integers. Some bitwise operations are
13853supported (and, or, xor, cpl) and some arithmetic operations are supported
13854(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
13855bool) which make it possible to report a match without having to write an ACL.
13856
Willy Tarreau74ca5042013-06-11 23:12:07 +020013857The currently available list of transformation keywords include :
Willy Tarreau0ba27502007-12-24 16:55:16 +010013858
Ben Shillitof25e8e52016-12-02 14:25:37 +00001385951d.single(<prop>[,<prop>*])
13860 Returns values for the properties requested as a string, where values are
13861 separated by the delimiter specified with "51degrees-property-separator".
13862 The device is identified using the User-Agent header passed to the
13863 converter. The function can be passed up to five property names, and if a
13864 property name can't be found, the value "NoData" is returned.
13865
13866 Example :
Davor Ocelice9ed2812017-12-25 17:49:28 +010013867 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request,
13868 # containing values for the three properties requested by using the
Ben Shillitof25e8e52016-12-02 14:25:37 +000013869 # User-Agent passed to the converter.
13870 frontend http-in
13871 bind *:8081
13872 default_backend servers
13873 http-request set-header X-51D-DeviceTypeMobileTablet \
13874 %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
13875
Willy Tarreau97707872015-01-27 15:12:13 +010013876add(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013877 Adds <value> to the input value of type signed integer, and returns the
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013878 result as a signed integer. <value> can be a numeric value or a variable
Daniel Schneller0b547052016-03-21 20:46:57 +010013879 name. The name of the variable starts with an indication about its scope. The
13880 scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013881 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013882 "sess" : the variable is shared with the whole session
13883 "txn" : the variable is shared with the transaction (request and response)
13884 "req" : the variable is shared only during request processing
13885 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013886 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013887 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013888
Nenad Merdanovicc31499d2019-03-23 11:00:32 +010013889aes_gcm_dec(<bits>,<nonce>,<key>,<aead_tag>)
13890 Decrypts the raw byte input using the AES128-GCM, AES192-GCM or
13891 AES256-GCM algorithm, depending on the <bits> parameter. All other parameters
13892 need to be base64 encoded and the returned result is in raw byte format.
13893 If the <aead_tag> validation fails, the converter doesn't return any data.
13894 The <nonce>, <key> and <aead_tag> can either be strings or variables. This
13895 converter requires at least OpenSSL 1.0.1.
13896
13897 Example:
13898 http-response set-header X-Decrypted-Text %[var(txn.enc),\
13899 aes_gcm_dec(128,txn.nonce,Zm9vb2Zvb29mb29wZm9vbw==,txn.aead_tag)]
13900
Willy Tarreau97707872015-01-27 15:12:13 +010013901and(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013902 Performs a bitwise "AND" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020013903 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010013904 numeric value or a variable name. The name of the variable starts with an
13905 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010013906 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010013907 "sess" : the variable is shared with the whole session
13908 "txn" : the variable is shared with the transaction (request and response)
13909 "req" : the variable is shared only during request processing
13910 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010013911 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010013912 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010013913
Holger Just1bfc24b2017-05-06 00:56:53 +020013914b64dec
13915 Converts (decodes) a base64 encoded input string to its binary
13916 representation. It performs the inverse operation of base64().
13917
Emeric Brun53d1a982014-04-30 18:21:37 +020013918base64
13919 Converts a binary input sample to a base64 string. It is used to log or
Davor Ocelice9ed2812017-12-25 17:49:28 +010013920 transfer binary content in a way that can be reliably transferred (e.g.
Emeric Brun53d1a982014-04-30 18:21:37 +020013921 an SSL ID can be copied in a header).
13922
Willy Tarreau97707872015-01-27 15:12:13 +010013923bool
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013924 Returns a boolean TRUE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010013925 non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010013926 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010013927 presence of a flag).
13928
Emeric Brun54c4ac82014-11-03 15:32:43 +010013929bytes(<offset>[,<length>])
13930 Extracts some bytes from an input binary sample. The result is a binary
13931 sample starting at an offset (in bytes) of the original sample and
Tim Düsterhus4896c442016-11-29 02:15:19 +010013932 optionally truncated at the given length.
Emeric Brun54c4ac82014-11-03 15:32:43 +010013933
Willy Tarreau280f42b2018-02-19 15:34:12 +010013934concat([<start>],[<var>],[<end>])
13935 Concatenates up to 3 fields after the current sample which is then turned to
13936 a string. The first one, <start>, is a constant string, that will be appended
13937 immediately after the existing sample. It may be omitted if not used. The
13938 second one, <var>, is a variable name. The variable will be looked up, its
13939 contents converted to a string, and it will be appended immediately after the
13940 <first> part. If the variable is not found, nothing is appended. It may be
13941 omitted as well. The third field, <end> is a constant string that will be
13942 appended after the variable. It may also be omitted. Together, these elements
13943 allow to concatenate variables with delimiters to an existing set of
13944 variables. This can be used to build new variables made of a succession of
John Roesler27c754c2019-07-10 15:45:51 -050013945 other variables, such as colon-delimited values. Note that due to the config
Willy Tarreau280f42b2018-02-19 15:34:12 +010013946 parser, it is not possible to use a comma nor a closing parenthesis as
John Roesler27c754c2019-07-10 15:45:51 -050013947 delimiters.
Willy Tarreau280f42b2018-02-19 15:34:12 +010013948
13949 Example:
13950 tcp-request session set-var(sess.src) src
13951 tcp-request session set-var(sess.dn) ssl_c_s_dn
13952 tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>)
13953 http-request set-header x-hap-sig %[var(txn.sig)]
13954
Willy Tarreau97707872015-01-27 15:12:13 +010013955cpl
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020013956 Takes the input value of type signed integer, applies a ones-complement
13957 (flips all bits) and returns the result as an signed integer.
Willy Tarreau97707872015-01-27 15:12:13 +010013958
Willy Tarreau80599772015-01-20 19:35:24 +010013959crc32([<avalanche>])
13960 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
13961 hash function. Optionally, it is possible to apply a full avalanche hash
13962 function to the output if the optional <avalanche> argument equals 1. This
13963 converter uses the same functions as used by the various hash-based load
13964 balancing algorithms, so it will provide exactly the same results. It is
13965 provided for compatibility with other software which want a CRC32 to be
13966 computed on some input keys, so it follows the most common implementation as
13967 found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
13968 but may provide a better or at least less predictable distribution. It must
13969 not be used for security purposes as a 32-bit hash is trivial to break. See
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010013970 also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive.
13971
13972crc32c([<avalanche>])
13973 Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C
13974 hash function. Optionally, it is possible to apply a full avalanche hash
13975 function to the output if the optional <avalanche> argument equals 1. This
13976 converter uses the same functions as described in RFC4960, Appendix B [8].
13977 It is provided for compatibility with other software which want a CRC32C to be
13978 computed on some input keys. It is slower than the other algorithms and it must
13979 not be used for security purposes as a 32-bit hash is trivial to break. See
13980 also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive.
Willy Tarreau80599772015-01-20 19:35:24 +010013981
David Carlier29b3ca32015-09-25 14:09:21 +010013982da-csv-conv(<prop>[,<prop>*])
David Carlier4542b102015-06-01 13:54:29 +020013983 Asks the DeviceAtlas converter to identify the User Agent string passed on
13984 input, and to emit a string made of the concatenation of the properties
13985 enumerated in argument, delimited by the separator defined by the global
13986 keyword "deviceatlas-property-separator", or by default the pipe character
David Carlier840b0242016-03-16 10:09:55 +000013987 ('|'). There's a limit of 12 different properties imposed by the haproxy
David Carlier4542b102015-06-01 13:54:29 +020013988 configuration language.
13989
13990 Example:
13991 frontend www
Cyril Bonté307ee1e2015-09-28 23:16:06 +020013992 bind *:8881
13993 default_backend servers
David Carlier840b0242016-03-16 10:09:55 +000013994 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 +020013995
Thierry FOURNIER9687c772015-05-07 15:46:29 +020013996debug
13997 This converter is used as debug tool. It dumps on screen the content and the
13998 type of the input sample. The sample is returned as is on its output. This
13999 converter only exists when haproxy was built with debugging enabled.
14000
Willy Tarreau97707872015-01-27 15:12:13 +010014001div(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014002 Divides the input value of type signed integer by <value>, and returns the
14003 result as an signed integer. If <value> is null, the largest unsigned
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014004 integer is returned (typically 2^63-1). <value> can be a numeric value or a
Daniel Schneller0b547052016-03-21 20:46:57 +010014005 variable name. The name of the variable starts with an indication about its
14006 scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014007 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014008 "sess" : the variable is shared with the whole session
14009 "txn" : the variable is shared with the transaction (request and response)
14010 "req" : the variable is shared only during request processing
14011 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014012 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014013 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014014
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014015djb2([<avalanche>])
14016 Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
14017 hash function. Optionally, it is possible to apply a full avalanche hash
14018 function to the output if the optional <avalanche> argument equals 1. This
14019 converter uses the same functions as used by the various hash-based load
14020 balancing algorithms, so it will provide exactly the same results. It is
14021 mostly intended for debugging, but can be used as a stick-table entry to
14022 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010014023 32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c",
14024 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014025
Willy Tarreau97707872015-01-27 15:12:13 +010014026even
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014027 Returns a boolean TRUE if the input value of type signed integer is even
Willy Tarreau97707872015-01-27 15:12:13 +010014028 otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".
14029
Marcin Deranek9631a282018-04-16 14:30:46 +020014030field(<index>,<delimiters>[,<count>])
14031 Extracts the substring at the given index counting from the beginning
14032 (positive index) or from the end (negative index) considering given delimiters
14033 from an input string. Indexes start at 1 or -1 and delimiters are a string
14034 formatted list of chars. Optionally you can specify <count> of fields to
14035 extract (default: 1). Value of 0 indicates extraction of all remaining
14036 fields.
14037
14038 Example :
14039 str(f1_f2_f3__f5),field(5,_) # f5
14040 str(f1_f2_f3__f5),field(2,_,0) # f2_f3__f5
14041 str(f1_f2_f3__f5),field(2,_,2) # f2_f3
14042 str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_
14043 str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3
Emeric Brunf399b0d2014-11-03 17:07:03 +010014044
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014045hex
Davor Ocelice9ed2812017-12-25 17:49:28 +010014046 Converts a binary input sample to a hex string containing two hex digits per
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014047 input byte. It is used to log or transfer hex dumps of some binary input data
Davor Ocelice9ed2812017-12-25 17:49:28 +010014048 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 +020014049 header).
Thierry FOURNIER2f49d6d2014-03-12 15:01:52 +010014050
Dragan Dosen3f957b22017-10-24 09:27:34 +020014051hex2i
14052 Converts a hex string containing two hex digits per input byte to an
John Roesler27c754c2019-07-10 15:45:51 -050014053 integer. If the input value cannot be converted, then zero is returned.
Dragan Dosen3f957b22017-10-24 09:27:34 +020014054
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014055http_date([<offset>])
14056 Converts an integer supposed to contain a date since epoch to a string
14057 representing this date in a format suitable for use in HTTP header fields. If
14058 an offset value is specified, then it is a number of seconds that is added to
14059 the date before the conversion is operated. This is particularly useful to
14060 emit Date header fields, Expires values in responses when combined with a
14061 positive offset, or Last-Modified values when the offset is negative.
Willy Tarreau74ca5042013-06-11 23:12:07 +020014062
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014063in_table(<table>)
14064 Uses the string representation of the input sample to perform a look up in
14065 the specified table. If the key is not found in the table, a boolean false
14066 is returned. Otherwise a boolean true is returned. This can be used to verify
Davor Ocelice9ed2812017-12-25 17:49:28 +010014067 the presence of a certain key in a table tracking some elements (e.g. whether
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014068 or not a source IP address or an Authorization header was already seen).
14069
Tim Duesterhus1478aa72018-01-25 16:24:51 +010014070ipmask(<mask4>, [<mask6>])
14071 Apply a mask to an IP address, and use the result for lookups and storage.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020014072 This can be used to make all hosts within a certain mask to share the same
Tim Duesterhus1478aa72018-01-25 16:24:51 +010014073 table entries and as such use the same server. The mask4 can be passed in
14074 dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can
14075 be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64).
14076 If no mask6 is given IPv6 addresses will fail to convert for backwards
14077 compatibility reasons.
Willy Tarreauffcb2e42014-07-10 16:29:08 +020014078
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014079json([<input-code>])
Davor Ocelice9ed2812017-12-25 17:49:28 +010014080 Escapes the input string and produces an ASCII output string ready to use as a
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014081 JSON string. The converter tries to decode the input string according to the
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020014082 <input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014083 "utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
14084 of errors:
14085 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
14086 bytes, ...)
14087 - invalid range (the decoded value is within a UTF-8 prohibited range),
14088 - code overlong (the value is encoded with more bytes than necessary).
14089
14090 The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
14091 character is greater than 0xffff because the JSON string escape specification
14092 only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
14093 in 4 variants designated by a combination of two suffix letters : "p" for
14094 "permissive" and "s" for "silently ignore". The behaviors of the decoders
14095 are :
Davor Ocelice9ed2812017-12-25 17:49:28 +010014096 - "ascii" : never fails;
14097 - "utf8" : fails on any detected errors;
14098 - "utf8s" : never fails, but removes characters corresponding to errors;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014099 - "utf8p" : accepts and fixes the overlong errors, but fails on any other
Davor Ocelice9ed2812017-12-25 17:49:28 +010014100 error;
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014101 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
14102 characters corresponding to the other errors.
14103
14104 This converter is particularly useful for building properly escaped JSON for
Davor Ocelice9ed2812017-12-25 17:49:28 +010014105 logging to servers which consume JSON-formatted traffic logs.
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014106
14107 Example:
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014108 capture request header Host len 15
Herve COMMOWICK8dfe8632016-08-05 12:01:20 +020014109 capture request header user-agent len 150
14110 log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'
Thierry FOURNIER317e1c42014-08-12 10:20:47 +020014111
14112 Input request from client 127.0.0.1:
14113 GET / HTTP/1.0
14114 User-Agent: Very "Ugly" UA 1/2
14115
14116 Output log:
14117 {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}
14118
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014119language(<value>[,<default>])
14120 Returns the value with the highest q-factor from a list as extracted from the
14121 "accept-language" header using "req.fhdr". Values with no q-factor have a
14122 q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
14123 belong to the list of semi-colon delimited <values> will be considered. The
14124 argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
14125 given list and a default value is provided, it is returned. Note that language
14126 names may have a variant after a dash ('-'). If this variant is present in the
14127 list, it will be matched, but if it is not, only the base language is checked.
14128 The match is case-sensitive, and the output string is always one of those
Davor Ocelice9ed2812017-12-25 17:49:28 +010014129 provided in arguments. The ordering of arguments is meaningless, only the
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014130 ordering of the values in the request counts, as the first value among
14131 multiple sharing the same q-factor is used.
Thierry FOURNIERad903512014-04-11 17:51:01 +020014132
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014133 Example :
Thierry FOURNIERad903512014-04-11 17:51:01 +020014134
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014135 # this configuration switches to the backend matching a
14136 # given language based on the request :
Thierry FOURNIERad903512014-04-11 17:51:01 +020014137
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014138 acl es req.fhdr(accept-language),language(es;fr;en) -m str es
14139 acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
14140 acl en req.fhdr(accept-language),language(es;fr;en) -m str en
14141 use_backend spanish if es
14142 use_backend french if fr
14143 use_backend english if en
14144 default_backend choose_your_language
Thierry FOURNIERad903512014-04-11 17:51:01 +020014145
Willy Tarreau60a2ee72017-12-15 07:13:48 +010014146length
Etienne Carriereed0d24e2017-12-13 13:41:34 +010014147 Get the length of the string. This can only be placed after a string
14148 sample fetch function or after a transformation keyword returning a string
14149 type. The result is of type integer.
14150
Willy Tarreauffcb2e42014-07-10 16:29:08 +020014151lower
14152 Convert a string sample to lower case. This can only be placed after a string
14153 sample fetch function or after a transformation keyword returning a string
14154 type. The result is of type string.
14155
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020014156ltime(<format>[,<offset>])
14157 Converts an integer supposed to contain a date since epoch to a string
14158 representing this date in local time using a format defined by the <format>
14159 string using strftime(3). The purpose is to allow any date format to be used
14160 in logs. An optional <offset> in seconds may be applied to the input date
14161 (positive or negative). See the strftime() man page for the format supported
14162 by your operating system. See also the utime converter.
14163
14164 Example :
14165
14166 # Emit two colons, one with the local time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010014167 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020014168 log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp
14169
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014170map(<map_file>[,<default_value>])
14171map_<match_type>(<map_file>[,<default_value>])
14172map_<match_type>_<output_type>(<map_file>[,<default_value>])
14173 Search the input value from <map_file> using the <match_type> matching method,
14174 and return the associated value converted to the type <output_type>. If the
14175 input value cannot be found in the <map_file>, the converter returns the
14176 <default_value>. If the <default_value> is not set, the converter fails and
14177 acts as if no input value could be fetched. If the <match_type> is not set, it
14178 defaults to "str". Likewise, if the <output_type> is not set, it defaults to
14179 "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
14180 string to another string.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014181
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014182 It is important to avoid overlapping between the keys : IP addresses and
14183 strings are stored in trees, so the first of the finest match will be used.
14184 Other keys are stored in lists, so the first matching occurrence will be used.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014185
Tim Düsterhus4896c442016-11-29 02:15:19 +010014186 The following array contains the list of all map functions available sorted by
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014187 input type, match type and output type.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014188
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014189 input type | match method | output type str | output type int | output type ip
14190 -----------+--------------+-----------------+-----------------+---------------
14191 str | str | map_str | map_str_int | map_str_ip
14192 -----------+--------------+-----------------+-----------------+---------------
Willy Tarreau787a4c02014-05-10 07:55:30 +020014193 str | beg | map_beg | map_beg_int | map_end_ip
14194 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014195 str | sub | map_sub | map_sub_int | map_sub_ip
14196 -----------+--------------+-----------------+-----------------+---------------
14197 str | dir | map_dir | map_dir_int | map_dir_ip
14198 -----------+--------------+-----------------+-----------------+---------------
14199 str | dom | map_dom | map_dom_int | map_dom_ip
14200 -----------+--------------+-----------------+-----------------+---------------
14201 str | end | map_end | map_end_int | map_end_ip
14202 -----------+--------------+-----------------+-----------------+---------------
Ruoshan Huang3c5e3742016-12-02 16:25:31 +080014203 str | reg | map_reg | map_reg_int | map_reg_ip
14204 -----------+--------------+-----------------+-----------------+---------------
14205 str | reg | map_regm | map_reg_int | map_reg_ip
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014206 -----------+--------------+-----------------+-----------------+---------------
14207 int | int | map_int | map_int_int | map_int_ip
14208 -----------+--------------+-----------------+-----------------+---------------
14209 ip | ip | map_ip | map_ip_int | map_ip_ip
14210 -----------+--------------+-----------------+-----------------+---------------
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014211
Thierry Fournier8feaa662016-02-10 22:55:20 +010014212 The special map called "map_regm" expect matching zone in the regular
14213 expression and modify the output replacing back reference (like "\1") by
14214 the corresponding match text.
14215
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014216 The file contains one key + value per line. Lines which start with '#' are
14217 ignored, just like empty lines. Leading tabs and spaces are stripped. The key
14218 is then the first "word" (series of non-space/tabs characters), and the value
14219 is what follows this series of space/tab till the end of the line excluding
14220 trailing spaces/tabs.
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014221
Thierry FOURNIER060762e2014-04-23 13:29:15 +020014222 Example :
14223
14224 # this is a comment and is ignored
14225 2.22.246.0/23 United Kingdom \n
14226 <-><-----------><--><------------><---->
14227 | | | | `- trailing spaces ignored
14228 | | | `---------- value
14229 | | `-------------------- middle spaces ignored
14230 | `---------------------------- key
14231 `------------------------------------ leading spaces ignored
14232
Willy Tarreau97707872015-01-27 15:12:13 +010014233mod(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014234 Divides the input value of type signed integer by <value>, and returns the
14235 remainder as an signed integer. If <value> is null, then zero is returned.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014236 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010014237 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014238 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014239 "sess" : the variable is shared with the whole session
14240 "txn" : the variable is shared with the transaction (request and response)
14241 "req" : the variable is shared only during request processing
14242 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014243 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014244 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014245
14246mul(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014247 Multiplies the input value of type signed integer by <value>, and returns
Thierry FOURNIER00c005c2015-07-08 01:10:21 +020014248 the product as an signed integer. In case of overflow, the largest possible
14249 value for the sign is returned so that the operation doesn't wrap around.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014250 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010014251 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014252 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014253 "sess" : the variable is shared with the whole session
14254 "txn" : the variable is shared with the transaction (request and response)
14255 "req" : the variable is shared only during request processing
14256 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014257 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014258 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014259
Nenad Merdanovicb7e7c472017-03-12 21:56:55 +010014260nbsrv
14261 Takes an input value of type string, interprets it as a backend name and
14262 returns the number of usable servers in that backend. Can be used in places
14263 where we want to look up a backend from a dynamic name, like a result of a
14264 map lookup.
14265
Willy Tarreau97707872015-01-27 15:12:13 +010014266neg
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014267 Takes the input value of type signed integer, computes the opposite value,
14268 and returns the remainder as an signed integer. 0 is identity. This operator
14269 is provided for reversed subtracts : in order to subtract the input from a
14270 constant, simply perform a "neg,add(value)".
Willy Tarreau97707872015-01-27 15:12:13 +010014271
14272not
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014273 Returns a boolean FALSE if the input value of type signed integer is
Willy Tarreau97707872015-01-27 15:12:13 +010014274 non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
Davor Ocelice9ed2812017-12-25 17:49:28 +010014275 used to report true/false for bit testing on input values (e.g. verify the
Willy Tarreau97707872015-01-27 15:12:13 +010014276 absence of a flag).
14277
14278odd
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014279 Returns a boolean TRUE if the input value of type signed integer is odd
Willy Tarreau97707872015-01-27 15:12:13 +010014280 otherwise returns FALSE. It is functionally equivalent to "and(1),bool".
14281
14282or(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014283 Performs a bitwise "OR" between <value> and the input value of type signed
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014284 integer, and returns the result as an signed integer. <value> can be a
Daniel Schneller0b547052016-03-21 20:46:57 +010014285 numeric value or a variable name. The name of the variable starts with an
14286 indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014287 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014288 "sess" : the variable is shared with the whole session
14289 "txn" : the variable is shared with the transaction (request and response)
14290 "req" : the variable is shared only during request processing
14291 "res" : the variable is shared only during response processing
Davor Ocelice9ed2812017-12-25 17:49:28 +010014292 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014293 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014294
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010014295protobuf(<field_number>,[<field_type>])
14296 This extracts the protocol buffers message field in raw mode of an input binary
14297 sample representation of a protocol buffer message with <field_number> as field
14298 number (dotted notation) if <field_type> is not present, or as an integer sample
14299 if this field is present (see also "ungrpc" below).
14300 The list of the authorized types is the following one: "int32", "int64", "uint32",
14301 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
14302 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
14303 "float" for the wire type 5. Note that "string" is considered as a length-delimited
14304 type, so it does not require any <field_type> argument to be extracted.
14305 More information may be found here about the protocol buffers message field types:
14306 https://developers.google.com/protocol-buffers/docs/encoding
14307
Willy Tarreauc4dc3502015-01-23 20:39:28 +010014308regsub(<regex>,<subst>[,<flags>])
Willy Tarreau7eda8492015-01-20 19:47:06 +010014309 Applies a regex-based substitution to the input string. It does the same
14310 operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
14311 default it will replace in the input string the first occurrence of the
14312 largest part matching the regular expression <regex> with the substitution
14313 string <subst>. It is possible to replace all occurrences instead by adding
14314 the flag "g" in the third argument <flags>. It is also possible to make the
14315 regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
14316 string, it is made up from the concatenation of all desired flags. Thus if
14317 both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
14318 It is important to note that due to the current limitations of the
Baptiste Assmann66025d82016-03-06 23:36:48 +010014319 configuration parser, some characters such as closing parenthesis, closing
14320 square brackets or comma are not possible to use in the arguments. The first
14321 use of this converter is to replace certain characters or sequence of
14322 characters with other ones.
Willy Tarreau7eda8492015-01-20 19:47:06 +010014323
14324 Example :
14325
14326 # de-duplicate "/" in header "x-path".
14327 # input: x-path: /////a///b/c/xzxyz/
14328 # output: x-path: /a/b/c/xzxyz/
14329 http-request set-header x-path %[hdr(x-path),regsub(/+,/,g)]
14330
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020014331capture-req(<id>)
14332 Capture the string entry in the request slot <id> and returns the entry as
14333 is. If the slot doesn't exist, the capture fails silently.
14334
14335 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020014336 "http-response capture", "capture.req.hdr" and
14337 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020014338
14339capture-res(<id>)
14340 Capture the string entry in the response slot <id> and returns the entry as
14341 is. If the slot doesn't exist, the capture fails silently.
14342
14343 See also: "declare capture", "http-request capture",
Baptiste Assmann5ac425c2015-10-21 23:13:46 +020014344 "http-response capture", "capture.req.hdr" and
14345 "capture.res.hdr" (sample fetches).
Thierry FOURNIER35ab2752015-05-28 13:22:03 +020014346
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014347sdbm([<avalanche>])
14348 Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
14349 hash function. Optionally, it is possible to apply a full avalanche hash
14350 function to the output if the optional <avalanche> argument equals 1. This
14351 converter uses the same functions as used by the various hash-based load
14352 balancing algorithms, so it will provide exactly the same results. It is
14353 mostly intended for debugging, but can be used as a stick-table entry to
14354 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010014355 32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c",
14356 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014357
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014358set-var(<var name>)
Davor Ocelice9ed2812017-12-25 17:49:28 +010014359 Sets a variable with the input content and returns the content on the output
14360 as-is. The variable keeps the value and the associated input type. The name of
14361 the variable starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014362 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014363 "sess" : the variable is shared with the whole session
14364 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014365 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010014366 "req" : the variable is shared only during request processing,
14367 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014368 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014369 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020014370
Dragan Dosen6e5a9ca2017-10-24 09:18:23 +020014371sha1
14372 Converts a binary input sample to a SHA1 digest. The result is a binary
14373 sample with length of 20 bytes.
14374
Tim Duesterhusca097c12018-04-27 21:18:45 +020014375strcmp(<var>)
14376 Compares the contents of <var> with the input value of type string. Returns
14377 the result as a signed integer compatible with strcmp(3): 0 if both strings
14378 are identical. A value less than 0 if the left string is lexicographically
14379 smaller than the right string or if the left string is shorter. A value greater
14380 than 0 otherwise (right string greater than left string or the right string is
14381 shorter).
14382
14383 Example :
14384
14385 http-request set-var(txn.host) hdr(host)
14386 # Check whether the client is attempting domain fronting.
14387 acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0
14388
14389
Willy Tarreau97707872015-01-27 15:12:13 +010014390sub(<value>)
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014391 Subtracts <value> from the input value of type signed integer, and returns
14392 the result as an signed integer. Note: in order to subtract the input from
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014393 a constant, simply perform a "neg,add(value)". <value> can be a numeric value
Daniel Schneller0b547052016-03-21 20:46:57 +010014394 or a variable name. The name of the variable starts with an indication about
14395 its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014396 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014397 "sess" : the variable is shared with the whole session
14398 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014399 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010014400 "req" : the variable is shared only during request processing,
14401 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014402 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014403 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014404
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014405table_bytes_in_rate(<table>)
14406 Uses the string representation of the input sample to perform a look up in
14407 the specified table. If the key is not found in the table, integer value zero
14408 is returned. Otherwise the converter returns the average client-to-server
14409 bytes rate associated with the input sample in the designated table, measured
14410 in amount of bytes over the period configured in the table. See also the
14411 sc_bytes_in_rate sample fetch keyword.
14412
14413
14414table_bytes_out_rate(<table>)
14415 Uses the string representation of the input sample to perform a look up in
14416 the specified table. If the key is not found in the table, integer value zero
14417 is returned. Otherwise the converter returns the average server-to-client
14418 bytes rate associated with the input sample in the designated table, measured
14419 in amount of bytes over the period configured in the table. See also the
14420 sc_bytes_out_rate sample fetch keyword.
14421
14422table_conn_cnt(<table>)
14423 Uses the string representation of the input sample to perform a look up in
14424 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010014425 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014426 connections associated with the input sample in the designated table. See
14427 also the sc_conn_cnt sample fetch keyword.
14428
14429table_conn_cur(<table>)
14430 Uses the string representation of the input sample to perform a look up in
14431 the specified table. If the key is not found in the table, integer value zero
14432 is returned. Otherwise the converter returns the current amount of concurrent
14433 tracked connections associated with the input sample in the designated table.
14434 See also the sc_conn_cur sample fetch keyword.
14435
14436table_conn_rate(<table>)
14437 Uses the string representation of the input sample to perform a look up in
14438 the specified table. If the key is not found in the table, integer value zero
14439 is returned. Otherwise the converter returns the average incoming connection
14440 rate associated with the input sample in the designated table. See also the
14441 sc_conn_rate sample fetch keyword.
14442
Thierry FOURNIER236657b2015-08-19 08:25:14 +020014443table_gpt0(<table>)
14444 Uses the string representation of the input sample to perform a look up in
14445 the specified table. If the key is not found in the table, boolean value zero
14446 is returned. Otherwise the converter returns the current value of the first
14447 general purpose tag associated with the input sample in the designated table.
14448 See also the sc_get_gpt0 sample fetch keyword.
14449
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014450table_gpc0(<table>)
14451 Uses the string representation of the input sample to perform a look up in
14452 the specified table. If the key is not found in the table, integer value zero
14453 is returned. Otherwise the converter returns the current value of the first
14454 general purpose counter associated with the input sample in the designated
14455 table. See also the sc_get_gpc0 sample fetch keyword.
14456
14457table_gpc0_rate(<table>)
14458 Uses the string representation of the input sample to perform a look up in
14459 the specified table. If the key is not found in the table, integer value zero
14460 is returned. Otherwise the converter returns the frequency which the gpc0
14461 counter was incremented over the configured period in the table, associated
14462 with the input sample in the designated table. See also the sc_get_gpc0_rate
14463 sample fetch keyword.
14464
Frédéric Lécaille6778b272018-01-29 15:22:53 +010014465table_gpc1(<table>)
14466 Uses the string representation of the input sample to perform a look up in
14467 the specified table. If the key is not found in the table, integer value zero
14468 is returned. Otherwise the converter returns the current value of the second
14469 general purpose counter associated with the input sample in the designated
14470 table. See also the sc_get_gpc1 sample fetch keyword.
14471
14472table_gpc1_rate(<table>)
14473 Uses the string representation of the input sample to perform a look up in
14474 the specified table. If the key is not found in the table, integer value zero
14475 is returned. Otherwise the converter returns the frequency which the gpc1
14476 counter was incremented over the configured period in the table, associated
14477 with the input sample in the designated table. See also the sc_get_gpc1_rate
14478 sample fetch keyword.
14479
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014480table_http_err_cnt(<table>)
14481 Uses the string representation of the input sample to perform a look up in
14482 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010014483 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014484 errors associated with the input sample in the designated table. See also the
14485 sc_http_err_cnt sample fetch keyword.
14486
14487table_http_err_rate(<table>)
14488 Uses the string representation of the input sample to perform a look up in
14489 the specified table. If the key is not found in the table, integer value zero
14490 is returned. Otherwise the average rate of HTTP errors associated with the
14491 input sample in the designated table, measured in amount of errors over the
14492 period configured in the table. See also the sc_http_err_rate sample fetch
14493 keyword.
14494
14495table_http_req_cnt(<table>)
14496 Uses the string representation of the input sample to perform a look up in
14497 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010014498 is returned. Otherwise the converter returns the cumulative number of HTTP
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014499 requests associated with the input sample in the designated table. See also
14500 the sc_http_req_cnt sample fetch keyword.
14501
14502table_http_req_rate(<table>)
14503 Uses the string representation of the input sample to perform a look up in
14504 the specified table. If the key is not found in the table, integer value zero
14505 is returned. Otherwise the average rate of HTTP requests associated with the
14506 input sample in the designated table, measured in amount of requests over the
14507 period configured in the table. See also the sc_http_req_rate sample fetch
14508 keyword.
14509
14510table_kbytes_in(<table>)
14511 Uses the string representation of the input sample to perform a look up in
14512 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010014513 is returned. Otherwise the converter returns the cumulative number of client-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014514 to-server data associated with the input sample in the designated table,
14515 measured in kilobytes. The test is currently performed on 32-bit integers,
14516 which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
14517 keyword.
14518
14519table_kbytes_out(<table>)
14520 Uses the string representation of the input sample to perform a look up in
14521 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010014522 is returned. Otherwise the converter returns the cumulative number of server-
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014523 to-client data associated with the input sample in the designated table,
14524 measured in kilobytes. The test is currently performed on 32-bit integers,
14525 which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
14526 keyword.
14527
14528table_server_id(<table>)
14529 Uses the string representation of the input sample to perform a look up in
14530 the specified table. If the key is not found in the table, integer value zero
14531 is returned. Otherwise the converter returns the server ID associated with
14532 the input sample in the designated table. A server ID is associated to a
14533 sample by a "stick" rule when a connection to a server succeeds. A server ID
14534 zero means that no server is associated with this key.
14535
14536table_sess_cnt(<table>)
14537 Uses the string representation of the input sample to perform a look up in
14538 the specified table. If the key is not found in the table, integer value zero
Davor Ocelice9ed2812017-12-25 17:49:28 +010014539 is returned. Otherwise the converter returns the cumulative number of incoming
Willy Tarreaud9f316a2014-07-10 14:03:38 +020014540 sessions associated with the input sample in the designated table. Note that
14541 a session here refers to an incoming connection being accepted by the
14542 "tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
14543 keyword.
14544
14545table_sess_rate(<table>)
14546 Uses the string representation of the input sample to perform a look up in
14547 the specified table. If the key is not found in the table, integer value zero
14548 is returned. Otherwise the converter returns the average incoming session
14549 rate associated with the input sample in the designated table. Note that a
14550 session here refers to an incoming connection being accepted by the
14551 "tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
14552 keyword.
14553
14554table_trackers(<table>)
14555 Uses the string representation of the input sample to perform a look up in
14556 the specified table. If the key is not found in the table, integer value zero
14557 is returned. Otherwise the converter returns the current amount of concurrent
14558 connections tracking the same key as the input sample in the designated
14559 table. It differs from table_conn_cur in that it does not rely on any stored
14560 information but on the table's reference count (the "use" value which is
14561 returned by "show table" on the CLI). This may sometimes be more suited for
14562 layer7 tracking. It can be used to tell a server how many concurrent
14563 connections there are from a given address for example. See also the
14564 sc_trackers sample fetch keyword.
14565
Willy Tarreauffcb2e42014-07-10 16:29:08 +020014566upper
14567 Convert a string sample to upper case. This can only be placed after a string
14568 sample fetch function or after a transformation keyword returning a string
14569 type. The result is of type string.
14570
Willy Tarreau7e913cb2020-04-23 17:54:47 +020014571url_dec([<in_form>])
14572 Takes an url-encoded string provided as input and returns the decoded version
14573 as output. The input and the output are of type string. If the <in_form>
14574 argument is set to a non-zero integer value, the input string is assumed to
14575 be part of a form or query string and the '+' character will be turned into a
14576 space (' '). Otherwise this will only happen after a question mark indicating
14577 a query string ('?').
Thierry FOURNIER82ff3c92015-05-07 15:46:20 +020014578
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010014579ungrpc(<field_number>,[<field_type>])
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010014580 This extracts the protocol buffers message field in raw mode of an input binary
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010014581 sample representation of a gRPC message with <field_number> as field number
14582 (dotted notation) if <field_type> is not present, or as an integer sample if this
14583 field is present.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010014584 The list of the authorized types is the following one: "int32", "int64", "uint32",
14585 "uint64", "sint32", "sint64", "bool", "enum" for the "varint" wire type 0
14586 "fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
14587 "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 +010014588 type, so it does not require any <field_type> argument to be extracted.
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010014589 More information may be found here about the protocol buffers message field types:
14590 https://developers.google.com/protocol-buffers/docs/encoding
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010014591
14592 Example:
14593 // with such a protocol buffer .proto file content adapted from
14594 // https://github.com/grpc/grpc/blob/master/examples/protos/route_guide.proto
14595
14596 message Point {
14597 int32 latitude = 1;
14598 int32 longitude = 2;
14599 }
14600
14601 message PPoint {
14602 Point point = 59;
14603 }
14604
14605 message Rectangle {
14606 // One corner of the rectangle.
14607 PPoint lo = 48;
14608 // The other corner of the rectangle.
14609 PPoint hi = 49;
14610 }
14611
14612 let's say a body request is made of a "Rectangle" object value (two PPoint
14613 protocol buffers messages), the four protocol buffers fields could be
14614 extracted with these "ungrpc" directives:
14615
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010014616 req.body,ungrpc(48.59.1,int32) # "latitude" of "lo" first PPoint
14617 req.body,ungrpc(48.59.2,int32) # "longitude" of "lo" first PPoint
John Roesler27c754c2019-07-10 15:45:51 -050014618 req.body,ungrpc(49.59.1,int32) # "latitude" of "hi" second PPoint
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010014619 req.body,ungrpc(49.59.2,int32) # "longitude" of "hi" second PPoint
14620
Frédéric Lécaille93d33162019-03-06 09:35:59 +010014621 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 +010014622
Frédéric Lécaille93d33162019-03-06 09:35:59 +010014623 req.body,ungrpc(48.59)
Frédéric Lécaille756d97f2019-03-04 19:03:48 +010014624
John Roesler27c754c2019-07-10 15:45:51 -050014625 As a gRPC message is always made of a gRPC header followed by protocol buffers
Frédéric Lécaillebfe61382019-03-06 14:34:36 +010014626 messages, in the previous example the "latitude" of "lo" first PPoint
14627 could be extracted with these equivalent directives:
14628
14629 req.body,ungrpc(48.59),protobuf(1,int32)
14630 req.body,ungrpc(48),protobuf(59.1,int32)
14631 req.body,ungrpc(48),protobuf(59),protobuf(1,int32)
14632
14633 Note that the first convert must be "ungrpc", the remaining ones must be
14634 "protobuf" and only the last one may have or not a second argument to
14635 interpret the previous binary sample.
14636
Frédéric Lécaille50290fb2019-02-27 14:34:51 +010014637
Christopher Faulet85d79c92016-11-09 16:54:56 +010014638unset-var(<var name>)
14639 Unsets a variable if the input content is defined. The name of the variable
14640 starts with an indication about its scope. The scopes allowed are:
14641 "proc" : the variable is shared with the whole process
14642 "sess" : the variable is shared with the whole session
14643 "txn" : the variable is shared with the transaction (request and
14644 response),
14645 "req" : the variable is shared only during request processing,
14646 "res" : the variable is shared only during response processing.
14647 This prefix is followed by a name. The separator is a '.'. The name may only
14648 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
14649
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020014650utime(<format>[,<offset>])
14651 Converts an integer supposed to contain a date since epoch to a string
14652 representing this date in UTC time using a format defined by the <format>
14653 string using strftime(3). The purpose is to allow any date format to be used
14654 in logs. An optional <offset> in seconds may be applied to the input date
14655 (positive or negative). See the strftime() man page for the format supported
14656 by your operating system. See also the ltime converter.
14657
14658 Example :
14659
14660 # Emit two colons, one with the UTC time and another with ip:port
Davor Ocelice9ed2812017-12-25 17:49:28 +010014661 # e.g. 20140710162350 127.0.0.1:57325
Willy Tarreau0dbfdba2014-07-10 16:37:47 +020014662 log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp
14663
Marcin Deranek9631a282018-04-16 14:30:46 +020014664word(<index>,<delimiters>[,<count>])
14665 Extracts the nth word counting from the beginning (positive index) or from
14666 the end (negative index) considering given delimiters from an input string.
14667 Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
Jerome Magnind1fa5fa2020-01-28 13:33:44 +010014668 Delimiters at the beginning or end of the input string are ignored.
Marcin Deranek9631a282018-04-16 14:30:46 +020014669 Optionally you can specify <count> of words to extract (default: 1).
14670 Value of 0 indicates extraction of all remaining words.
14671
14672 Example :
14673 str(f1_f2_f3__f5),word(4,_) # f5
14674 str(f1_f2_f3__f5),word(2,_,0) # f2_f3__f5
14675 str(f1_f2_f3__f5),word(3,_,2) # f3__f5
14676 str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
14677 str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
Jerome Magnind1fa5fa2020-01-28 13:33:44 +010014678 str(/f1/f2/f3/f4),word(1,/) # f1
Emeric Brunc9a0f6d2014-11-25 14:09:01 +010014679
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014680wt6([<avalanche>])
14681 Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
14682 hash function. Optionally, it is possible to apply a full avalanche hash
14683 function to the output if the optional <avalanche> argument equals 1. This
14684 converter uses the same functions as used by the various hash-based load
14685 balancing algorithms, so it will provide exactly the same results. It is
14686 mostly intended for debugging, but can be used as a stick-table entry to
14687 collect rough statistics. It must not be used for security purposes as a
Emmanuel Hocdet50791a72018-03-21 11:19:01 +010014688 32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c",
14689 and the "hash-type" directive.
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020014690
Willy Tarreau97707872015-01-27 15:12:13 +010014691xor(<value>)
14692 Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014693 of type signed integer, and returns the result as an signed integer.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014694 <value> can be a numeric value or a variable name. The name of the variable
Daniel Schneller0b547052016-03-21 20:46:57 +010014695 starts with an indication about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010014696 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010014697 "sess" : the variable is shared with the whole session
14698 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014699 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010014700 "req" : the variable is shared only during request processing,
14701 "res" : the variable is shared only during response processing.
Thierry FOURNIER5d86fae2015-07-07 21:10:16 +020014702 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010014703 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Willy Tarreau97707872015-01-27 15:12:13 +010014704
Thierry FOURNIER01e09742016-12-26 11:46:11 +010014705xxh32([<seed>])
14706 Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
14707 variant of the XXHash hash function. This hash supports a seed which defaults
14708 to zero but a different value maybe passed as the <seed> argument. This hash
14709 is known to be very good and very fast so it can be used to hash URLs and/or
14710 URL parameters for use as stick-table keys to collect statistics with a low
14711 collision rate, though care must be taken as the algorithm is not considered
14712 as cryptographically secure.
14713
14714xxh64([<seed>])
14715 Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
14716 variant of the XXHash hash function. This hash supports a seed which defaults
14717 to zero but a different value maybe passed as the <seed> argument. This hash
14718 is known to be very good and very fast so it can be used to hash URLs and/or
14719 URL parameters for use as stick-table keys to collect statistics with a low
14720 collision rate, though care must be taken as the algorithm is not considered
14721 as cryptographically secure.
14722
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010014723
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200147247.3.2. Fetching samples from internal states
Willy Tarreau74ca5042013-06-11 23:12:07 +020014725--------------------------------------------
14726
14727A first set of sample fetch methods applies to internal information which does
14728not even relate to any client information. These ones are sometimes used with
14729"monitor-fail" directives to report an internal status to external watchers.
14730The sample fetch methods described in this section are usable anywhere.
14731
14732always_false : boolean
14733 Always returns the boolean "false" value. It may be used with ACLs as a
14734 temporary replacement for another one when adjusting configurations.
14735
14736always_true : boolean
14737 Always returns the boolean "true" value. It may be used with ACLs as a
14738 temporary replacement for another one when adjusting configurations.
14739
14740avg_queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010014741 Returns the total number of queued connections of the designated backend
Willy Tarreau74ca5042013-06-11 23:12:07 +020014742 divided by the number of active servers. The current backend is used if no
14743 backend is specified. This is very similar to "queue" except that the size of
14744 the farm is considered, in order to give a more accurate measurement of the
14745 time it may take for a new connection to be processed. The main usage is with
14746 ACL to return a sorry page to new users when it becomes certain they will get
14747 a degraded service, or to pass to the backend servers in a header so that
14748 they decide to work in degraded mode or to disable some functions to speed up
14749 the processing a bit. Note that in the event there would not be any active
14750 server anymore, twice the number of queued connections would be considered as
14751 the measured value. This is a fair estimate, as we expect one server to get
14752 back soon anyway, but we still prefer to send new traffic to another backend
14753 if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
14754 sample fetches.
Krzysztof Piotr Oledzki346f76d2010-01-12 21:59:30 +010014755
Willy Tarreau74ca5042013-06-11 23:12:07 +020014756be_conn([<backend>]) : integer
Willy Tarreaua36af912009-10-10 12:02:45 +020014757 Applies to the number of currently established connections on the backend,
14758 possibly including the connection being evaluated. If no backend name is
14759 specified, the current one is used. But it is also possible to check another
14760 backend. It can be used to use a specific farm when the nominal one is full.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040014761 See also the "fe_conn", "queue", "be_conn_free", and "be_sess_rate" criteria.
14762
14763be_conn_free([<backend>]) : integer
14764 Returns an integer value corresponding to the number of available connections
14765 across available servers in the backend. Queue slots are not included. Backup
14766 servers are also not included, unless all other servers are down. If no
14767 backend name is specified, the current one is used. But it is also possible
14768 to check another backend. It can be used to use a specific farm when the
Patrick Hemmer155e93e2018-06-14 18:01:35 -040014769 nominal one is full. See also the "be_conn", "connslots", and "srv_conn_free"
14770 criteria.
Patrick Hemmer4cdf3ab2018-06-14 17:10:27 -040014771
14772 OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0
14773 (meaning unlimited), then this fetch clearly does not make sense, in which
14774 case the value returned will be -1.
Willy Tarreau6a06a402007-07-15 20:15:28 +020014775
Willy Tarreau74ca5042013-06-11 23:12:07 +020014776be_sess_rate([<backend>]) : integer
14777 Returns an integer value corresponding to the sessions creation rate on the
14778 backend, in number of new sessions per second. This is used with ACLs to
14779 switch to an alternate backend when an expensive or fragile one reaches too
Davor Ocelice9ed2812017-12-25 17:49:28 +010014780 high a session rate, or to limit abuse of service (e.g. prevent sucking of an
Willy Tarreau74ca5042013-06-11 23:12:07 +020014781 online dictionary). It can also be useful to add this element to logs using a
14782 log-format directive.
Willy Tarreaud63335a2010-02-26 12:56:52 +010014783
14784 Example :
14785 # Redirect to an error page if the dictionary is requested too often
14786 backend dynamic
14787 mode http
14788 acl being_scanned be_sess_rate gt 100
14789 redirect location /denied.html if being_scanned
Willy Tarreau0ba27502007-12-24 16:55:16 +010014790
Davor Ocelice9ed2812017-12-25 17:49:28 +010014791bin(<hex>) : bin
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014792 Returns a binary chain. The input is the hexadecimal representation
14793 of the string.
14794
14795bool(<bool>) : bool
14796 Returns a boolean value. <bool> can be 'true', 'false', '1' or '0'.
14797 'false' and '0' are the same. 'true' and '1' are the same.
14798
Willy Tarreau74ca5042013-06-11 23:12:07 +020014799connslots([<backend>]) : integer
14800 Returns an integer value corresponding to the number of connection slots
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030014801 still available in the backend, by totaling the maximum amount of
Willy Tarreau74ca5042013-06-11 23:12:07 +020014802 connections on all servers and the maximum queue size. This is probably only
14803 used with ACLs.
Tait Clarridge7896d522012-12-05 21:39:31 -050014804
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014805 The basic idea here is to be able to measure the number of connection "slots"
Willy Tarreau55165fe2009-05-10 12:02:55 +020014806 still available (connection + queue), so that anything beyond that (intended
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014807 usage; see "use_backend" keyword) can be redirected to a different backend.
14808
Willy Tarreau55165fe2009-05-10 12:02:55 +020014809 'connslots' = number of available server connection slots, + number of
14810 available server queue slots.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014811
Willy Tarreaua36af912009-10-10 12:02:45 +020014812 Note that while "fe_conn" may be used, "connslots" comes in especially
Willy Tarreau55165fe2009-05-10 12:02:55 +020014813 useful when you have a case of traffic going to one single ip, splitting into
Willy Tarreau74ca5042013-06-11 23:12:07 +020014814 multiple backends (perhaps using ACLs to do name-based load balancing) and
Willy Tarreau55165fe2009-05-10 12:02:55 +020014815 you want to be able to differentiate between different backends, and their
Davor Ocelice9ed2812017-12-25 17:49:28 +010014816 available "connslots". Also, whereas "nbsrv" only measures servers that are
Willy Tarreau74ca5042013-06-11 23:12:07 +020014817 actually *down*, this fetch is more fine-grained and looks into the number of
Willy Tarreaua36af912009-10-10 12:02:45 +020014818 available connection slots as well. See also "queue" and "avg_queue".
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014819
Willy Tarreau55165fe2009-05-10 12:02:55 +020014820 OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
14821 of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
Willy Tarreau74ca5042013-06-11 23:12:07 +020014822 then this fetch clearly does not make sense, in which case the value returned
Willy Tarreau55165fe2009-05-10 12:02:55 +020014823 will be -1.
Jeffrey 'jf' Lim5051d7b2008-09-04 01:03:03 +080014824
Willy Tarreau70fe9442018-11-22 16:07:39 +010014825cpu_calls : integer
14826 Returns the number of calls to the task processing the stream or current
14827 request since it was allocated. This number is reset for each new request on
14828 the same connections in case of HTTP keep-alive. This value should usually be
14829 low and stable (around 2 calls for a typically simple request) but may become
14830 high if some processing (compression, caching or analysis) is performed. This
14831 is purely for performance monitoring purposes.
14832
14833cpu_ns_avg : integer
14834 Returns the average number of nanoseconds spent in each call to the task
14835 processing the stream or current request. This number is reset for each new
14836 request on the same connections in case of HTTP keep-alive. This value
14837 indicates the overall cost of processing the request or the connection for
14838 each call. There is no good nor bad value but the time spent in a call
14839 automatically causes latency for other processing (see lat_ns_avg below),
14840 and may affect other connection's apparent response time. Certain operations
14841 like compression, complex regex matching or heavy Lua operations may directly
14842 affect this value, and having it in the logs will make it easier to spot the
14843 faulty processing that needs to be fixed to recover decent performance.
14844 Note: this value is exactly cpu_ns_tot divided by cpu_calls.
14845
14846cpu_ns_tot : integer
14847 Returns the total number of nanoseconds spent in each call to the task
14848 processing the stream or current request. This number is reset for each new
14849 request on the same connections in case of HTTP keep-alive. This value
14850 indicates the overall cost of processing the request or the connection for
14851 each call. There is no good nor bad value but the time spent in a call
14852 automatically causes latency for other processing (see lat_ns_avg below),
14853 induces CPU costs on the machine, and may affect other connection's apparent
14854 response time. Certain operations like compression, complex regex matching or
14855 heavy Lua operations may directly affect this value, and having it in the
14856 logs will make it easier to spot the faulty processing that needs to be fixed
14857 to recover decent performance. The value may be artificially high due to a
14858 high cpu_calls count, for example when processing many HTTP chunks, and for
14859 this reason it is often preferred to log cpu_ns_avg instead.
14860
Willy Tarreau6236d3a2013-07-25 14:28:25 +020014861date([<offset>]) : integer
14862 Returns the current date as the epoch (number of seconds since 01/01/1970).
14863 If an offset value is specified, then it is a number of seconds that is added
14864 to the current date before returning the value. This is particularly useful
14865 to compute relative dates, as both positive and negative offsets are allowed.
Willy Tarreau276fae92013-07-25 14:36:01 +020014866 It is useful combined with the http_date converter.
14867
14868 Example :
14869
14870 # set an expires header to now+1 hour in every response
14871 http-response set-header Expires %[date(3600),http_date]
Willy Tarreau6236d3a2013-07-25 14:28:25 +020014872
Etienne Carrierea792a0a2018-01-17 13:43:24 +010014873date_us : integer
14874 Return the microseconds part of the date (the "second" part is returned by
14875 date sample). This sample is coherent with the date sample as it is comes
14876 from the same timeval structure.
14877
Willy Tarreaud716f9b2017-10-13 11:03:15 +020014878distcc_body(<token>[,<occ>]) : binary
14879 Parses a distcc message and returns the body associated to occurrence #<occ>
14880 of the token <token>. Occurrences start at 1, and when unspecified, any may
14881 match though in practice only the first one is checked for now. This can be
14882 used to extract file names or arguments in files built using distcc through
14883 haproxy. Please refer to distcc's protocol documentation for the complete
14884 list of supported tokens.
14885
14886distcc_param(<token>[,<occ>]) : integer
14887 Parses a distcc message and returns the parameter associated to occurrence
14888 #<occ> of the token <token>. Occurrences start at 1, and when unspecified,
14889 any may match though in practice only the first one is checked for now. This
14890 can be used to extract certain information such as the protocol version, the
14891 file size or the argument in files built using distcc through haproxy.
14892 Another use case consists in waiting for the start of the preprocessed file
14893 contents before connecting to the server to avoid keeping idle connections.
14894 Please refer to distcc's protocol documentation for the complete list of
14895 supported tokens.
14896
14897 Example :
14898 # wait up to 20s for the pre-processed file to be uploaded
14899 tcp-request inspect-delay 20s
14900 tcp-request content accept if { distcc_param(DOTI) -m found }
14901 # send large files to the big farm
14902 use_backend big_farm if { distcc_param(DOTI) gt 1000000 }
14903
Willy Tarreau595ec542013-06-12 21:34:28 +020014904env(<name>) : string
14905 Returns a string containing the value of environment variable <name>. As a
14906 reminder, environment variables are per-process and are sampled when the
14907 process starts. This can be useful to pass some information to a next hop
14908 server, or with ACLs to take specific action when the process is started a
14909 certain way.
14910
14911 Examples :
14912 # Pass the Via header to next hop with the local hostname in it
14913 http-request add-header Via 1.1\ %[env(HOSTNAME)]
14914
14915 # reject cookie-less requests when the STOP environment variable is set
14916 http-request deny if !{ cook(SESSIONID) -m found } { env(STOP) -m found }
14917
Willy Tarreau74ca5042013-06-11 23:12:07 +020014918fe_conn([<frontend>]) : integer
14919 Returns the number of currently established connections on the frontend,
Willy Tarreaud63335a2010-02-26 12:56:52 +010014920 possibly including the connection being evaluated. If no frontend name is
14921 specified, the current one is used. But it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020014922 frontend. It can be used to return a sorry page before hard-blocking, or to
14923 use a specific backend to drain new requests when the farm is considered
Davor Ocelice9ed2812017-12-25 17:49:28 +010014924 full. This is mostly used with ACLs but can also be used to pass some
Willy Tarreau74ca5042013-06-11 23:12:07 +020014925 statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
14926 "fe_sess_rate" fetches.
Willy Tarreaua36af912009-10-10 12:02:45 +020014927
Nenad Merdanovicad9a7e92016-10-03 04:57:37 +020014928fe_req_rate([<frontend>]) : integer
14929 Returns an integer value corresponding to the number of HTTP requests per
14930 second sent to a frontend. This number can differ from "fe_sess_rate" in
14931 situations where client-side keep-alive is enabled.
14932
Willy Tarreau74ca5042013-06-11 23:12:07 +020014933fe_sess_rate([<frontend>]) : integer
14934 Returns an integer value corresponding to the sessions creation rate on the
14935 frontend, in number of new sessions per second. This is used with ACLs to
14936 limit the incoming session rate to an acceptable range in order to prevent
14937 abuse of service at the earliest moment, for example when combined with other
14938 layer 4 ACLs in order to force the clients to wait a bit for the rate to go
14939 down below the limit. It can also be useful to add this element to logs using
14940 a log-format directive. See also the "rate-limit sessions" directive for use
14941 in frontends.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010014942
14943 Example :
14944 # This frontend limits incoming mails to 10/s with a max of 100
14945 # concurrent connections. We accept any connection below 10/s, and
14946 # force excess clients to wait for 100 ms. Since clients are limited to
14947 # 100 max, there cannot be more than 10 incoming mails per second.
14948 frontend mail
14949 bind :25
14950 mode tcp
14951 maxconn 100
14952 acl too_fast fe_sess_rate ge 10
14953 tcp-request inspect-delay 100ms
14954 tcp-request content accept if ! too_fast
14955 tcp-request content accept if WAIT_END
Willy Tarreaud72758d2010-01-12 10:42:19 +010014956
Nenad Merdanovic807a6e72017-03-12 22:00:00 +010014957hostname : string
14958 Returns the system hostname.
14959
Thierry FOURNIER07ee64e2015-07-06 23:43:03 +020014960int(<integer>) : signed integer
14961 Returns a signed integer.
14962
Thierry FOURNIERcc103292015-06-06 19:30:17 +020014963ipv4(<ipv4>) : ipv4
14964 Returns an ipv4.
14965
14966ipv6(<ipv6>) : ipv6
14967 Returns an ipv6.
14968
Willy Tarreau70fe9442018-11-22 16:07:39 +010014969lat_ns_avg : integer
14970 Returns the average number of nanoseconds spent between the moment the task
14971 handling the stream is woken up and the moment it is effectively called. This
14972 number is reset for each new request on the same connections in case of HTTP
14973 keep-alive. This value indicates the overall latency inflicted to the current
14974 request by all other requests being processed in parallel, and is a direct
14975 indicator of perceived performance due to noisy neighbours. In order to keep
14976 the value low, it is possible to reduce the scheduler's run queue depth using
14977 "tune.runqueue-depth", to reduce the number of concurrent events processed at
14978 once using "tune.maxpollevents", to decrease the stream's nice value using
14979 the "nice" option on the "bind" lines or in the frontend, or to look for
14980 other heavy requests in logs (those exhibiting large values of "cpu_ns_avg"),
14981 whose processing needs to be adjusted or fixed. Compression of large buffers
14982 could be a culprit, like heavy regex or long lists of regex.
14983 Note: this value is exactly lat_ns_tot divided by cpu_calls.
14984
14985lat_ns_tot : integer
14986 Returns the total number of nanoseconds spent between the moment the task
14987 handling the stream is woken up and the moment it is effectively called. This
14988 number is reset for each new request on the same connections in case of HTTP
14989 keep-alive. This value indicates the overall latency inflicted to the current
14990 request by all other requests being processed in parallel, and is a direct
14991 indicator of perceived performance due to noisy neighbours. In order to keep
14992 the value low, it is possible to reduce the scheduler's run queue depth using
14993 "tune.runqueue-depth", to reduce the number of concurrent events processed at
14994 once using "tune.maxpollevents", to decrease the stream's nice value using
14995 the "nice" option on the "bind" lines or in the frontend, or to look for
14996 other heavy requests in logs (those exhibiting large values of "cpu_ns_avg"),
14997 whose processing needs to be adjusted or fixed. Compression of large buffers
14998 could be a culprit, like heavy regex or long lists of regex. Note: while it
14999 may intuitively seem that the total latency adds to a transfer time, it is
15000 almost never true because while a task waits for the CPU, network buffers
15001 continue to fill up and the next call will process more at once. The value
15002 may be artificially high due to a high cpu_calls count, for example when
15003 processing many HTTP chunks, and for this reason it is often preferred to log
15004 lat_ns_avg instead, which is a more relevant performance indicator.
15005
Thierry FOURNIERcc103292015-06-06 19:30:17 +020015006meth(<method>) : method
15007 Returns a method.
15008
Willy Tarreau0f30d262014-11-24 16:02:05 +010015009nbproc : integer
15010 Returns an integer value corresponding to the number of processes that were
15011 started (it equals the global "nbproc" setting). This is useful for logging
15012 and debugging purposes.
15013
Willy Tarreau74ca5042013-06-11 23:12:07 +020015014nbsrv([<backend>]) : integer
15015 Returns an integer value corresponding to the number of usable servers of
15016 either the current backend or the named backend. This is mostly used with
15017 ACLs but can also be useful when added to logs. This is normally used to
Willy Tarreaud63335a2010-02-26 12:56:52 +010015018 switch to an alternate backend when the number of servers is too low to
15019 to handle some load. It is useful to report a failure when combined with
15020 "monitor fail".
Willy Tarreau079ff0a2009-03-05 21:34:28 +010015021
Patrick Hemmerfabb24f2018-08-13 14:07:57 -040015022prio_class : integer
15023 Returns the priority class of the current session for http mode or connection
15024 for tcp mode. The value will be that set by the last call to "http-request
15025 set-priority-class" or "tcp-request content set-priority-class".
15026
15027prio_offset : integer
15028 Returns the priority offset of the current session for http mode or
15029 connection for tcp mode. The value will be that set by the last call to
15030 "http-request set-priority-offset" or "tcp-request content
15031 set-priority-offset".
15032
Willy Tarreau0f30d262014-11-24 16:02:05 +010015033proc : integer
15034 Returns an integer value corresponding to the position of the process calling
15035 the function, between 1 and global.nbproc. This is useful for logging and
15036 debugging purposes.
15037
Willy Tarreau74ca5042013-06-11 23:12:07 +020015038queue([<backend>]) : integer
Willy Tarreaud63335a2010-02-26 12:56:52 +010015039 Returns the total number of queued connections of the designated backend,
15040 including all the connections in server queues. If no backend name is
15041 specified, the current one is used, but it is also possible to check another
Willy Tarreau74ca5042013-06-11 23:12:07 +020015042 one. This is useful with ACLs or to pass statistics to backend servers. This
15043 can be used to take actions when queuing goes above a known level, generally
15044 indicating a surge of traffic or a massive slowdown on the servers. One
15045 possible action could be to reject new users but still accept old ones. See
15046 also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
15047
Willy Tarreau84310e22014-02-14 11:59:04 +010015048rand([<range>]) : integer
15049 Returns a random integer value within a range of <range> possible values,
15050 starting at zero. If the range is not specified, it defaults to 2^32, which
15051 gives numbers between 0 and 4294967295. It can be useful to pass some values
15052 needed to take some routing decisions for example, or just for debugging
15053 purposes. This random must not be used for security purposes.
15054
Luca Schimweg77306662019-09-10 15:42:52 +020015055uuid([<version>]) : string
15056 Returns a UUID following the RFC4122 standard. If the version is not
15057 specified, a UUID version 4 (fully random) is returned.
15058 Currently, only version 4 is supported.
15059
Willy Tarreau74ca5042013-06-11 23:12:07 +020015060srv_conn([<backend>/]<server>) : integer
15061 Returns an integer value corresponding to the number of currently established
15062 connections on the designated server, possibly including the connection being
15063 evaluated. If <backend> is omitted, then the server is looked up in the
15064 current backend. It can be used to use a specific farm when one server is
15065 full, or to inform the server about our view of the number of active
Patrick Hemmer155e93e2018-06-14 18:01:35 -040015066 connections with it. See also the "fe_conn", "be_conn", "queue", and
15067 "srv_conn_free" fetch methods.
15068
15069srv_conn_free([<backend>/]<server>) : integer
15070 Returns an integer value corresponding to the number of available connections
15071 on the designated server, possibly including the connection being evaluated.
15072 The value does not include queue slots. If <backend> is omitted, then the
15073 server is looked up in the current backend. It can be used to use a specific
15074 farm when one server is full, or to inform the server about our view of the
15075 number of active connections with it. See also the "be_conn_free" and
15076 "srv_conn" fetch methods.
15077
15078 OTHER CAVEATS AND NOTES: If the server maxconn is 0, then this fetch clearly
15079 does not make sense, in which case the value returned will be -1.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015080
15081srv_is_up([<backend>/]<server>) : boolean
15082 Returns true when the designated server is UP, and false when it is either
15083 DOWN or in maintenance mode. If <backend> is omitted, then the server is
15084 looked up in the current backend. It is mainly used to take action based on
Davor Ocelice9ed2812017-12-25 17:49:28 +010015085 an external status reported via a health check (e.g. a geographical site's
Willy Tarreau74ca5042013-06-11 23:12:07 +020015086 availability). Another possible use which is more of a hack consists in
15087 using dummy servers as boolean variables that can be enabled or disabled from
15088 the CLI, so that rules depending on those ACLs can be tweaked in realtime.
15089
Willy Tarreauff2b7af2017-10-13 11:46:26 +020015090srv_queue([<backend>/]<server>) : integer
15091 Returns an integer value corresponding to the number of connections currently
15092 pending in the designated server's queue. If <backend> is omitted, then the
15093 server is looked up in the current backend. It can sometimes be used together
15094 with the "use-server" directive to force to use a known faster server when it
15095 is not much loaded. See also the "srv_conn", "avg_queue" and "queue" sample
15096 fetch methods.
15097
Willy Tarreau74ca5042013-06-11 23:12:07 +020015098srv_sess_rate([<backend>/]<server>) : integer
15099 Returns an integer corresponding to the sessions creation rate on the
15100 designated server, in number of new sessions per second. If <backend> is
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015101 omitted, then the server is looked up in the current backend. This is mostly
Willy Tarreau74ca5042013-06-11 23:12:07 +020015102 used with ACLs but can make sense with logs too. This is used to switch to an
15103 alternate backend when an expensive or fragile one reaches too high a session
Davor Ocelice9ed2812017-12-25 17:49:28 +010015104 rate, or to limit abuse of service (e.g. prevent latent requests from
Willy Tarreau74ca5042013-06-11 23:12:07 +020015105 overloading servers).
15106
15107 Example :
15108 # Redirect to a separate back
15109 acl srv1_full srv_sess_rate(be1/srv1) gt 50
15110 acl srv2_full srv_sess_rate(be1/srv2) gt 50
15111 use_backend be2 if srv1_full or srv2_full
15112
Willy Tarreau0f30d262014-11-24 16:02:05 +010015113stopping : boolean
15114 Returns TRUE if the process calling the function is currently stopping. This
15115 can be useful for logging, or for relaxing certain checks or helping close
15116 certain connections upon graceful shutdown.
15117
Thierry FOURNIERcc103292015-06-06 19:30:17 +020015118str(<string>) : string
15119 Returns a string.
15120
Willy Tarreau74ca5042013-06-11 23:12:07 +020015121table_avl([<table>]) : integer
15122 Returns the total number of available entries in the current proxy's
15123 stick-table or in the designated stick-table. See also table_cnt.
15124
15125table_cnt([<table>]) : integer
15126 Returns the total number of entries currently in use in the current proxy's
15127 stick-table or in the designated stick-table. See also src_conn_cnt and
15128 table_avl for other entry counting methods.
15129
Christopher Faulet34adb2a2017-11-21 21:45:38 +010015130thread : integer
15131 Returns an integer value corresponding to the position of the thread calling
15132 the function, between 0 and (global.nbthread-1). This is useful for logging
15133 and debugging purposes.
15134
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015135var(<var-name>) : undefined
15136 Returns a variable with the stored type. If the variable is not set, the
Daniel Schneller0b547052016-03-21 20:46:57 +010015137 sample fetch fails. The name of the variable starts with an indication
15138 about its scope. The scopes allowed are:
Christopher Fauletff2613e2016-11-09 11:36:17 +010015139 "proc" : the variable is shared with the whole process
Daniel Schneller0b547052016-03-21 20:46:57 +010015140 "sess" : the variable is shared with the whole session
15141 "txn" : the variable is shared with the transaction (request and
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015142 response),
Daniel Schneller0b547052016-03-21 20:46:57 +010015143 "req" : the variable is shared only during request processing,
15144 "res" : the variable is shared only during response processing.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015145 This prefix is followed by a name. The separator is a '.'. The name may only
Christopher Fauletb71557a2016-10-31 10:49:03 +010015146 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
Thierry FOURNIER4834bc72015-06-06 19:29:07 +020015147
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200151487.3.3. Fetching samples at Layer 4
Willy Tarreau74ca5042013-06-11 23:12:07 +020015149----------------------------------
15150
15151The layer 4 usually describes just the transport layer which in haproxy is
15152closest to the connection, where no content is yet made available. The fetch
15153methods described here are usable as low as the "tcp-request connection" rule
15154sets unless they require some future information. Those generally include
15155TCP/IP addresses and ports, as well as elements from stick-tables related to
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015156the incoming connection. For retrieving a value from a sticky counters, the
15157counter number can be explicitly set as 0, 1, or 2 using the pre-defined
Moemen MHEDHBI9cf46342018-09-25 17:50:53 +020015158"sc0_", "sc1_", or "sc2_" prefix. These three pre-defined prefixes can only be
15159used if MAX_SESS_STKCTR value does not exceed 3, otherwise the counter number
15160can be specified as the first integer argument when using the "sc_" prefix.
15161Starting from "sc_0" to "sc_N" where N is (MAX_SESS_STKCTR-1). An optional
15162table may be specified with the "sc*" form, in which case the currently
15163tracked key will be looked up into this alternate table instead of the table
15164currently being tracked.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015165
Jérôme Magnin35e53a62019-01-16 14:38:37 +010015166bc_http_major : integer
Jérôme Magnin86577422018-12-07 09:03:11 +010015167 Returns the backend connection's HTTP major version encoding, which may be 1
15168 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
15169 encoding and not the version present in the request header.
15170
Willy Tarreau74ca5042013-06-11 23:12:07 +020015171be_id : integer
15172 Returns an integer containing the current backend's id. It can be used in
15173 frontends with responses to check which backend processed the request.
15174
Marcin Deranekd2471c22016-12-12 14:08:05 +010015175be_name : string
15176 Returns a string containing the current backend's name. It can be used in
15177 frontends with responses to check which backend processed the request.
15178
Willy Tarreau74ca5042013-06-11 23:12:07 +020015179dst : ip
15180 This is the destination IPv4 address of the connection on the client side,
15181 which is the address the client connected to. It can be useful when running
15182 in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
15183 On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
Willy Tarreau64ded3d2019-01-23 10:02:15 +010015184 RFC 4291. When the incoming connection passed through address translation or
15185 redirection involving connection tracking, the original destination address
15186 before the redirection will be reported. On Linux systems, the source and
15187 destination may seldom appear reversed if the nf_conntrack_tcp_loose sysctl
15188 is set, because a late response may reopen a timed out connection and switch
15189 what is believed to be the source and the destination.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015190
15191dst_conn : integer
15192 Returns an integer value corresponding to the number of currently established
15193 connections on the same socket including the one being evaluated. It is
15194 normally used with ACLs but can as well be used to pass the information to
15195 servers in an HTTP header or in logs. It can be used to either return a sorry
15196 page before hard-blocking, or to use a specific backend to drain new requests
15197 when the socket is considered saturated. This offers the ability to assign
15198 different limits to different listening ports or addresses. See also the
15199 "fe_conn" and "be_conn" fetches.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015200
Willy Tarreau16e01562016-08-09 16:46:18 +020015201dst_is_local : boolean
15202 Returns true if the destination address of the incoming connection is local
15203 to the system, or false if the address doesn't exist on the system, meaning
15204 that it was intercepted in transparent mode. It can be useful to apply
15205 certain rules by default to forwarded traffic and other rules to the traffic
Davor Ocelice9ed2812017-12-25 17:49:28 +010015206 targeting the real address of the machine. For example the stats page could
Willy Tarreau16e01562016-08-09 16:46:18 +020015207 be delivered only on this address, or SSH access could be locally redirected.
15208 Please note that the check involves a few system calls, so it's better to do
15209 it only once per connection.
15210
Willy Tarreau74ca5042013-06-11 23:12:07 +020015211dst_port : integer
15212 Returns an integer value corresponding to the destination TCP port of the
15213 connection on the client side, which is the port the client connected to.
15214 This might be used when running in transparent mode, when assigning dynamic
15215 ports to some clients for a whole application session, to stick all users to
15216 a same server, or to pass the destination port information to a server using
15217 an HTTP header.
15218
Willy Tarreau60ca10a2017-08-18 15:26:54 +020015219fc_http_major : integer
15220 Reports the front connection's HTTP major version encoding, which may be 1
15221 for HTTP/0.9 to HTTP/1.1 or 2 for HTTP/2. Note, this is based on the on-wire
15222 encoding and not on the version present in the request header.
15223
Emeric Brun4f603012017-01-05 15:11:44 +010015224fc_rcvd_proxy : boolean
15225 Returns true if the client initiated the connection with a PROXY protocol
15226 header.
15227
Thierry Fournier / OZON.IO6310bef2016-07-24 20:16:50 +020015228fc_rtt(<unit>) : integer
15229 Returns the Round Trip Time (RTT) measured by the kernel for the client
15230 connection. <unit> is facultative, by default the unit is milliseconds. <unit>
15231 can be set to "ms" for milliseconds or "us" for microseconds. If the server
15232 connection is not established, if the connection is not TCP or if the
15233 operating system does not support TCP_INFO, for example Linux kernels before
15234 2.4, the sample fetch fails.
15235
15236fc_rttvar(<unit>) : integer
15237 Returns the Round Trip Time (RTT) variance measured by the kernel for the
15238 client connection. <unit> is facultative, by default the unit is milliseconds.
15239 <unit> can be set to "ms" for milliseconds or "us" for microseconds. If the
15240 server connection is not established, if the connection is not TCP or if the
15241 operating system does not support TCP_INFO, for example Linux kernels before
15242 2.4, the sample fetch fails.
15243
Christopher Faulet297df182019-10-17 14:40:48 +020015244fc_unacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070015245 Returns the unacked counter measured by the kernel for the client connection.
15246 If the server connection is not established, if the connection is not TCP or
15247 if the operating system does not support TCP_INFO, for example Linux kernels
15248 before 2.4, the sample fetch fails.
15249
Christopher Faulet297df182019-10-17 14:40:48 +020015250fc_sacked : integer
Joe Williams30fcd392016-08-10 07:06:44 -070015251 Returns the sacked counter measured by the kernel for the client connection.
15252 If the server connection is not established, if the connection is not TCP or
15253 if the operating system does not support TCP_INFO, for example Linux kernels
15254 before 2.4, the sample fetch fails.
15255
Christopher Faulet297df182019-10-17 14:40:48 +020015256fc_retrans : integer
Joe Williams30fcd392016-08-10 07:06:44 -070015257 Returns the retransmits counter measured by the kernel for the client
15258 connection. If the server connection is not established, if the connection is
15259 not TCP or if the operating system does not support TCP_INFO, for example
15260 Linux kernels before 2.4, the sample fetch fails.
15261
Christopher Faulet297df182019-10-17 14:40:48 +020015262fc_fackets : integer
Joe Williams30fcd392016-08-10 07:06:44 -070015263 Returns the fack counter measured by the kernel for the client
15264 connection. If the server connection is not established, if the connection is
15265 not TCP or if the operating system does not support TCP_INFO, for example
15266 Linux kernels before 2.4, the sample fetch fails.
15267
Christopher Faulet297df182019-10-17 14:40:48 +020015268fc_lost : integer
Joe Williams30fcd392016-08-10 07:06:44 -070015269 Returns the lost counter measured by the kernel for the client
15270 connection. If the server connection is not established, if the connection is
15271 not TCP or if the operating system does not support TCP_INFO, for example
15272 Linux kernels before 2.4, the sample fetch fails.
15273
Christopher Faulet297df182019-10-17 14:40:48 +020015274fc_reordering : integer
Joe Williams30fcd392016-08-10 07:06:44 -070015275 Returns the reordering counter measured by the kernel for the client
15276 connection. If the server connection is not established, if the connection is
15277 not TCP or if the operating system does not support TCP_INFO, for example
15278 Linux kernels before 2.4, the sample fetch fails.
15279
Marcin Deranek9a66dfb2018-04-13 14:37:50 +020015280fe_defbe : string
15281 Returns a string containing the frontend's default backend name. It can be
15282 used in frontends to check which backend will handle requests by default.
15283
Willy Tarreau74ca5042013-06-11 23:12:07 +020015284fe_id : integer
15285 Returns an integer containing the current frontend's id. It can be used in
Marcin Deranek6e413ed2016-12-13 12:40:01 +010015286 backends to check from which frontend it was called, or to stick all users
Willy Tarreau74ca5042013-06-11 23:12:07 +020015287 coming via a same frontend to the same server.
15288
Marcin Deranekd2471c22016-12-12 14:08:05 +010015289fe_name : string
15290 Returns a string containing the current frontend's name. It can be used in
15291 backends to check from which frontend it was called, or to stick all users
15292 coming via a same frontend to the same server.
15293
Cyril Bonté62ba8702014-04-22 23:52:25 +020015294sc_bytes_in_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015295sc0_bytes_in_rate([<table>]) : integer
15296sc1_bytes_in_rate([<table>]) : integer
15297sc2_bytes_in_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015298 Returns the average client-to-server bytes rate from the currently tracked
15299 counters, measured in amount of bytes over the period configured in the
15300 table. See also src_bytes_in_rate.
15301
Cyril Bonté62ba8702014-04-22 23:52:25 +020015302sc_bytes_out_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015303sc0_bytes_out_rate([<table>]) : integer
15304sc1_bytes_out_rate([<table>]) : integer
15305sc2_bytes_out_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015306 Returns the average server-to-client bytes rate from the currently tracked
15307 counters, measured in amount of bytes over the period configured in the
15308 table. See also src_bytes_out_rate.
15309
Cyril Bonté62ba8702014-04-22 23:52:25 +020015310sc_clr_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015311sc0_clr_gpc0([<table>]) : integer
15312sc1_clr_gpc0([<table>]) : integer
15313sc2_clr_gpc0([<table>]) : integer
Willy Tarreauf73cd112011-08-13 01:45:16 +020015314 Clears the first General Purpose Counter associated to the currently tracked
15315 counters, and returns its previous value. Before the first invocation, the
Willy Tarreau869948b2013-01-04 14:14:57 +010015316 stored value is zero, so first invocation will always return zero. This is
15317 typically used as a second ACL in an expression in order to mark a connection
15318 when a first ACL was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020015319
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015320 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020015321 # block if 5 consecutive requests continue to come faster than 10 sess
15322 # per second, and reset the counter as soon as the traffic slows down.
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015323 acl abuse sc0_http_req_rate gt 10
15324 acl kill sc0_inc_gpc0 gt 5
15325 acl save sc0_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020015326 tcp-request connection accept if !abuse save
15327 tcp-request connection reject if abuse kill
15328
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015329sc_clr_gpc1(<ctr>[,<table>]) : integer
15330sc0_clr_gpc1([<table>]) : integer
15331sc1_clr_gpc1([<table>]) : integer
15332sc2_clr_gpc1([<table>]) : integer
15333 Clears the second General Purpose Counter associated to the currently tracked
15334 counters, and returns its previous value. Before the first invocation, the
15335 stored value is zero, so first invocation will always return zero. This is
15336 typically used as a second ACL in an expression in order to mark a connection
15337 when a first ACL was verified.
15338
Cyril Bonté62ba8702014-04-22 23:52:25 +020015339sc_conn_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015340sc0_conn_cnt([<table>]) : integer
15341sc1_conn_cnt([<table>]) : integer
15342sc2_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015343 Returns the cumulative number of incoming connections from currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020015344 counters. See also src_conn_cnt.
15345
Cyril Bonté62ba8702014-04-22 23:52:25 +020015346sc_conn_cur(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015347sc0_conn_cur([<table>]) : integer
15348sc1_conn_cur([<table>]) : integer
15349sc2_conn_cur([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015350 Returns the current amount of concurrent connections tracking the same
15351 tracked counters. This number is automatically incremented when tracking
15352 begins and decremented when tracking stops. See also src_conn_cur.
15353
Cyril Bonté62ba8702014-04-22 23:52:25 +020015354sc_conn_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015355sc0_conn_rate([<table>]) : integer
15356sc1_conn_rate([<table>]) : integer
15357sc2_conn_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015358 Returns the average connection rate from the currently tracked counters,
15359 measured in amount of connections over the period configured in the table.
15360 See also src_conn_rate.
15361
Cyril Bonté62ba8702014-04-22 23:52:25 +020015362sc_get_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015363sc0_get_gpc0([<table>]) : integer
15364sc1_get_gpc0([<table>]) : integer
15365sc2_get_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015366 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015367 currently tracked counters. See also src_get_gpc0 and sc/sc0/sc1/sc2_inc_gpc0.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020015368
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015369sc_get_gpc1(<ctr>[,<table>]) : integer
15370sc0_get_gpc1([<table>]) : integer
15371sc1_get_gpc1([<table>]) : integer
15372sc2_get_gpc1([<table>]) : integer
15373 Returns the value of the second General Purpose Counter associated to the
15374 currently tracked counters. See also src_get_gpc1 and sc/sc0/sc1/sc2_inc_gpc1.
15375
Thierry FOURNIER236657b2015-08-19 08:25:14 +020015376sc_get_gpt0(<ctr>[,<table>]) : integer
15377sc0_get_gpt0([<table>]) : integer
15378sc1_get_gpt0([<table>]) : integer
15379sc2_get_gpt0([<table>]) : integer
15380 Returns the value of the first General Purpose Tag associated to the
15381 currently tracked counters. See also src_get_gpt0.
15382
Cyril Bonté62ba8702014-04-22 23:52:25 +020015383sc_gpc0_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015384sc0_gpc0_rate([<table>]) : integer
15385sc1_gpc0_rate([<table>]) : integer
15386sc2_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020015387 Returns the average increment rate of the first General Purpose Counter
15388 associated to the currently tracked counters. It reports the frequency
15389 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015390 src_gpc0_rate, sc/sc0/sc1/sc2_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
15391 that the "gpc0_rate" counter must be stored in the stick-table for a value to
15392 be returned, as "gpc0" only holds the event count.
Willy Tarreaue9656522010-08-17 15:40:09 +020015393
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015394sc_gpc1_rate(<ctr>[,<table>]) : integer
15395sc0_gpc1_rate([<table>]) : integer
15396sc1_gpc1_rate([<table>]) : integer
15397sc2_gpc1_rate([<table>]) : integer
15398 Returns the average increment rate of the second General Purpose Counter
15399 associated to the currently tracked counters. It reports the frequency
15400 which the gpc1 counter was incremented over the configured period. See also
15401 src_gpcA_rate, sc/sc0/sc1/sc2_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
15402 that the "gpc1_rate" counter must be stored in the stick-table for a value to
15403 be returned, as "gpc1" only holds the event count.
15404
Cyril Bonté62ba8702014-04-22 23:52:25 +020015405sc_http_err_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015406sc0_http_err_cnt([<table>]) : integer
15407sc1_http_err_cnt([<table>]) : integer
15408sc2_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015409 Returns the cumulative number of HTTP errors from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020015410 counters. This includes the both request errors and 4xx error responses.
15411 See also src_http_err_cnt.
15412
Cyril Bonté62ba8702014-04-22 23:52:25 +020015413sc_http_err_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015414sc0_http_err_rate([<table>]) : integer
15415sc1_http_err_rate([<table>]) : integer
15416sc2_http_err_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015417 Returns the average rate of HTTP errors from the currently tracked counters,
15418 measured in amount of errors over the period configured in the table. This
15419 includes the both request errors and 4xx error responses. See also
15420 src_http_err_rate.
15421
Cyril Bonté62ba8702014-04-22 23:52:25 +020015422sc_http_req_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015423sc0_http_req_cnt([<table>]) : integer
15424sc1_http_req_cnt([<table>]) : integer
15425sc2_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015426 Returns the cumulative number of HTTP requests from the currently tracked
Willy Tarreaue9656522010-08-17 15:40:09 +020015427 counters. This includes every started request, valid or not. See also
15428 src_http_req_cnt.
15429
Cyril Bonté62ba8702014-04-22 23:52:25 +020015430sc_http_req_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015431sc0_http_req_rate([<table>]) : integer
15432sc1_http_req_rate([<table>]) : integer
15433sc2_http_req_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015434 Returns the average rate of HTTP requests from the currently tracked
15435 counters, measured in amount of requests over the period configured in
15436 the table. This includes every started request, valid or not. See also
15437 src_http_req_rate.
15438
Cyril Bonté62ba8702014-04-22 23:52:25 +020015439sc_inc_gpc0(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015440sc0_inc_gpc0([<table>]) : integer
15441sc1_inc_gpc0([<table>]) : integer
15442sc2_inc_gpc0([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015443 Increments the first General Purpose Counter associated to the currently
Willy Tarreau869948b2013-01-04 14:14:57 +010015444 tracked counters, and returns its new value. Before the first invocation,
15445 the stored value is zero, so first invocation will increase it to 1 and will
15446 return 1. This is typically used as a second ACL in an expression in order
15447 to mark a connection when a first ACL was verified :
Willy Tarreaue9656522010-08-17 15:40:09 +020015448
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015449 Example:
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015450 acl abuse sc0_http_req_rate gt 10
15451 acl kill sc0_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020015452 tcp-request connection reject if abuse kill
15453
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015454sc_inc_gpc1(<ctr>[,<table>]) : integer
15455sc0_inc_gpc1([<table>]) : integer
15456sc1_inc_gpc1([<table>]) : integer
15457sc2_inc_gpc1([<table>]) : integer
15458 Increments the second General Purpose Counter associated to the currently
15459 tracked counters, and returns its new value. Before the first invocation,
15460 the stored value is zero, so first invocation will increase it to 1 and will
15461 return 1. This is typically used as a second ACL in an expression in order
15462 to mark a connection when a first ACL was verified.
15463
Cyril Bonté62ba8702014-04-22 23:52:25 +020015464sc_kbytes_in(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015465sc0_kbytes_in([<table>]) : integer
15466sc1_kbytes_in([<table>]) : integer
15467sc2_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020015468 Returns the total amount of client-to-server data from the currently tracked
15469 counters, measured in kilobytes. The test is currently performed on 32-bit
15470 integers, which limits values to 4 terabytes. See also src_kbytes_in.
Willy Tarreaue9656522010-08-17 15:40:09 +020015471
Cyril Bonté62ba8702014-04-22 23:52:25 +020015472sc_kbytes_out(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015473sc0_kbytes_out([<table>]) : integer
15474sc1_kbytes_out([<table>]) : integer
15475sc2_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020015476 Returns the total amount of server-to-client data from the currently tracked
15477 counters, measured in kilobytes. The test is currently performed on 32-bit
15478 integers, which limits values to 4 terabytes. See also src_kbytes_out.
Willy Tarreaue9656522010-08-17 15:40:09 +020015479
Cyril Bonté62ba8702014-04-22 23:52:25 +020015480sc_sess_cnt(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015481sc0_sess_cnt([<table>]) : integer
15482sc1_sess_cnt([<table>]) : integer
15483sc2_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015484 Returns the cumulative number of incoming connections that were transformed
Willy Tarreaue9656522010-08-17 15:40:09 +020015485 into sessions, which means that they were accepted by a "tcp-request
15486 connection" rule, from the currently tracked counters. A backend may count
15487 more sessions than connections because each connection could result in many
Jamie Gloudonaaa21002012-08-25 00:18:33 -040015488 backend sessions if some HTTP keep-alive is performed over the connection
Willy Tarreaue9656522010-08-17 15:40:09 +020015489 with the client. See also src_sess_cnt.
15490
Cyril Bonté62ba8702014-04-22 23:52:25 +020015491sc_sess_rate(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015492sc0_sess_rate([<table>]) : integer
15493sc1_sess_rate([<table>]) : integer
15494sc2_sess_rate([<table>]) : integer
Willy Tarreaue9656522010-08-17 15:40:09 +020015495 Returns the average session rate from the currently tracked counters,
15496 measured in amount of sessions over the period configured in the table. A
15497 session is a connection that got past the early "tcp-request connection"
15498 rules. A backend may count more sessions than connections because each
15499 connection could result in many backend sessions if some HTTP keep-alive is
Jamie Gloudonaaa21002012-08-25 00:18:33 -040015500 performed over the connection with the client. See also src_sess_rate.
Willy Tarreaue9656522010-08-17 15:40:09 +020015501
Cyril Bonté62ba8702014-04-22 23:52:25 +020015502sc_tracked(<ctr>[,<table>]) : boolean
Willy Tarreau0f791d42013-07-23 19:56:43 +020015503sc0_tracked([<table>]) : boolean
15504sc1_tracked([<table>]) : boolean
15505sc2_tracked([<table>]) : boolean
Willy Tarreau6f1615f2013-06-03 15:15:22 +020015506 Returns true if the designated session counter is currently being tracked by
15507 the current session. This can be useful when deciding whether or not we want
15508 to set some values in a header passed to the server.
15509
Cyril Bonté62ba8702014-04-22 23:52:25 +020015510sc_trackers(<ctr>[,<table>]) : integer
Willy Tarreau0f791d42013-07-23 19:56:43 +020015511sc0_trackers([<table>]) : integer
15512sc1_trackers([<table>]) : integer
15513sc2_trackers([<table>]) : integer
Willy Tarreau2406db42012-12-09 12:16:43 +010015514 Returns the current amount of concurrent connections tracking the same
15515 tracked counters. This number is automatically incremented when tracking
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015516 begins and decremented when tracking stops. It differs from sc0_conn_cur in
Willy Tarreau2406db42012-12-09 12:16:43 +010015517 that it does not rely on any stored information but on the table's reference
15518 count (the "use" value which is returned by "show table" on the CLI). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020015519 may sometimes be more suited for layer7 tracking. It can be used to tell a
15520 server how many concurrent connections there are from a given address for
15521 example.
Willy Tarreau2406db42012-12-09 12:16:43 +010015522
Willy Tarreau74ca5042013-06-11 23:12:07 +020015523so_id : integer
15524 Returns an integer containing the current listening socket's id. It is useful
15525 in frontends involving many "bind" lines, or to stick all users coming via a
15526 same socket to the same server.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015527
Jerome Magnin28b90332020-03-27 22:08:40 +010015528so_name : string
15529 Returns a string containing the current listening socket's name, as defined
15530 with name on a "bind" line. It can serve the same purposes as so_id but with
15531 strings instead of integers.
15532
Willy Tarreau74ca5042013-06-11 23:12:07 +020015533src : ip
Davor Ocelice9ed2812017-12-25 17:49:28 +010015534 This is the source IPv4 address of the client of the session. It is of type
Willy Tarreau74ca5042013-06-11 23:12:07 +020015535 IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
15536 mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
15537 TCP-level source address which is used, and not the address of a client
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010015538 behind a proxy. However if the "accept-proxy" or "accept-netscaler-cip" bind
15539 directive is used, it can be the address of a client behind another
15540 PROXY-protocol compatible component for all rule sets except
Willy Tarreau64ded3d2019-01-23 10:02:15 +010015541 "tcp-request connection" which sees the real address. When the incoming
15542 connection passed through address translation or redirection involving
15543 connection tracking, the original destination address before the redirection
15544 will be reported. On Linux systems, the source and destination may seldom
15545 appear reversed if the nf_conntrack_tcp_loose sysctl is set, because a late
15546 response may reopen a timed out connection and switch what is believed to be
15547 the source and the destination.
Willy Tarreaud63335a2010-02-26 12:56:52 +010015548
Thierry FOURNIERd5f624d2013-11-26 11:52:33 +010015549 Example:
15550 # add an HTTP header in requests with the originating address' country
15551 http-request set-header X-Country %[src,map_ip(geoip.lst)]
15552
Willy Tarreau74ca5042013-06-11 23:12:07 +020015553src_bytes_in_rate([<table>]) : integer
15554 Returns the average bytes rate from the incoming connection's source address
15555 in the current proxy's stick-table or in the designated stick-table, measured
15556 in amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015557 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_in_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015558
Willy Tarreau74ca5042013-06-11 23:12:07 +020015559src_bytes_out_rate([<table>]) : integer
15560 Returns the average bytes rate to the incoming connection's source address in
15561 the current proxy's stick-table or in the designated stick-table, measured in
Willy Tarreauc9705a12010-07-27 20:05:50 +020015562 amount of bytes over the period configured in the table. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015563 not found, zero is returned. See also sc/sc0/sc1/sc2_bytes_out_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015564
Willy Tarreau74ca5042013-06-11 23:12:07 +020015565src_clr_gpc0([<table>]) : integer
15566 Clears the first General Purpose Counter associated to the incoming
15567 connection's source address in the current proxy's stick-table or in the
15568 designated stick-table, and returns its previous value. If the address is not
15569 found, an entry is created and 0 is returned. This is typically used as a
15570 second ACL in an expression in order to mark a connection when a first ACL
15571 was verified :
Willy Tarreauf73cd112011-08-13 01:45:16 +020015572
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015573 Example:
Willy Tarreauf73cd112011-08-13 01:45:16 +020015574 # block if 5 consecutive requests continue to come faster than 10 sess
15575 # per second, and reset the counter as soon as the traffic slows down.
15576 acl abuse src_http_req_rate gt 10
15577 acl kill src_inc_gpc0 gt 5
Willy Tarreau869948b2013-01-04 14:14:57 +010015578 acl save src_clr_gpc0 ge 0
Willy Tarreauf73cd112011-08-13 01:45:16 +020015579 tcp-request connection accept if !abuse save
15580 tcp-request connection reject if abuse kill
15581
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015582src_clr_gpc1([<table>]) : integer
15583 Clears the second General Purpose Counter associated to the incoming
15584 connection's source address in the current proxy's stick-table or in the
15585 designated stick-table, and returns its previous value. If the address is not
15586 found, an entry is created and 0 is returned. This is typically used as a
15587 second ACL in an expression in order to mark a connection when a first ACL
15588 was verified.
15589
Willy Tarreau74ca5042013-06-11 23:12:07 +020015590src_conn_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015591 Returns the cumulative number of connections initiated from the current
Willy Tarreau74ca5042013-06-11 23:12:07 +020015592 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020015593 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015594 See also sc/sc0/sc1/sc2_conn_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015595
Willy Tarreau74ca5042013-06-11 23:12:07 +020015596src_conn_cur([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020015597 Returns the current amount of concurrent connections initiated from the
Willy Tarreau74ca5042013-06-11 23:12:07 +020015598 current incoming connection's source address in the current proxy's
15599 stick-table or in the designated stick-table. If the address is not found,
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015600 zero is returned. See also sc/sc0/sc1/sc2_conn_cur.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015601
Willy Tarreau74ca5042013-06-11 23:12:07 +020015602src_conn_rate([<table>]) : integer
15603 Returns the average connection rate from the incoming connection's source
15604 address in the current proxy's stick-table or in the designated stick-table,
15605 measured in amount of connections over the period configured in the table. If
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015606 the address is not found, zero is returned. See also sc/sc0/sc1/sc2_conn_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015607
Willy Tarreau74ca5042013-06-11 23:12:07 +020015608src_get_gpc0([<table>]) : integer
Willy Tarreauc9705a12010-07-27 20:05:50 +020015609 Returns the value of the first General Purpose Counter associated to the
Willy Tarreau74ca5042013-06-11 23:12:07 +020015610 incoming connection's source address in the current proxy's stick-table or in
Willy Tarreauc9705a12010-07-27 20:05:50 +020015611 the designated stick-table. If the address is not found, zero is returned.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015612 See also sc/sc0/sc1/sc2_get_gpc0 and src_inc_gpc0.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015613
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015614src_get_gpc1([<table>]) : integer
15615 Returns the value of the second General Purpose Counter associated to the
15616 incoming connection's source address in the current proxy's stick-table or in
15617 the designated stick-table. If the address is not found, zero is returned.
15618 See also sc/sc0/sc1/sc2_get_gpc1 and src_inc_gpc1.
15619
Thierry FOURNIER236657b2015-08-19 08:25:14 +020015620src_get_gpt0([<table>]) : integer
15621 Returns the value of the first General Purpose Tag associated to the
15622 incoming connection's source address in the current proxy's stick-table or in
15623 the designated stick-table. If the address is not found, zero is returned.
15624 See also sc/sc0/sc1/sc2_get_gpt0.
15625
Willy Tarreau74ca5042013-06-11 23:12:07 +020015626src_gpc0_rate([<table>]) : integer
Willy Tarreauba2ffd12013-05-29 15:54:14 +020015627 Returns the average increment rate of the first General Purpose Counter
Willy Tarreau74ca5042013-06-11 23:12:07 +020015628 associated to the incoming connection's source address in the current proxy's
Willy Tarreauba2ffd12013-05-29 15:54:14 +020015629 stick-table or in the designated stick-table. It reports the frequency
15630 which the gpc0 counter was incremented over the configured period. See also
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015631 sc/sc0/sc1/sc2_gpc0_rate, src_get_gpc0, and sc/sc0/sc1/sc2_inc_gpc0. Note
15632 that the "gpc0_rate" counter must be stored in the stick-table for a value to
15633 be returned, as "gpc0" only holds the event count.
Willy Tarreauba2ffd12013-05-29 15:54:14 +020015634
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015635src_gpc1_rate([<table>]) : integer
15636 Returns the average increment rate of the second General Purpose Counter
15637 associated to the incoming connection's source address in the current proxy's
15638 stick-table or in the designated stick-table. It reports the frequency
15639 which the gpc1 counter was incremented over the configured period. See also
15640 sc/sc0/sc1/sc2_gpc1_rate, src_get_gpc1, and sc/sc0/sc1/sc2_inc_gpc1. Note
15641 that the "gpc1_rate" counter must be stored in the stick-table for a value to
15642 be returned, as "gpc1" only holds the event count.
15643
Willy Tarreau74ca5042013-06-11 23:12:07 +020015644src_http_err_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015645 Returns the cumulative number of HTTP errors from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020015646 source address in the current proxy's stick-table or in the designated
Willy Tarreauc9705a12010-07-27 20:05:50 +020015647 stick-table. This includes the both request errors and 4xx error responses.
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015648 See also sc/sc0/sc1/sc2_http_err_cnt. If the address is not found, zero is
Willy Tarreau74ca5042013-06-11 23:12:07 +020015649 returned.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015650
Willy Tarreau74ca5042013-06-11 23:12:07 +020015651src_http_err_rate([<table>]) : integer
15652 Returns the average rate of HTTP errors from the incoming connection's source
15653 address in the current proxy's stick-table or in the designated stick-table,
15654 measured in amount of errors over the period configured in the table. This
15655 includes the both request errors and 4xx error responses. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015656 not found, zero is returned. See also sc/sc0/sc1/sc2_http_err_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015657
Willy Tarreau74ca5042013-06-11 23:12:07 +020015658src_http_req_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015659 Returns the cumulative number of HTTP requests from the incoming connection's
Willy Tarreau74ca5042013-06-11 23:12:07 +020015660 source address in the current proxy's stick-table or in the designated stick-
15661 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015662 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015663
Willy Tarreau74ca5042013-06-11 23:12:07 +020015664src_http_req_rate([<table>]) : integer
15665 Returns the average rate of HTTP requests from the incoming connection's
15666 source address in the current proxy's stick-table or in the designated stick-
15667 table, measured in amount of requests over the period configured in the
Willy Tarreauc9705a12010-07-27 20:05:50 +020015668 table. This includes every started request, valid or not. If the address is
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015669 not found, zero is returned. See also sc/sc0/sc1/sc2_http_req_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015670
Willy Tarreau74ca5042013-06-11 23:12:07 +020015671src_inc_gpc0([<table>]) : integer
15672 Increments the first General Purpose Counter associated to the incoming
15673 connection's source address in the current proxy's stick-table or in the
15674 designated stick-table, and returns its new value. If the address is not
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020015675 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc0.
Willy Tarreau74ca5042013-06-11 23:12:07 +020015676 This is typically used as a second ACL in an expression in order to mark a
15677 connection when a first ACL was verified :
Willy Tarreauc9705a12010-07-27 20:05:50 +020015678
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015679 Example:
Willy Tarreauc9705a12010-07-27 20:05:50 +020015680 acl abuse src_http_req_rate gt 10
Willy Tarreau869948b2013-01-04 14:14:57 +010015681 acl kill src_inc_gpc0 gt 0
Willy Tarreaue9656522010-08-17 15:40:09 +020015682 tcp-request connection reject if abuse kill
Willy Tarreauc9705a12010-07-27 20:05:50 +020015683
Frédéric Lécaille6778b272018-01-29 15:22:53 +010015684src_inc_gpc1([<table>]) : integer
15685 Increments the second General Purpose Counter associated to the incoming
15686 connection's source address in the current proxy's stick-table or in the
15687 designated stick-table, and returns its new value. If the address is not
15688 found, an entry is created and 1 is returned. See also sc0/sc2/sc2_inc_gpc1.
15689 This is typically used as a second ACL in an expression in order to mark a
15690 connection when a first ACL was verified.
15691
Willy Tarreau16e01562016-08-09 16:46:18 +020015692src_is_local : boolean
15693 Returns true if the source address of the incoming connection is local to the
15694 system, or false if the address doesn't exist on the system, meaning that it
15695 comes from a remote machine. Note that UNIX addresses are considered local.
15696 It can be useful to apply certain access restrictions based on where the
Davor Ocelice9ed2812017-12-25 17:49:28 +010015697 client comes from (e.g. require auth or https for remote machines). Please
Willy Tarreau16e01562016-08-09 16:46:18 +020015698 note that the check involves a few system calls, so it's better to do it only
15699 once per connection.
15700
Willy Tarreau74ca5042013-06-11 23:12:07 +020015701src_kbytes_in([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020015702 Returns the total amount of data received from the incoming connection's
15703 source address in the current proxy's stick-table or in the designated
15704 stick-table, measured in kilobytes. If the address is not found, zero is
15705 returned. The test is currently performed on 32-bit integers, which limits
15706 values to 4 terabytes. See also sc/sc0/sc1/sc2_kbytes_in.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015707
Willy Tarreau74ca5042013-06-11 23:12:07 +020015708src_kbytes_out([<table>]) : integer
Willy Tarreaua01b9742014-07-10 15:29:24 +020015709 Returns the total amount of data sent to the incoming connection's source
15710 address in the current proxy's stick-table or in the designated stick-table,
15711 measured in kilobytes. If the address is not found, zero is returned. The
15712 test is currently performed on 32-bit integers, which limits values to 4
15713 terabytes. See also sc/sc0/sc1/sc2_kbytes_out.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020015714
Willy Tarreau74ca5042013-06-11 23:12:07 +020015715src_port : integer
15716 Returns an integer value corresponding to the TCP source port of the
15717 connection on the client side, which is the port the client connected from.
15718 Usage of this function is very limited as modern protocols do not care much
15719 about source ports nowadays.
Willy Tarreau079ff0a2009-03-05 21:34:28 +010015720
Willy Tarreau74ca5042013-06-11 23:12:07 +020015721src_sess_cnt([<table>]) : integer
Davor Ocelice9ed2812017-12-25 17:49:28 +010015722 Returns the cumulative number of connections initiated from the incoming
Willy Tarreauc9705a12010-07-27 20:05:50 +020015723 connection's source IPv4 address in the current proxy's stick-table or in the
15724 designated stick-table, that were transformed into sessions, which means that
15725 they were accepted by "tcp-request" rules. If the address is not found, zero
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015726 is returned. See also sc/sc0/sc1/sc2_sess_cnt.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015727
Willy Tarreau74ca5042013-06-11 23:12:07 +020015728src_sess_rate([<table>]) : integer
15729 Returns the average session rate from the incoming connection's source
15730 address in the current proxy's stick-table or in the designated stick-table,
15731 measured in amount of sessions over the period configured in the table. A
15732 session is a connection that went past the early "tcp-request" rules. If the
Willy Tarreau4d4149c2013-07-23 19:33:46 +020015733 address is not found, zero is returned. See also sc/sc0/sc1/sc2_sess_rate.
Willy Tarreauc9705a12010-07-27 20:05:50 +020015734
Willy Tarreau74ca5042013-06-11 23:12:07 +020015735src_updt_conn_cnt([<table>]) : integer
15736 Creates or updates the entry associated to the incoming connection's source
15737 address in the current proxy's stick-table or in the designated stick-table.
15738 This table must be configured to store the "conn_cnt" data type, otherwise
15739 the match will be ignored. The current count is incremented by one, and the
15740 expiration timer refreshed. The updated count is returned, so this match
15741 can't return zero. This was used to reject service abusers based on their
15742 source address. Note: it is recommended to use the more complete "track-sc*"
15743 actions in "tcp-request" rules instead.
Willy Tarreaua975b8f2010-06-05 19:13:27 +020015744
15745 Example :
15746 # This frontend limits incoming SSH connections to 3 per 10 second for
15747 # each source address, and rejects excess connections until a 10 second
15748 # silence is observed. At most 20 addresses are tracked.
15749 listen ssh
15750 bind :22
15751 mode tcp
15752 maxconn 100
Willy Tarreauc9705a12010-07-27 20:05:50 +020015753 stick-table type ip size 20 expire 10s store conn_cnt
Willy Tarreau74ca5042013-06-11 23:12:07 +020015754 tcp-request content reject if { src_updt_conn_cnt gt 3 }
Willy Tarreaua975b8f2010-06-05 19:13:27 +020015755 server local 127.0.0.1:22
15756
Willy Tarreau74ca5042013-06-11 23:12:07 +020015757srv_id : integer
15758 Returns an integer containing the server's id when processing the response.
15759 While it's almost only used with ACLs, it may be used for logging or
15760 debugging.
Hervé COMMOWICKdaa824e2011-08-05 12:09:44 +020015761
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200157627.3.4. Fetching samples at Layer 5
Willy Tarreau74ca5042013-06-11 23:12:07 +020015763----------------------------------
Willy Tarreau0b1cd942010-05-16 22:18:27 +020015764
Willy Tarreau74ca5042013-06-11 23:12:07 +020015765The layer 5 usually describes just the session layer which in haproxy is
15766closest to the session once all the connection handshakes are finished, but
15767when no content is yet made available. The fetch methods described here are
15768usable as low as the "tcp-request content" rule sets unless they require some
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030015769future information. Those generally include the results of SSL negotiations.
Willy Tarreauc735a072011-03-29 00:57:02 +020015770
Ben Shillitof25e8e52016-12-02 14:25:37 +00001577151d.all(<prop>[,<prop>*]) : string
15772 Returns values for the properties requested as a string, where values are
15773 separated by the delimiter specified with "51degrees-property-separator".
15774 The device is identified using all the important HTTP headers from the
15775 request. The function can be passed up to five property names, and if a
15776 property name can't be found, the value "NoData" is returned.
15777
15778 Example :
15779 # Here the header "X-51D-DeviceTypeMobileTablet" is added to the request
15780 # containing the three properties requested using all relevant headers from
15781 # the request.
15782 frontend http-in
15783 bind *:8081
15784 default_backend servers
15785 http-request set-header X-51D-DeviceTypeMobileTablet \
15786 %[51d.all(DeviceType,IsMobile,IsTablet)]
15787
Emeric Brun645ae792014-04-30 14:21:06 +020015788ssl_bc : boolean
15789 Returns true when the back connection was made via an SSL/TLS transport
15790 layer and is locally deciphered. This means the outgoing connection was made
15791 other a server with the "ssl" option.
15792
15793ssl_bc_alg_keysize : integer
15794 Returns the symmetric cipher key size supported in bits when the outgoing
15795 connection was made over an SSL/TLS transport layer.
15796
Olivier Houchard6b77f492018-11-22 18:18:29 +010015797ssl_bc_alpn : string
15798 This extracts the Application Layer Protocol Negotiation field from an
15799 outgoing connection made via a TLS transport layer.
Michael Prokop4438c602019-05-24 10:25:45 +020015800 The result is a string containing the protocol name negotiated with the
Olivier Houchard6b77f492018-11-22 18:18:29 +010015801 server. The SSL library must have been built with support for TLS
15802 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
15803 not advertised unless the "alpn" keyword on the "server" line specifies a
15804 protocol list. Also, nothing forces the server to pick a protocol from this
15805 list, any other one may be requested. The TLS ALPN extension is meant to
15806 replace the TLS NPN extension. See also "ssl_bc_npn".
15807
Emeric Brun645ae792014-04-30 14:21:06 +020015808ssl_bc_cipher : string
15809 Returns the name of the used cipher when the outgoing connection was made
15810 over an SSL/TLS transport layer.
15811
Patrick Hemmer65674662019-06-04 08:13:03 -040015812ssl_bc_client_random : binary
15813 Returns the client random of the back connection when the incoming connection
15814 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
15815 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
15816
Emeric Brun74f7ffa2018-02-19 16:14:12 +010015817ssl_bc_is_resumed : boolean
15818 Returns true when the back connection was made over an SSL/TLS transport
15819 layer and the newly created SSL session was resumed using a cached
15820 session or a TLS ticket.
15821
Olivier Houchard6b77f492018-11-22 18:18:29 +010015822ssl_bc_npn : string
15823 This extracts the Next Protocol Negotiation field from an outgoing connection
15824 made via a TLS transport layer. The result is a string containing the
Michael Prokop4438c602019-05-24 10:25:45 +020015825 protocol name negotiated with the server . The SSL library must have been
Olivier Houchard6b77f492018-11-22 18:18:29 +010015826 built with support for TLS extensions enabled (check haproxy -vv). Note that
15827 the TLS NPN extension is not advertised unless the "npn" keyword on the
15828 "server" line specifies a protocol list. Also, nothing forces the server to
15829 pick a protocol from this list, any other one may be used. Please note that
15830 the TLS NPN extension was replaced with ALPN.
15831
Emeric Brun645ae792014-04-30 14:21:06 +020015832ssl_bc_protocol : string
15833 Returns the name of the used protocol when the outgoing connection was made
15834 over an SSL/TLS transport layer.
15835
Emeric Brunb73a9b02014-04-30 18:49:19 +020015836ssl_bc_unique_id : binary
Emeric Brun645ae792014-04-30 14:21:06 +020015837 When the outgoing connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020015838 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
15839 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
Emeric Brun645ae792014-04-30 14:21:06 +020015840
Patrick Hemmer65674662019-06-04 08:13:03 -040015841ssl_bc_server_random : binary
15842 Returns the server random of the back connection when the incoming connection
15843 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
15844 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
15845
Emeric Brun645ae792014-04-30 14:21:06 +020015846ssl_bc_session_id : binary
15847 Returns the SSL ID of the back connection when the outgoing connection was
15848 made over an SSL/TLS transport layer. It is useful to log if we want to know
15849 if session was reused or not.
15850
Patrick Hemmere0275472018-04-28 19:15:51 -040015851ssl_bc_session_key : binary
15852 Returns the SSL session master key of the back connection when the outgoing
15853 connection was made over an SSL/TLS transport layer. It is useful to decrypt
15854 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
15855 BoringSSL.
15856
Emeric Brun645ae792014-04-30 14:21:06 +020015857ssl_bc_use_keysize : integer
15858 Returns the symmetric cipher key size used in bits when the outgoing
15859 connection was made over an SSL/TLS transport layer.
15860
Willy Tarreau74ca5042013-06-11 23:12:07 +020015861ssl_c_ca_err : integer
15862 When the incoming connection was made over an SSL/TLS transport layer,
15863 returns the ID of the first error detected during verification of the client
15864 certificate at depth > 0, or 0 if no error was encountered during this
15865 verification process. Please refer to your SSL library's documentation to
15866 find the exhaustive list of error codes.
Willy Tarreauc735a072011-03-29 00:57:02 +020015867
Willy Tarreau74ca5042013-06-11 23:12:07 +020015868ssl_c_ca_err_depth : integer
15869 When the incoming connection was made over an SSL/TLS transport layer,
15870 returns the depth in the CA chain of the first error detected during the
15871 verification of the client certificate. If no error is encountered, 0 is
15872 returned.
Willy Tarreau0ba27502007-12-24 16:55:16 +010015873
Emeric Brun43e79582014-10-29 19:03:26 +010015874ssl_c_der : binary
15875 Returns the DER formatted certificate presented by the client when the
15876 incoming connection was made over an SSL/TLS transport layer. When used for
15877 an ACL, the value(s) to match against can be passed in hexadecimal form.
15878
Willy Tarreau74ca5042013-06-11 23:12:07 +020015879ssl_c_err : integer
15880 When the incoming connection was made over an SSL/TLS transport layer,
15881 returns the ID of the first error detected during verification at depth 0, or
15882 0 if no error was encountered during this verification process. Please refer
15883 to your SSL library's documentation to find the exhaustive list of error
15884 codes.
Willy Tarreau62644772008-07-16 18:36:06 +020015885
Willy Tarreau74ca5042013-06-11 23:12:07 +020015886ssl_c_i_dn([<entry>[,<occ>]]) : string
15887 When the incoming connection was made over an SSL/TLS transport layer,
15888 returns the full distinguished name of the issuer of the certificate
15889 presented by the client when no <entry> is specified, or the value of the
15890 first given entry found from the beginning of the DN. If a positive/negative
15891 occurrence number is specified as the optional second argument, it returns
15892 the value of the nth given entry value from the beginning/end of the DN.
15893 For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
15894 "ssl_c_i_dn(CN)" retrieves the common name.
Willy Tarreau62644772008-07-16 18:36:06 +020015895
Willy Tarreau74ca5042013-06-11 23:12:07 +020015896ssl_c_key_alg : string
15897 Returns the name of the algorithm used to generate the key of the certificate
15898 presented by the client when the incoming connection was made over an SSL/TLS
15899 transport layer.
Willy Tarreau62644772008-07-16 18:36:06 +020015900
Willy Tarreau74ca5042013-06-11 23:12:07 +020015901ssl_c_notafter : string
15902 Returns the end date presented by the client as a formatted string
15903 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15904 transport layer.
Emeric Brunbede3d02009-06-30 17:54:00 +020015905
Willy Tarreau74ca5042013-06-11 23:12:07 +020015906ssl_c_notbefore : string
15907 Returns the start date presented by the client as a formatted string
15908 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15909 transport layer.
Willy Tarreaub6672b52011-12-12 17:23:41 +010015910
Willy Tarreau74ca5042013-06-11 23:12:07 +020015911ssl_c_s_dn([<entry>[,<occ>]]) : string
15912 When the incoming connection was made over an SSL/TLS transport layer,
15913 returns the full distinguished name of the subject of the certificate
15914 presented by the client when no <entry> is specified, or the value of the
15915 first given entry found from the beginning of the DN. If a positive/negative
15916 occurrence number is specified as the optional second argument, it returns
15917 the value of the nth given entry value from the beginning/end of the DN.
15918 For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
15919 "ssl_c_s_dn(CN)" retrieves the common name.
Willy Tarreaub6672b52011-12-12 17:23:41 +010015920
Willy Tarreau74ca5042013-06-11 23:12:07 +020015921ssl_c_serial : binary
15922 Returns the serial of the certificate presented by the client when the
15923 incoming connection was made over an SSL/TLS transport layer. When used for
15924 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun2525b6b2012-10-18 15:59:43 +020015925
Willy Tarreau74ca5042013-06-11 23:12:07 +020015926ssl_c_sha1 : binary
15927 Returns the SHA-1 fingerprint of the certificate presented by the client when
15928 the incoming connection was made over an SSL/TLS transport layer. This can be
15929 used to stick a client to a server, or to pass this information to a server.
Willy Tarreau2d0caa32014-07-02 19:01:22 +020015930 Note that the output is binary, so if you want to pass that signature to the
15931 server, you need to encode it in hex or base64, such as in the example below:
15932
Jarno Huuskonen676f6222017-03-30 09:19:45 +030015933 Example:
Willy Tarreau2d0caa32014-07-02 19:01:22 +020015934 http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]
Emeric Brun2525b6b2012-10-18 15:59:43 +020015935
Willy Tarreau74ca5042013-06-11 23:12:07 +020015936ssl_c_sig_alg : string
15937 Returns the name of the algorithm used to sign the certificate presented by
15938 the client when the incoming connection was made over an SSL/TLS transport
15939 layer.
Emeric Brun87855892012-10-17 17:39:35 +020015940
Willy Tarreau74ca5042013-06-11 23:12:07 +020015941ssl_c_used : boolean
15942 Returns true if current SSL session uses a client certificate even if current
15943 connection uses SSL session resumption. See also "ssl_fc_has_crt".
Emeric Brun7f56e742012-10-19 18:15:40 +020015944
Willy Tarreau74ca5042013-06-11 23:12:07 +020015945ssl_c_verify : integer
15946 Returns the verify result error ID when the incoming connection was made over
15947 an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
15948 refer to your SSL library's documentation for an exhaustive list of error
15949 codes.
Emeric Brunce5ad802012-10-22 14:11:22 +020015950
Willy Tarreau74ca5042013-06-11 23:12:07 +020015951ssl_c_version : integer
15952 Returns the version of the certificate presented by the client when the
15953 incoming connection was made over an SSL/TLS transport layer.
Emeric Brunce5ad802012-10-22 14:11:22 +020015954
Emeric Brun43e79582014-10-29 19:03:26 +010015955ssl_f_der : binary
15956 Returns the DER formatted certificate presented by the frontend when the
15957 incoming connection was made over an SSL/TLS transport layer. When used for
15958 an ACL, the value(s) to match against can be passed in hexadecimal form.
15959
Willy Tarreau74ca5042013-06-11 23:12:07 +020015960ssl_f_i_dn([<entry>[,<occ>]]) : string
15961 When the incoming connection was made over an SSL/TLS transport layer,
15962 returns the full distinguished name of the issuer of the certificate
15963 presented by the frontend when no <entry> is specified, or the value of the
15964 first given entry found from the beginning of the DN. If a positive/negative
Emeric Brun87855892012-10-17 17:39:35 +020015965 occurrence number is specified as the optional second argument, it returns
Willy Tarreau74ca5042013-06-11 23:12:07 +020015966 the value of the nth given entry value from the beginning/end of the DN.
15967 For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
15968 "ssl_f_i_dn(CN)" retrieves the common name.
Emeric Brun87855892012-10-17 17:39:35 +020015969
Willy Tarreau74ca5042013-06-11 23:12:07 +020015970ssl_f_key_alg : string
15971 Returns the name of the algorithm used to generate the key of the certificate
15972 presented by the frontend when the incoming connection was made over an
15973 SSL/TLS transport layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020015974
Willy Tarreau74ca5042013-06-11 23:12:07 +020015975ssl_f_notafter : string
15976 Returns the end date presented by the frontend as a formatted string
15977 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15978 transport layer.
Emeric Brun2525b6b2012-10-18 15:59:43 +020015979
Willy Tarreau74ca5042013-06-11 23:12:07 +020015980ssl_f_notbefore : string
15981 Returns the start date presented by the frontend as a formatted string
15982 YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
15983 transport layer.
Emeric Brun87855892012-10-17 17:39:35 +020015984
Willy Tarreau74ca5042013-06-11 23:12:07 +020015985ssl_f_s_dn([<entry>[,<occ>]]) : string
15986 When the incoming connection was made over an SSL/TLS transport layer,
15987 returns the full distinguished name of the subject of the certificate
15988 presented by the frontend when no <entry> is specified, or the value of the
15989 first given entry found from the beginning of the DN. If a positive/negative
15990 occurrence number is specified as the optional second argument, it returns
15991 the value of the nth given entry value from the beginning/end of the DN.
15992 For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
15993 "ssl_f_s_dn(CN)" retrieves the common name.
Emeric Brunce5ad802012-10-22 14:11:22 +020015994
Willy Tarreau74ca5042013-06-11 23:12:07 +020015995ssl_f_serial : binary
15996 Returns the serial of the certificate presented by the frontend when the
15997 incoming connection was made over an SSL/TLS transport layer. When used for
15998 an ACL, the value(s) to match against can be passed in hexadecimal form.
Emeric Brun87855892012-10-17 17:39:35 +020015999
Emeric Brun55f4fa82014-04-30 17:11:25 +020016000ssl_f_sha1 : binary
16001 Returns the SHA-1 fingerprint of the certificate presented by the frontend
16002 when the incoming connection was made over an SSL/TLS transport layer. This
16003 can be used to know which certificate was chosen using SNI.
16004
Willy Tarreau74ca5042013-06-11 23:12:07 +020016005ssl_f_sig_alg : string
16006 Returns the name of the algorithm used to sign the certificate presented by
16007 the frontend when the incoming connection was made over an SSL/TLS transport
16008 layer.
Emeric Brun7f56e742012-10-19 18:15:40 +020016009
Willy Tarreau74ca5042013-06-11 23:12:07 +020016010ssl_f_version : integer
16011 Returns the version of the certificate presented by the frontend when the
16012 incoming connection was made over an SSL/TLS transport layer.
16013
16014ssl_fc : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020016015 Returns true when the front connection was made via an SSL/TLS transport
16016 layer and is locally deciphered. This means it has matched a socket declared
16017 with a "bind" line having the "ssl" option.
16018
Willy Tarreau74ca5042013-06-11 23:12:07 +020016019 Example :
16020 # This passes "X-Proto: https" to servers when client connects over SSL
16021 listen http-https
16022 bind :80
16023 bind :443 ssl crt /etc/haproxy.pem
16024 http-request add-header X-Proto https if { ssl_fc }
16025
16026ssl_fc_alg_keysize : integer
16027 Returns the symmetric cipher key size supported in bits when the incoming
16028 connection was made over an SSL/TLS transport layer.
16029
16030ssl_fc_alpn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016031 This extracts the Application Layer Protocol Negotiation field from an
Willy Tarreau74ca5042013-06-11 23:12:07 +020016032 incoming connection made via a TLS transport layer and locally deciphered by
16033 haproxy. The result is a string containing the protocol name advertised by
16034 the client. The SSL library must have been built with support for TLS
16035 extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
16036 not advertised unless the "alpn" keyword on the "bind" line specifies a
16037 protocol list. Also, nothing forces the client to pick a protocol from this
16038 list, any other one may be requested. The TLS ALPN extension is meant to
16039 replace the TLS NPN extension. See also "ssl_fc_npn".
16040
Willy Tarreau74ca5042013-06-11 23:12:07 +020016041ssl_fc_cipher : string
16042 Returns the name of the used cipher when the incoming connection was made
16043 over an SSL/TLS transport layer.
Willy Tarreauab861d32013-04-02 02:30:41 +020016044
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010016045ssl_fc_cipherlist_bin : binary
16046 Returns the binary form of the client hello cipher list. The maximum returned
16047 value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010016048 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010016049
16050ssl_fc_cipherlist_hex : string
16051 Returns the binary form of the client hello cipher list encoded as
16052 hexadecimal. The maximum returned value length is according with the value of
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010016053 "tune.ssl.capture-cipherlist-size".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010016054
16055ssl_fc_cipherlist_str : string
16056 Returns the decoded text form of the client hello cipher list. The maximum
16057 number of ciphers returned is according with the value of
16058 "tune.ssl.capture-cipherlist-size". Note that this sample-fetch is only
Davor Ocelice9ed2812017-12-25 17:49:28 +010016059 available with OpenSSL >= 1.0.2. If the function is not enabled, this
Emmanuel Hocdetddcde192017-09-01 17:32:08 +020016060 sample-fetch returns the hash like "ssl_fc_cipherlist_xxh".
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010016061
16062ssl_fc_cipherlist_xxh : integer
16063 Returns a xxh64 of the cipher list. This hash can be return only is the value
16064 "tune.ssl.capture-cipherlist-size" is set greater than 0, however the hash
Emmanuel Hocdetaaee7502017-03-07 18:34:58 +010016065 take in account all the data of the cipher list.
Thierry FOURNIER5bf77322017-02-25 12:45:22 +010016066
Patrick Hemmer65674662019-06-04 08:13:03 -040016067ssl_fc_client_random : binary
16068 Returns the client random of the front connection when the incoming connection
16069 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
16070 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
16071
Willy Tarreau74ca5042013-06-11 23:12:07 +020016072ssl_fc_has_crt : boolean
Emeric Brun2525b6b2012-10-18 15:59:43 +020016073 Returns true if a client certificate is present in an incoming connection over
16074 SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Emeric Brun9143d372012-12-20 15:44:16 +010016075 Note: on SSL session resumption with Session ID or TLS ticket, client
16076 certificate is not present in the current connection but may be retrieved
16077 from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
16078 current SSL session uses a client certificate.
Emeric Brun2525b6b2012-10-18 15:59:43 +020016079
Olivier Houchardccaa7de2017-10-02 11:51:03 +020016080ssl_fc_has_early : boolean
16081 Returns true if early data were sent, and the handshake didn't happen yet. As
16082 it has security implications, it is useful to be able to refuse those, or
16083 wait until the handshake happened.
16084
Willy Tarreau74ca5042013-06-11 23:12:07 +020016085ssl_fc_has_sni : boolean
16086 This checks for the presence of a Server Name Indication TLS extension (SNI)
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020016087 in an incoming connection was made over an SSL/TLS transport layer. Returns
16088 true when the incoming connection presents a TLS SNI field. This requires
John Roesler27c754c2019-07-10 15:45:51 -050016089 that the SSL library is built with support for TLS extensions enabled (check
Willy Tarreauf7bc57c2012-10-03 00:19:48 +020016090 haproxy -vv).
Willy Tarreau7875d092012-09-10 08:20:03 +020016091
Nenad Merdanovic1516fe32016-05-17 03:31:21 +020016092ssl_fc_is_resumed : boolean
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020016093 Returns true if the SSL/TLS session has been resumed through the use of
Jérôme Magnin4a326cb2018-01-15 14:01:17 +010016094 SSL session cache or TLS tickets on an incoming connection over an SSL/TLS
16095 transport layer.
Nenad Merdanovic26ea8222015-05-18 02:28:57 +020016096
Willy Tarreau74ca5042013-06-11 23:12:07 +020016097ssl_fc_npn : string
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016098 This extracts the Next Protocol Negotiation field from an incoming connection
Willy Tarreau74ca5042013-06-11 23:12:07 +020016099 made via a TLS transport layer and locally deciphered by haproxy. The result
16100 is a string containing the protocol name advertised by the client. The SSL
16101 library must have been built with support for TLS extensions enabled (check
16102 haproxy -vv). Note that the TLS NPN extension is not advertised unless the
16103 "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
16104 forces the client to pick a protocol from this list, any other one may be
16105 requested. Please note that the TLS NPN extension was replaced with ALPN.
Willy Tarreaua33c6542012-10-15 13:19:06 +020016106
Willy Tarreau74ca5042013-06-11 23:12:07 +020016107ssl_fc_protocol : string
16108 Returns the name of the used protocol when the incoming connection was made
16109 over an SSL/TLS transport layer.
Willy Tarreau7875d092012-09-10 08:20:03 +020016110
Emeric Brunb73a9b02014-04-30 18:49:19 +020016111ssl_fc_unique_id : binary
David Sc1ad52e2014-04-08 18:48:47 -040016112 When the incoming connection was made over an SSL/TLS transport layer,
Emeric Brunb73a9b02014-04-30 18:49:19 +020016113 returns the TLS unique ID as defined in RFC5929 section 3. The unique id
16114 can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".
David Sc1ad52e2014-04-08 18:48:47 -040016115
Patrick Hemmer65674662019-06-04 08:13:03 -040016116ssl_fc_server_random : binary
16117 Returns the server random of the front connection when the incoming connection
16118 was made over an SSL/TLS transport layer. It is useful to to decrypt traffic
16119 sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or BoringSSL.
16120
Willy Tarreau74ca5042013-06-11 23:12:07 +020016121ssl_fc_session_id : binary
16122 Returns the SSL ID of the front connection when the incoming connection was
16123 made over an SSL/TLS transport layer. It is useful to stick a given client to
16124 a server. It is important to note that some browsers refresh their session ID
16125 every few minutes.
Willy Tarreau7875d092012-09-10 08:20:03 +020016126
Patrick Hemmere0275472018-04-28 19:15:51 -040016127ssl_fc_session_key : binary
16128 Returns the SSL session master key of the front connection when the incoming
16129 connection was made over an SSL/TLS transport layer. It is useful to decrypt
16130 traffic sent using ephemeral ciphers. This requires OpenSSL >= 1.1.0, or
16131 BoringSSL.
16132
16133
Willy Tarreau74ca5042013-06-11 23:12:07 +020016134ssl_fc_sni : string
16135 This extracts the Server Name Indication TLS extension (SNI) field from an
16136 incoming connection made via an SSL/TLS transport layer and locally
16137 deciphered by haproxy. The result (when present) typically is a string
16138 matching the HTTPS host name (253 chars or less). The SSL library must have
16139 been built with support for TLS extensions enabled (check haproxy -vv).
16140
16141 This fetch is different from "req_ssl_sni" above in that it applies to the
16142 connection being deciphered by haproxy and not to SSL contents being blindly
16143 forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
John Roesler27c754c2019-07-10 15:45:51 -050016144 requires that the SSL library is built with support for TLS extensions
Cyril Bonté9c1eb1e2012-10-09 22:45:34 +020016145 enabled (check haproxy -vv).
Willy Tarreau62644772008-07-16 18:36:06 +020016146
Willy Tarreau74ca5042013-06-11 23:12:07 +020016147 ACL derivatives :
Willy Tarreau74ca5042013-06-11 23:12:07 +020016148 ssl_fc_sni_end : suffix match
16149 ssl_fc_sni_reg : regex match
Emeric Brun589fcad2012-10-16 14:13:26 +020016150
Willy Tarreau74ca5042013-06-11 23:12:07 +020016151ssl_fc_use_keysize : integer
16152 Returns the symmetric cipher key size used in bits when the incoming
16153 connection was made over an SSL/TLS transport layer.
Willy Tarreaub6fb4202008-07-20 11:18:28 +020016154
Willy Tarreaub6fb4202008-07-20 11:18:28 +020016155
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200161567.3.5. Fetching samples from buffer contents (Layer 6)
Willy Tarreau74ca5042013-06-11 23:12:07 +020016157------------------------------------------------------
Willy Tarreaub6fb4202008-07-20 11:18:28 +020016158
Willy Tarreau74ca5042013-06-11 23:12:07 +020016159Fetching samples from buffer contents is a bit different from the previous
16160sample fetches above because the sampled data are ephemeral. These data can
16161only be used when they're available and will be lost when they're forwarded.
16162For this reason, samples fetched from buffer contents during a request cannot
16163be used in a response for example. Even while the data are being fetched, they
16164can change. Sometimes it is necessary to set some delays or combine multiple
16165sample fetch methods to ensure that the expected data are complete and usable,
16166for example through TCP request content inspection. Please see the "tcp-request
16167content" keyword for more detailed information on the subject.
Willy Tarreau62644772008-07-16 18:36:06 +020016168
Willy Tarreau74ca5042013-06-11 23:12:07 +020016169payload(<offset>,<length>) : binary (deprecated)
Davor Ocelice9ed2812017-12-25 17:49:28 +010016170 This is an alias for "req.payload" when used in the context of a request (e.g.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016171 "stick on", "stick match"), and for "res.payload" when used in the context of
16172 a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010016173
Willy Tarreau74ca5042013-06-11 23:12:07 +020016174payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
16175 This is an alias for "req.payload_lv" when used in the context of a request
Davor Ocelice9ed2812017-12-25 17:49:28 +010016176 (e.g. "stick on", "stick match"), and for "res.payload_lv" when used in the
Willy Tarreau74ca5042013-06-11 23:12:07 +020016177 context of a response such as in "stick store response".
Willy Tarreau0ba27502007-12-24 16:55:16 +010016178
Thierry FOURNIERd7d88812017-04-19 15:15:14 +020016179req.hdrs : string
16180 Returns the current request headers as string including the last empty line
16181 separating headers from the request body. The last empty line can be used to
16182 detect a truncated header block. This sample fetch is useful for some SPOE
16183 headers analyzers and for advanced logging.
16184
Thierry FOURNIER5617dce2017-04-09 05:38:19 +020016185req.hdrs_bin : binary
16186 Returns the current request headers contained in preparsed binary form. This
16187 is useful for offloading some processing with SPOE. Each string is described
16188 by a length followed by the number of bytes indicated in the length. The
16189 length is represented using the variable integer encoding detailed in the
16190 SPOE documentation. The end of the list is marked by a couple of empty header
16191 names and values (length of 0 for both).
16192
16193 *(<str:header-name><str:header-value>)<empty string><empty string>
16194
16195 int: refer to the SPOE documentation for the encoding
16196 str: <int:length><bytes>
16197
Willy Tarreau74ca5042013-06-11 23:12:07 +020016198req.len : integer
16199req_len : integer (deprecated)
16200 Returns an integer value corresponding to the number of bytes present in the
16201 request buffer. This is mostly used in ACL. It is important to understand
16202 that this test does not return false as long as the buffer is changing. This
16203 means that a check with equality to zero will almost always immediately match
16204 at the beginning of the session, while a test for more data will wait for
16205 that data to come in and return false only when haproxy is certain that no
16206 more data will come in. This test was designed to be used with TCP request
16207 content inspection.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016208
Willy Tarreau74ca5042013-06-11 23:12:07 +020016209req.payload(<offset>,<length>) : binary
16210 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020016211 in the request buffer. As a special case, if the <length> argument is zero,
16212 the the whole buffer from <offset> to the end is extracted. This can be used
16213 with ACLs in order to check for the presence of some content in a buffer at
16214 any location.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016215
Willy Tarreau74ca5042013-06-11 23:12:07 +020016216 ACL alternatives :
16217 payload(<offset>,<length>) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016218
Willy Tarreau74ca5042013-06-11 23:12:07 +020016219req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
16220 This extracts a binary block whose size is specified at <offset1> for <length>
16221 bytes, and which starts at <offset2> if specified or just after the length in
16222 the request buffer. The <offset2> parameter also supports relative offsets if
16223 prepended with a '+' or '-' sign.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016224
Willy Tarreau74ca5042013-06-11 23:12:07 +020016225 ACL alternatives :
16226 payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016227
Willy Tarreau74ca5042013-06-11 23:12:07 +020016228 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016229
Willy Tarreau74ca5042013-06-11 23:12:07 +020016230req.proto_http : boolean
16231req_proto_http : boolean (deprecated)
16232 Returns true when data in the request buffer look like HTTP and correctly
16233 parses as such. It is the same parser as the common HTTP request parser which
16234 is used so there should be no surprises. The test does not match until the
16235 request is complete, failed or timed out. This test may be used to report the
16236 protocol in TCP logs, but the biggest use is to block TCP request analysis
16237 until a complete HTTP request is present in the buffer, for example to track
16238 a header.
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016239
Willy Tarreau74ca5042013-06-11 23:12:07 +020016240 Example:
16241 # track request counts per "base" (concatenation of Host+URL)
16242 tcp-request inspect-delay 10s
16243 tcp-request content reject if !HTTP
Willy Tarreaube4a3ef2013-06-17 15:04:07 +020016244 tcp-request content track-sc0 base table req-rate
Willy Tarreaua7ad50c2012-04-29 15:39:40 +020016245
Willy Tarreau74ca5042013-06-11 23:12:07 +020016246req.rdp_cookie([<name>]) : string
16247rdp_cookie([<name>]) : string (deprecated)
16248 When the request buffer looks like the RDP protocol, extracts the RDP cookie
16249 <name>, or any cookie if unspecified. The parser only checks for the first
16250 cookie, as illustrated in the RDP protocol specification. The cookie name is
16251 case insensitive. Generally the "MSTS" cookie name will be used, as it can
16252 contain the user name of the client connecting to the server if properly
16253 configured on the client. The "MSTSHASH" cookie is often used as well for
16254 session stickiness to servers.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016255
Willy Tarreau74ca5042013-06-11 23:12:07 +020016256 This differs from "balance rdp-cookie" in that any balancing algorithm may be
16257 used and thus the distribution of clients to backend servers is not linked to
16258 a hash of the RDP cookie. It is envisaged that using a balancing algorithm
16259 such as "balance roundrobin" or "balance leastconn" will lead to a more even
16260 distribution of clients to backend servers than the hash used by "balance
16261 rdp-cookie".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016262
Willy Tarreau74ca5042013-06-11 23:12:07 +020016263 ACL derivatives :
16264 req_rdp_cookie([<name>]) : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016265
Willy Tarreau74ca5042013-06-11 23:12:07 +020016266 Example :
16267 listen tse-farm
16268 bind 0.0.0.0:3389
16269 # wait up to 5s for an RDP cookie in the request
16270 tcp-request inspect-delay 5s
16271 tcp-request content accept if RDP_COOKIE
16272 # apply RDP cookie persistence
16273 persist rdp-cookie
16274 # Persist based on the mstshash cookie
16275 # This is only useful makes sense if
16276 # balance rdp-cookie is not used
16277 stick-table type string size 204800
16278 stick on req.rdp_cookie(mstshash)
16279 server srv1 1.1.1.1:3389
16280 server srv1 1.1.1.2:3389
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016281
Willy Tarreau74ca5042013-06-11 23:12:07 +020016282 See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
16283 "req_rdp_cookie" ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016284
Willy Tarreau74ca5042013-06-11 23:12:07 +020016285req.rdp_cookie_cnt([name]) : integer
16286rdp_cookie_cnt([name]) : integer (deprecated)
16287 Tries to parse the request buffer as RDP protocol, then returns an integer
16288 corresponding to the number of RDP cookies found. If an optional cookie name
16289 is passed, only cookies matching this name are considered. This is mostly
16290 used in ACL.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016291
Willy Tarreau74ca5042013-06-11 23:12:07 +020016292 ACL derivatives :
16293 req_rdp_cookie_cnt([<name>]) : integer match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016294
Alex Zorin4afdd132018-12-30 13:56:28 +110016295req.ssl_alpn : string
16296 Returns a string containing the values of the Application-Layer Protocol
16297 Negotiation (ALPN) TLS extension (RFC7301), sent by the client within the SSL
16298 ClientHello message. Note that this only applies to raw contents found in the
16299 request buffer and not to the contents deciphered via an SSL data layer, so
16300 this will not work with "bind" lines having the "ssl" option. This is useful
16301 in ACL to make a routing decision based upon the ALPN preferences of a TLS
Jarno Huuskonene504f812019-01-03 07:56:49 +020016302 client, like in the example below. See also "ssl_fc_alpn".
Alex Zorin4afdd132018-12-30 13:56:28 +110016303
16304 Examples :
16305 # Wait for a client hello for at most 5 seconds
16306 tcp-request inspect-delay 5s
16307 tcp-request content accept if { req_ssl_hello_type 1 }
Jarno Huuskonene504f812019-01-03 07:56:49 +020016308 use_backend bk_acme if { req.ssl_alpn acme-tls/1 }
Alex Zorin4afdd132018-12-30 13:56:28 +110016309 default_backend bk_default
16310
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020016311req.ssl_ec_ext : boolean
16312 Returns a boolean identifying if client sent the Supported Elliptic Curves
16313 Extension as defined in RFC4492, section 5.1. within the SSL ClientHello
Cyril Bonté307ee1e2015-09-28 23:16:06 +020016314 message. This can be used to present ECC compatible clients with EC
16315 certificate and to use RSA for all others, on the same IP address. Note that
16316 this only applies to raw contents found in the request buffer and not to
16317 contents deciphered via an SSL data layer, so this will not work with "bind"
16318 lines having the "ssl" option.
Nenad Merdanovic5fc7d7e2015-07-07 22:00:17 +020016319
Willy Tarreau74ca5042013-06-11 23:12:07 +020016320req.ssl_hello_type : integer
16321req_ssl_hello_type : integer (deprecated)
16322 Returns an integer value containing the type of the SSL hello message found
16323 in the request buffer if the buffer contains data that parse as a complete
16324 SSL (v3 or superior) client hello message. Note that this only applies to raw
16325 contents found in the request buffer and not to contents deciphered via an
16326 SSL data layer, so this will not work with "bind" lines having the "ssl"
16327 option. This is mostly used in ACL to detect presence of an SSL hello message
16328 that is supposed to contain an SSL session ID usable for stickiness.
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016329
Willy Tarreau74ca5042013-06-11 23:12:07 +020016330req.ssl_sni : string
16331req_ssl_sni : string (deprecated)
16332 Returns a string containing the value of the Server Name TLS extension sent
16333 by a client in a TLS stream passing through the request buffer if the buffer
16334 contains data that parse as a complete SSL (v3 or superior) client hello
16335 message. Note that this only applies to raw contents found in the request
16336 buffer and not to contents deciphered via an SSL data layer, so this will not
16337 work with "bind" lines having the "ssl" option. SNI normally contains the
16338 name of the host the client tries to connect to (for recent browsers). SNI is
16339 useful for allowing or denying access to certain hosts when SSL/TLS is used
16340 by the client. This test was designed to be used with TCP request content
16341 inspection. If content switching is needed, it is recommended to first wait
16342 for a complete client hello (type 1), like in the example below. See also
16343 "ssl_fc_sni".
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016344
Willy Tarreau74ca5042013-06-11 23:12:07 +020016345 ACL derivatives :
16346 req_ssl_sni : exact string match
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016347
Willy Tarreau74ca5042013-06-11 23:12:07 +020016348 Examples :
16349 # Wait for a client hello for at most 5 seconds
16350 tcp-request inspect-delay 5s
16351 tcp-request content accept if { req_ssl_hello_type 1 }
16352 use_backend bk_allow if { req_ssl_sni -f allowed_sites }
16353 default_backend bk_sorry_page
Willy Tarreau04aa6a92012-04-06 18:57:55 +020016354
Pradeep Jindalbb2acf52015-09-29 10:12:57 +053016355req.ssl_st_ext : integer
16356 Returns 0 if the client didn't send a SessionTicket TLS Extension (RFC5077)
16357 Returns 1 if the client sent SessionTicket TLS Extension
16358 Returns 2 if the client also sent non-zero length TLS SessionTicket
16359 Note that this only applies to raw contents found in the request buffer and
16360 not to contents deciphered via an SSL data layer, so this will not work with
16361 "bind" lines having the "ssl" option. This can for example be used to detect
16362 whether the client sent a SessionTicket or not and stick it accordingly, if
16363 no SessionTicket then stick on SessionID or don't stick as there's no server
16364 side state is there when SessionTickets are in use.
16365
Willy Tarreau74ca5042013-06-11 23:12:07 +020016366req.ssl_ver : integer
16367req_ssl_ver : integer (deprecated)
16368 Returns an integer value containing the version of the SSL/TLS protocol of a
16369 stream present in the request buffer. Both SSLv2 hello messages and SSLv3
16370 messages are supported. TLSv1 is announced as SSL version 3.1. The value is
16371 composed of the major version multiplied by 65536, added to the minor
16372 version. Note that this only applies to raw contents found in the request
16373 buffer and not to contents deciphered via an SSL data layer, so this will not
16374 work with "bind" lines having the "ssl" option. The ACL version of the test
Davor Ocelice9ed2812017-12-25 17:49:28 +010016375 matches against a decimal notation in the form MAJOR.MINOR (e.g. 3.1). This
Willy Tarreau74ca5042013-06-11 23:12:07 +020016376 fetch is mostly used in ACL.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016377
Willy Tarreau74ca5042013-06-11 23:12:07 +020016378 ACL derivatives :
16379 req_ssl_ver : decimal match
Willy Tarreaud63335a2010-02-26 12:56:52 +010016380
Willy Tarreau47e8eba2013-09-11 23:28:46 +020016381res.len : integer
16382 Returns an integer value corresponding to the number of bytes present in the
16383 response buffer. This is mostly used in ACL. It is important to understand
16384 that this test does not return false as long as the buffer is changing. This
16385 means that a check with equality to zero will almost always immediately match
16386 at the beginning of the session, while a test for more data will wait for
16387 that data to come in and return false only when haproxy is certain that no
16388 more data will come in. This test was designed to be used with TCP response
16389 content inspection.
16390
Willy Tarreau74ca5042013-06-11 23:12:07 +020016391res.payload(<offset>,<length>) : binary
16392 This extracts a binary block of <length> bytes and starting at byte <offset>
Willy Tarreau00f00842013-08-02 11:07:32 +020016393 in the response buffer. As a special case, if the <length> argument is zero,
16394 the the whole buffer from <offset> to the end is extracted. This can be used
16395 with ACLs in order to check for the presence of some content in a buffer at
16396 any location.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016397
Willy Tarreau74ca5042013-06-11 23:12:07 +020016398res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
16399 This extracts a binary block whose size is specified at <offset1> for <length>
16400 bytes, and which starts at <offset2> if specified or just after the length in
16401 the response buffer. The <offset2> parameter also supports relative offsets
16402 if prepended with a '+' or '-' sign.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016403
Willy Tarreau74ca5042013-06-11 23:12:07 +020016404 Example : please consult the example from the "stick store-response" keyword.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016405
Willy Tarreau971f7b62015-09-29 14:06:59 +020016406res.ssl_hello_type : integer
16407rep_ssl_hello_type : integer (deprecated)
16408 Returns an integer value containing the type of the SSL hello message found
16409 in the response buffer if the buffer contains data that parses as a complete
16410 SSL (v3 or superior) hello message. Note that this only applies to raw
16411 contents found in the response buffer and not to contents deciphered via an
16412 SSL data layer, so this will not work with "server" lines having the "ssl"
16413 option. This is mostly used in ACL to detect presence of an SSL hello message
16414 that is supposed to contain an SSL session ID usable for stickiness.
16415
Willy Tarreau74ca5042013-06-11 23:12:07 +020016416wait_end : boolean
16417 This fetch either returns true when the inspection period is over, or does
16418 not fetch. It is only used in ACLs, in conjunction with content analysis to
Davor Ocelice9ed2812017-12-25 17:49:28 +010016419 avoid returning a wrong verdict early. It may also be used to delay some
Willy Tarreau74ca5042013-06-11 23:12:07 +020016420 actions, such as a delayed reject for some special addresses. Since it either
16421 stops the rules evaluation or immediately returns true, it is recommended to
Davor Ocelice9ed2812017-12-25 17:49:28 +010016422 use this acl as the last one in a rule. Please note that the default ACL
Willy Tarreau74ca5042013-06-11 23:12:07 +020016423 "WAIT_END" is always usable without prior declaration. This test was designed
16424 to be used with TCP request content inspection.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016425
Willy Tarreau74ca5042013-06-11 23:12:07 +020016426 Examples :
16427 # delay every incoming request by 2 seconds
16428 tcp-request inspect-delay 2s
16429 tcp-request content accept if WAIT_END
Willy Tarreaud63335a2010-02-26 12:56:52 +010016430
Willy Tarreau74ca5042013-06-11 23:12:07 +020016431 # don't immediately tell bad guys they are rejected
16432 tcp-request inspect-delay 10s
16433 acl goodguys src 10.0.0.0/24
16434 acl badguys src 10.0.1.0/24
16435 tcp-request content accept if goodguys
16436 tcp-request content reject if badguys WAIT_END
16437 tcp-request content reject
16438
16439
Thierry FOURNIER060762e2014-04-23 13:29:15 +0200164407.3.6. Fetching HTTP samples (Layer 7)
Willy Tarreau74ca5042013-06-11 23:12:07 +020016441--------------------------------------
16442
16443It is possible to fetch samples from HTTP contents, requests and responses.
16444This application layer is also called layer 7. It is only possible to fetch the
16445data in this section when a full HTTP request or response has been parsed from
16446its respective request or response buffer. This is always the case with all
16447HTTP specific rules and for sections running with "mode http". When using TCP
16448content inspection, it may be necessary to support an inspection delay in order
16449to let the request or response come in first. These fetches may require a bit
16450more CPU resources than the layer 4 ones, but not much since the request and
16451response are indexed.
16452
16453base : string
16454 This returns the concatenation of the first Host header and the path part of
16455 the request, which starts at the first slash and ends before the question
16456 mark. It can be useful in virtual hosted environments to detect URL abuses as
16457 well as to improve shared caches efficiency. Using this with a limited size
16458 stick table also allows one to collect statistics about most commonly
16459 requested objects by host/path. With ACLs it can allow simple content
16460 switching rules involving the host and the path at the same time, such as
16461 "www.example.com/favicon.ico". See also "path" and "uri".
16462
16463 ACL derivatives :
16464 base : exact string match
16465 base_beg : prefix match
16466 base_dir : subdir match
16467 base_dom : domain match
16468 base_end : suffix match
16469 base_len : length match
16470 base_reg : regex match
16471 base_sub : substring match
16472
16473base32 : integer
16474 This returns a 32-bit hash of the value returned by the "base" fetch method
16475 above. This is useful to track per-URL activity on high traffic sites without
16476 having to store all URLs. Instead a shorter hash is stored, saving a lot of
Willy Tarreau23ec4ca2014-07-15 20:15:37 +020016477 memory. The output type is an unsigned integer. The hash function used is
16478 SDBM with full avalanche on the output. Technically, base32 is exactly equal
16479 to "base,sdbm(1)".
Willy Tarreau74ca5042013-06-11 23:12:07 +020016480
16481base32+src : binary
16482 This returns the concatenation of the base32 fetch above and the src fetch
16483 below. The resulting type is of type binary, with a size of 8 or 20 bytes
16484 depending on the source address family. This can be used to track per-IP,
16485 per-URL counters.
16486
William Lallemand65ad6e12014-01-31 15:08:02 +010016487capture.req.hdr(<idx>) : string
16488 This extracts the content of the header captured by the "capture request
16489 header", idx is the position of the capture keyword in the configuration.
16490 The first entry is an index of 0. See also: "capture request header".
16491
16492capture.req.method : string
16493 This extracts the METHOD of an HTTP request. It can be used in both request
16494 and response. Unlike "method", it can be used in both request and response
16495 because it's allocated.
16496
16497capture.req.uri : string
16498 This extracts the request's URI, which starts at the first slash and ends
16499 before the first space in the request (without the host part). Unlike "path"
16500 and "url", it can be used in both request and response because it's
16501 allocated.
16502
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020016503capture.req.ver : string
16504 This extracts the request's HTTP version and returns either "HTTP/1.0" or
16505 "HTTP/1.1". Unlike "req.ver", it can be used in both request, response, and
16506 logs because it relies on a persistent flag.
16507
William Lallemand65ad6e12014-01-31 15:08:02 +010016508capture.res.hdr(<idx>) : string
16509 This extracts the content of the header captured by the "capture response
16510 header", idx is the position of the capture keyword in the configuration.
16511 The first entry is an index of 0.
16512 See also: "capture response header"
16513
Willy Tarreau3c1b5ec2014-04-24 23:41:57 +020016514capture.res.ver : string
16515 This extracts the response's HTTP version and returns either "HTTP/1.0" or
16516 "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
16517 persistent flag.
16518
Willy Tarreaua5910cc2015-05-02 00:46:08 +020016519req.body : binary
16520 This returns the HTTP request's available body as a block of data. It
16521 requires that the request body has been buffered made available using
16522 "option http-buffer-request". In case of chunked-encoded body, currently only
16523 the first chunk is analyzed.
16524
Thierry FOURNIER9826c772015-05-20 15:50:54 +020016525req.body_param([<name>) : string
16526 This fetch assumes that the body of the POST request is url-encoded. The user
16527 can check if the "content-type" contains the value
16528 "application/x-www-form-urlencoded". This extracts the first occurrence of the
16529 parameter <name> in the body, which ends before '&'. The parameter name is
16530 case-sensitive. If no name is given, any parameter will match, and the first
16531 one will be returned. The result is a string corresponding to the value of the
16532 parameter <name> as presented in the request body (no URL decoding is
16533 performed). Note that the ACL version of this fetch iterates over multiple
16534 parameters and will iteratively report all parameters values if no name is
16535 given.
16536
Willy Tarreaua5910cc2015-05-02 00:46:08 +020016537req.body_len : integer
16538 This returns the length of the HTTP request's available body in bytes. It may
16539 be lower than the advertised length if the body is larger than the buffer. It
16540 requires that the request body has been buffered made available using
16541 "option http-buffer-request".
16542
16543req.body_size : integer
16544 This returns the advertised length of the HTTP request's body in bytes. It
16545 will represent the advertised Content-Length header, or the size of the first
16546 chunk in case of chunked encoding. In order to parse the chunks, it requires
16547 that the request body has been buffered made available using
16548 "option http-buffer-request".
16549
Willy Tarreau74ca5042013-06-11 23:12:07 +020016550req.cook([<name>]) : string
16551cook([<name>]) : string (deprecated)
16552 This extracts the last occurrence of the cookie name <name> on a "Cookie"
16553 header line from the request, and returns its value as string. If no name is
16554 specified, the first cookie value is returned. When used with ACLs, all
16555 matching cookies are evaluated. Spaces around the name and the value are
16556 ignored as requested by the Cookie header specification (RFC6265). The cookie
16557 name is case-sensitive. Empty cookies are valid, so an empty cookie may very
16558 well return an empty value if it is present. Use the "found" match to detect
16559 presence. Use the res.cook() variant for response cookies sent by the server.
16560
16561 ACL derivatives :
16562 cook([<name>]) : exact string match
16563 cook_beg([<name>]) : prefix match
16564 cook_dir([<name>]) : subdir match
16565 cook_dom([<name>]) : domain match
16566 cook_end([<name>]) : suffix match
16567 cook_len([<name>]) : length match
16568 cook_reg([<name>]) : regex match
16569 cook_sub([<name>]) : substring match
Willy Tarreaud63335a2010-02-26 12:56:52 +010016570
Willy Tarreau74ca5042013-06-11 23:12:07 +020016571req.cook_cnt([<name>]) : integer
16572cook_cnt([<name>]) : integer (deprecated)
16573 Returns an integer value representing the number of occurrences of the cookie
16574 <name> in the request, or all cookies if <name> is not specified.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016575
Willy Tarreau74ca5042013-06-11 23:12:07 +020016576req.cook_val([<name>]) : integer
16577cook_val([<name>]) : integer (deprecated)
16578 This extracts the last occurrence of the cookie name <name> on a "Cookie"
16579 header line from the request, and converts its value to an integer which is
16580 returned. If no name is specified, the first cookie value is returned. When
16581 used in ACLs, all matching names are iterated over until a value matches.
Willy Tarreau0e698542011-09-16 08:32:32 +020016582
Willy Tarreau74ca5042013-06-11 23:12:07 +020016583cookie([<name>]) : string (deprecated)
16584 This extracts the last occurrence of the cookie name <name> on a "Cookie"
16585 header line from the request, or a "Set-Cookie" header from the response, and
16586 returns its value as a string. A typical use is to get multiple clients
16587 sharing a same profile use the same server. This can be similar to what
Willy Tarreau294d0f02015-08-10 19:40:12 +020016588 "appsession" did with the "request-learn" statement, but with support for
Willy Tarreau74ca5042013-06-11 23:12:07 +020016589 multi-peer synchronization and state keeping across restarts. If no name is
16590 specified, the first cookie value is returned. This fetch should not be used
16591 anymore and should be replaced by req.cook() or res.cook() instead as it
16592 ambiguously uses the direction based on the context where it is used.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016593
Willy Tarreau74ca5042013-06-11 23:12:07 +020016594hdr([<name>[,<occ>]]) : string
16595 This is equivalent to req.hdr() when used on requests, and to res.hdr() when
16596 used on responses. Please refer to these respective fetches for more details.
16597 In case of doubt about the fetch direction, please use the explicit ones.
16598 Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030016599 unambiguously apply to the request headers.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016600
Willy Tarreau74ca5042013-06-11 23:12:07 +020016601req.fhdr(<name>[,<occ>]) : string
16602 This extracts the last occurrence of header <name> in an HTTP request. When
16603 used from an ACL, all occurrences are iterated over until a match is found.
16604 Optionally, a specific occurrence might be specified as a position number.
16605 Positive values indicate a position from the first occurrence, with 1 being
16606 the first one. Negative values indicate positions relative to the last one,
16607 with -1 being the last one. It differs from req.hdr() in that any commas
16608 present in the value are returned and are not used as delimiters. This is
16609 sometimes useful with headers such as User-Agent.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016610
Willy Tarreau74ca5042013-06-11 23:12:07 +020016611req.fhdr_cnt([<name>]) : integer
16612 Returns an integer value representing the number of occurrences of request
16613 header field name <name>, or the total number of header fields if <name> is
16614 not specified. Contrary to its req.hdr_cnt() cousin, this function returns
16615 the number of full line headers and does not stop on commas.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016616
Willy Tarreau74ca5042013-06-11 23:12:07 +020016617req.hdr([<name>[,<occ>]]) : string
16618 This extracts the last occurrence of header <name> in an HTTP request. When
16619 used from an ACL, all occurrences are iterated over until a match is found.
16620 Optionally, a specific occurrence might be specified as a position number.
16621 Positive values indicate a position from the first occurrence, with 1 being
16622 the first one. Negative values indicate positions relative to the last one,
16623 with -1 being the last one. A typical use is with the X-Forwarded-For header
16624 once converted to IP, associated with an IP stick-table. The function
16625 considers any comma as a delimiter for distinct values. If full-line headers
Lukas Tribus23953682017-04-28 13:24:30 +000016626 are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
Willy Tarreau74ca5042013-06-11 23:12:07 +020016627 how certain headers are supposed to be parsed. Also, some of them are case
Davor Ocelice9ed2812017-12-25 17:49:28 +010016628 insensitive (e.g. Connection).
Willy Tarreaud63335a2010-02-26 12:56:52 +010016629
Willy Tarreau74ca5042013-06-11 23:12:07 +020016630 ACL derivatives :
16631 hdr([<name>[,<occ>]]) : exact string match
16632 hdr_beg([<name>[,<occ>]]) : prefix match
16633 hdr_dir([<name>[,<occ>]]) : subdir match
16634 hdr_dom([<name>[,<occ>]]) : domain match
16635 hdr_end([<name>[,<occ>]]) : suffix match
16636 hdr_len([<name>[,<occ>]]) : length match
16637 hdr_reg([<name>[,<occ>]]) : regex match
16638 hdr_sub([<name>[,<occ>]]) : substring match
16639
16640req.hdr_cnt([<name>]) : integer
16641hdr_cnt([<header>]) : integer (deprecated)
16642 Returns an integer value representing the number of occurrences of request
16643 header field name <name>, or the total number of header field values if
16644 <name> is not specified. It is important to remember that one header line may
16645 count as several headers if it has several values. The function considers any
16646 comma as a delimiter for distinct values. If full-line headers are desired
16647 instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
16648 detect presence, absence or abuse of a specific header, as well as to block
16649 request smuggling attacks by rejecting requests which contain more than one
16650 of certain headers. See "req.hdr" for more information on header matching.
16651
16652req.hdr_ip([<name>[,<occ>]]) : ip
16653hdr_ip([<name>[,<occ>]]) : ip (deprecated)
16654 This extracts the last occurrence of header <name> in an HTTP request,
16655 converts it to an IPv4 or IPv6 address and returns this address. When used
16656 with ACLs, all occurrences are checked, and if <name> is omitted, every value
16657 of every header is checked. Optionally, a specific occurrence might be
16658 specified as a position number. Positive values indicate a position from the
Davor Ocelice9ed2812017-12-25 17:49:28 +010016659 first occurrence, with 1 being the first one. Negative values indicate
Willy Tarreau74ca5042013-06-11 23:12:07 +020016660 positions relative to the last one, with -1 being the last one. A typical use
16661 is with the X-Forwarded-For and X-Client-IP headers.
16662
16663req.hdr_val([<name>[,<occ>]]) : integer
16664hdr_val([<name>[,<occ>]]) : integer (deprecated)
16665 This extracts the last occurrence of header <name> in an HTTP request, and
16666 converts it to an integer value. When used with ACLs, all occurrences are
16667 checked, and if <name> is omitted, every value of every header is checked.
16668 Optionally, a specific occurrence might be specified as a position number.
16669 Positive values indicate a position from the first occurrence, with 1 being
16670 the first one. Negative values indicate positions relative to the last one,
16671 with -1 being the last one. A typical use is with the X-Forwarded-For header.
16672
Frédéric Lécailleec891192019-02-26 15:02:35 +010016673
16674
Willy Tarreau74ca5042013-06-11 23:12:07 +020016675http_auth(<userlist>) : boolean
16676 Returns a boolean indicating whether the authentication data received from
16677 the client match a username & password stored in the specified userlist. This
16678 fetch function is not really useful outside of ACLs. Currently only http
16679 basic auth is supported.
16680
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010016681http_auth_group(<userlist>) : string
16682 Returns a string corresponding to the user name found in the authentication
16683 data received from the client if both the user name and password are valid
16684 according to the specified userlist. The main purpose is to use it in ACLs
16685 where it is then checked whether the user belongs to any group within a list.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016686 This fetch function is not really useful outside of ACLs. Currently only http
16687 basic auth is supported.
16688
16689 ACL derivatives :
Thierry FOURNIER9eec0a62014-01-22 18:38:02 +010016690 http_auth_group(<userlist>) : group ...
16691 Returns true when the user extracted from the request and whose password is
16692 valid according to the specified userlist belongs to at least one of the
16693 groups.
Willy Tarreau74ca5042013-06-11 23:12:07 +020016694
16695http_first_req : boolean
Willy Tarreau7f18e522010-10-22 20:04:13 +020016696 Returns true when the request being processed is the first one of the
16697 connection. This can be used to add or remove headers that may be missing
Willy Tarreau74ca5042013-06-11 23:12:07 +020016698 from some requests when a request is not the first one, or to help grouping
16699 requests in the logs.
Willy Tarreau7f18e522010-10-22 20:04:13 +020016700
Willy Tarreau74ca5042013-06-11 23:12:07 +020016701method : integer + string
16702 Returns an integer value corresponding to the method in the HTTP request. For
16703 example, "GET" equals 1 (check sources to establish the matching). Value 9
16704 means "other method" and may be converted to a string extracted from the
16705 stream. This should not be used directly as a sample, this is only meant to
16706 be used from ACLs, which transparently convert methods from patterns to these
16707 integer + string values. Some predefined ACL already check for most common
16708 methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016709
Willy Tarreau74ca5042013-06-11 23:12:07 +020016710 ACL derivatives :
16711 method : case insensitive method match
Willy Tarreau6a06a402007-07-15 20:15:28 +020016712
Willy Tarreau74ca5042013-06-11 23:12:07 +020016713 Example :
16714 # only accept GET and HEAD requests
16715 acl valid_method method GET HEAD
16716 http-request deny if ! valid_method
Willy Tarreau6a06a402007-07-15 20:15:28 +020016717
Willy Tarreau74ca5042013-06-11 23:12:07 +020016718path : string
16719 This extracts the request's URL path, which starts at the first slash and
16720 ends before the question mark (without the host part). A typical use is with
16721 prefetch-capable caches, and with portals which need to aggregate multiple
16722 information from databases and keep them in caches. Note that with outgoing
16723 caches, it would be wiser to use "url" instead. With ACLs, it's typically
Davor Ocelice9ed2812017-12-25 17:49:28 +010016724 used to match exact file names (e.g. "/login.php"), or directory parts using
Willy Tarreau74ca5042013-06-11 23:12:07 +020016725 the derivative forms. See also the "url" and "base" fetch methods.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016726
Willy Tarreau74ca5042013-06-11 23:12:07 +020016727 ACL derivatives :
16728 path : exact string match
16729 path_beg : prefix match
16730 path_dir : subdir match
16731 path_dom : domain match
16732 path_end : suffix match
16733 path_len : length match
16734 path_reg : regex match
16735 path_sub : substring match
Willy Tarreau6a06a402007-07-15 20:15:28 +020016736
Willy Tarreau49ad95c2015-01-19 15:06:26 +010016737query : string
16738 This extracts the request's query string, which starts after the first
16739 question mark. If no question mark is present, this fetch returns nothing. If
16740 a question mark is present but nothing follows, it returns an empty string.
16741 This means it's possible to easily know whether a query string is present
Tim Düsterhus4896c442016-11-29 02:15:19 +010016742 using the "found" matching method. This fetch is the complement of "path"
Willy Tarreau49ad95c2015-01-19 15:06:26 +010016743 which stops before the question mark.
16744
Willy Tarreaueb27ec72015-02-20 13:55:29 +010016745req.hdr_names([<delim>]) : string
16746 This builds a string made from the concatenation of all header names as they
16747 appear in the request when the rule is evaluated. The default delimiter is
16748 the comma (',') but it may be overridden as an optional argument <delim>. In
16749 this case, only the first character of <delim> is considered.
16750
Willy Tarreau74ca5042013-06-11 23:12:07 +020016751req.ver : string
16752req_ver : string (deprecated)
16753 Returns the version string from the HTTP request, for example "1.1". This can
16754 be useful for logs, but is mostly there for ACL. Some predefined ACL already
16755 check for versions 1.0 and 1.1.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016756
Willy Tarreau74ca5042013-06-11 23:12:07 +020016757 ACL derivatives :
16758 req_ver : exact string match
Willy Tarreau0e698542011-09-16 08:32:32 +020016759
Willy Tarreau74ca5042013-06-11 23:12:07 +020016760res.comp : boolean
16761 Returns the boolean "true" value if the response has been compressed by
16762 HAProxy, otherwise returns boolean "false". This may be used to add
16763 information in the logs.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016764
Willy Tarreau74ca5042013-06-11 23:12:07 +020016765res.comp_algo : string
16766 Returns a string containing the name of the algorithm used if the response
16767 was compressed by HAProxy, for example : "deflate". This may be used to add
16768 some information in the logs.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016769
Willy Tarreau74ca5042013-06-11 23:12:07 +020016770res.cook([<name>]) : string
16771scook([<name>]) : string (deprecated)
16772 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
16773 header line from the response, and returns its value as string. If no name is
16774 specified, the first cookie value is returned.
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020016775
Willy Tarreau74ca5042013-06-11 23:12:07 +020016776 ACL derivatives :
16777 scook([<name>] : exact string match
Willy Tarreau0ce3aa02012-04-25 18:46:33 +020016778
Willy Tarreau74ca5042013-06-11 23:12:07 +020016779res.cook_cnt([<name>]) : integer
16780scook_cnt([<name>]) : integer (deprecated)
16781 Returns an integer value representing the number of occurrences of the cookie
16782 <name> in the response, or all cookies if <name> is not specified. This is
16783 mostly useful when combined with ACLs to detect suspicious responses.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016784
Willy Tarreau74ca5042013-06-11 23:12:07 +020016785res.cook_val([<name>]) : integer
16786scook_val([<name>]) : integer (deprecated)
16787 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
16788 header line from the response, and converts its value to an integer which is
16789 returned. If no name is specified, the first cookie value is returned.
Willy Tarreaud63335a2010-02-26 12:56:52 +010016790
Willy Tarreau74ca5042013-06-11 23:12:07 +020016791res.fhdr([<name>[,<occ>]]) : string
16792 This extracts the last occurrence of header <name> in an HTTP response, or of
16793 the last header if no <name> is specified. Optionally, a specific occurrence
16794 might be specified as a position number. Positive values indicate a position
16795 from the first occurrence, with 1 being the first one. Negative values
16796 indicate positions relative to the last one, with -1 being the last one. It
16797 differs from res.hdr() in that any commas present in the value are returned
16798 and are not used as delimiters. If this is not desired, the res.hdr() fetch
16799 should be used instead. This is sometimes useful with headers such as Date or
16800 Expires.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016801
Willy Tarreau74ca5042013-06-11 23:12:07 +020016802res.fhdr_cnt([<name>]) : integer
16803 Returns an integer value representing the number of occurrences of response
16804 header field name <name>, or the total number of header fields if <name> is
16805 not specified. Contrary to its res.hdr_cnt() cousin, this function returns
16806 the number of full line headers and does not stop on commas. If this is not
16807 desired, the res.hdr_cnt() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016808
Willy Tarreau74ca5042013-06-11 23:12:07 +020016809res.hdr([<name>[,<occ>]]) : string
16810shdr([<name>[,<occ>]]) : string (deprecated)
16811 This extracts the last occurrence of header <name> in an HTTP response, or of
16812 the last header if no <name> is specified. Optionally, a specific occurrence
16813 might be specified as a position number. Positive values indicate a position
16814 from the first occurrence, with 1 being the first one. Negative values
16815 indicate positions relative to the last one, with -1 being the last one. This
16816 can be useful to learn some data into a stick-table. The function considers
16817 any comma as a delimiter for distinct values. If this is not desired, the
16818 res.fhdr() fetch should be used instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016819
Willy Tarreau74ca5042013-06-11 23:12:07 +020016820 ACL derivatives :
16821 shdr([<name>[,<occ>]]) : exact string match
16822 shdr_beg([<name>[,<occ>]]) : prefix match
16823 shdr_dir([<name>[,<occ>]]) : subdir match
16824 shdr_dom([<name>[,<occ>]]) : domain match
16825 shdr_end([<name>[,<occ>]]) : suffix match
16826 shdr_len([<name>[,<occ>]]) : length match
16827 shdr_reg([<name>[,<occ>]]) : regex match
16828 shdr_sub([<name>[,<occ>]]) : substring match
16829
16830res.hdr_cnt([<name>]) : integer
16831shdr_cnt([<name>]) : integer (deprecated)
16832 Returns an integer value representing the number of occurrences of response
16833 header field name <name>, or the total number of header fields if <name> is
16834 not specified. The function considers any comma as a delimiter for distinct
16835 values. If this is not desired, the res.fhdr_cnt() fetch should be used
16836 instead.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016837
Willy Tarreau74ca5042013-06-11 23:12:07 +020016838res.hdr_ip([<name>[,<occ>]]) : ip
16839shdr_ip([<name>[,<occ>]]) : ip (deprecated)
16840 This extracts the last occurrence of header <name> in an HTTP response,
16841 convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
16842 specific occurrence might be specified as a position number. Positive values
16843 indicate a position from the first occurrence, with 1 being the first one.
16844 Negative values indicate positions relative to the last one, with -1 being
16845 the last one. This can be useful to learn some data into a stick table.
Willy Tarreau6a06a402007-07-15 20:15:28 +020016846
Willy Tarreaueb27ec72015-02-20 13:55:29 +010016847res.hdr_names([<delim>]) : string
16848 This builds a string made from the concatenation of all header names as they
16849 appear in the response when the rule is evaluated. The default delimiter is
16850 the comma (',') but it may be overridden as an optional argument <delim>. In
16851 this case, only the first character of <delim> is considered.
16852
Willy Tarreau74ca5042013-06-11 23:12:07 +020016853res.hdr_val([<name>[,<occ>]]) : integer
16854shdr_val([<name>[,<occ>]]) : integer (deprecated)
16855 This extracts the last occurrence of header <name> in an HTTP response, and
16856 converts it to an integer value. Optionally, a specific occurrence might be
16857 specified as a position number. Positive values indicate a position from the
16858 first occurrence, with 1 being the first one. Negative values indicate
16859 positions relative to the last one, with -1 being the last one. This can be
16860 useful to learn some data into a stick table.
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010016861
Willy Tarreau74ca5042013-06-11 23:12:07 +020016862res.ver : string
16863resp_ver : string (deprecated)
16864 Returns the version string from the HTTP response, for example "1.1". This
16865 can be useful for logs, but is mostly there for ACL.
Willy Tarreau0e698542011-09-16 08:32:32 +020016866
Willy Tarreau74ca5042013-06-11 23:12:07 +020016867 ACL derivatives :
16868 resp_ver : exact string match
Alexandre Cassen5eb1a902007-11-29 15:43:32 +010016869
Willy Tarreau74ca5042013-06-11 23:12:07 +020016870set-cookie([<name>]) : string (deprecated)
16871 This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
16872 header line from the response and uses the corresponding value to match. This
Willy Tarreau294d0f02015-08-10 19:40:12 +020016873 can be comparable to what "appsession" did with default options, but with
Willy Tarreau74ca5042013-06-11 23:12:07 +020016874 support for multi-peer synchronization and state keeping across restarts.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010016875
Willy Tarreau74ca5042013-06-11 23:12:07 +020016876 This fetch function is deprecated and has been superseded by the "res.cook"
16877 fetch. This keyword will disappear soon.
Krzysztof Piotr Oledzki6b35ce12010-02-01 23:35:44 +010016878
Willy Tarreau74ca5042013-06-11 23:12:07 +020016879status : integer
16880 Returns an integer containing the HTTP status code in the HTTP response, for
16881 example, 302. It is mostly used within ACLs and integer ranges, for example,
16882 to remove any Location header if the response is not a 3xx.
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016883
Thierry Fournier0e00dca2016-04-07 15:47:40 +020016884unique-id : string
16885 Returns the unique-id attached to the request. The directive
16886 "unique-id-format" must be set. If it is not set, the unique-id sample fetch
16887 fails. Note that the unique-id is usually used with HTTP requests, however this
16888 sample fetch can be used with other protocols. Obviously, if it is used with
16889 other protocols than HTTP, the unique-id-format directive must not contain
16890 HTTP parts. See: unique-id-format and unique-id-header
16891
Willy Tarreau74ca5042013-06-11 23:12:07 +020016892url : string
16893 This extracts the request's URL as presented in the request. A typical use is
16894 with prefetch-capable caches, and with portals which need to aggregate
16895 multiple information from databases and keep them in caches. With ACLs, using
16896 "path" is preferred over using "url", because clients may send a full URL as
16897 is normally done with proxies. The only real use is to match "*" which does
16898 not match in "path", and for which there is already a predefined ACL. See
16899 also "path" and "base".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016900
Willy Tarreau74ca5042013-06-11 23:12:07 +020016901 ACL derivatives :
16902 url : exact string match
16903 url_beg : prefix match
16904 url_dir : subdir match
16905 url_dom : domain match
16906 url_end : suffix match
16907 url_len : length match
16908 url_reg : regex match
16909 url_sub : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016910
Willy Tarreau74ca5042013-06-11 23:12:07 +020016911url_ip : ip
16912 This extracts the IP address from the request's URL when the host part is
16913 presented as an IP address. Its use is very limited. For instance, a
16914 monitoring system might use this field as an alternative for the source IP in
16915 order to test what path a given source address would follow, or to force an
16916 entry in a table for a given source address. With ACLs it can be used to
16917 restrict access to certain systems through a proxy, for example when combined
16918 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016919
Willy Tarreau74ca5042013-06-11 23:12:07 +020016920url_port : integer
16921 This extracts the port part from the request's URL. Note that if the port is
16922 not specified in the request, port 80 is assumed. With ACLs it can be used to
16923 restrict access to certain systems through a proxy, for example when combined
16924 with option "http_proxy".
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016925
Willy Tarreau1ede1da2015-05-07 16:06:18 +020016926urlp([<name>[,<delim>]]) : string
16927url_param([<name>[,<delim>]]) : string
Willy Tarreau74ca5042013-06-11 23:12:07 +020016928 This extracts the first occurrence of the parameter <name> in the query
16929 string, which begins after either '?' or <delim>, and which ends before '&',
Willy Tarreau1ede1da2015-05-07 16:06:18 +020016930 ';' or <delim>. The parameter name is case-sensitive. If no name is given,
16931 any parameter will match, and the first one will be returned. The result is
16932 a string corresponding to the value of the parameter <name> as presented in
16933 the request (no URL decoding is performed). This can be used for session
Willy Tarreau74ca5042013-06-11 23:12:07 +020016934 stickiness based on a client ID, to extract an application cookie passed as a
16935 URL parameter, or in ACLs to apply some checks. Note that the ACL version of
Willy Tarreau1ede1da2015-05-07 16:06:18 +020016936 this fetch iterates over multiple parameters and will iteratively report all
16937 parameters values if no name is given
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016938
Willy Tarreau74ca5042013-06-11 23:12:07 +020016939 ACL derivatives :
16940 urlp(<name>[,<delim>]) : exact string match
16941 urlp_beg(<name>[,<delim>]) : prefix match
16942 urlp_dir(<name>[,<delim>]) : subdir match
16943 urlp_dom(<name>[,<delim>]) : domain match
16944 urlp_end(<name>[,<delim>]) : suffix match
16945 urlp_len(<name>[,<delim>]) : length match
16946 urlp_reg(<name>[,<delim>]) : regex match
16947 urlp_sub(<name>[,<delim>]) : substring match
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016948
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016949
Willy Tarreau74ca5042013-06-11 23:12:07 +020016950 Example :
16951 # match http://example.com/foo?PHPSESSIONID=some_id
16952 stick on urlp(PHPSESSIONID)
16953 # match http://example.com/foo;JSESSIONID=some_id
16954 stick on urlp(JSESSIONID,;)
Willy Tarreau25c1ebc2012-04-25 16:21:44 +020016955
Jarno Huuskonen676f6222017-03-30 09:19:45 +030016956urlp_val([<name>[,<delim>]]) : integer
Willy Tarreau74ca5042013-06-11 23:12:07 +020016957 See "urlp" above. This one extracts the URL parameter <name> in the request
16958 and converts it to an integer value. This can be used for session stickiness
16959 based on a user ID for example, or with ACLs to match a page number or price.
Willy Tarreaua9fddca2012-07-31 07:51:48 +020016960
Dragan Dosen0070cd52016-06-16 12:19:49 +020016961url32 : integer
16962 This returns a 32-bit hash of the value obtained by concatenating the first
16963 Host header and the whole URL including parameters (not only the path part of
16964 the request, as in the "base32" fetch above). This is useful to track per-URL
16965 activity. A shorter hash is stored, saving a lot of memory. The output type
16966 is an unsigned integer.
16967
16968url32+src : binary
16969 This returns the concatenation of the "url32" fetch and the "src" fetch. The
16970 resulting type is of type binary, with a size of 8 or 20 bytes depending on
16971 the source address family. This can be used to track per-IP, per-URL counters.
16972
Willy Tarreau198a7442008-01-17 12:05:32 +010016973
Willy Tarreau74ca5042013-06-11 23:12:07 +0200169747.4. Pre-defined ACLs
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016975---------------------
Willy Tarreauced27012008-01-17 20:35:34 +010016976
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016977Some predefined ACLs are hard-coded so that they do not have to be declared in
16978every frontend which needs them. They all have their names in upper case in
Patrick Mézard2382ad62010-05-09 10:43:32 +020016979order to avoid confusion. Their equivalence is provided below.
Willy Tarreauced27012008-01-17 20:35:34 +010016980
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016981ACL name Equivalent to Usage
16982---------------+-----------------------------+---------------------------------
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016983FALSE always_false never match
Willy Tarreau2492d5b2009-07-11 00:06:00 +020016984HTTP req_proto_http match if protocol is valid HTTP
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016985HTTP_1.0 req_ver 1.0 match HTTP version 1.0
16986HTTP_1.1 req_ver 1.1 match HTTP version 1.1
Willy Tarreaud63335a2010-02-26 12:56:52 +010016987HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length
16988HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme
16989HTTP_URL_SLASH url_beg / match URL beginning with "/"
16990HTTP_URL_STAR url * match URL equal to "*"
16991LOCALHOST src 127.0.0.1/8 match connection from local host
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016992METH_CONNECT method CONNECT match HTTP CONNECT method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020016993METH_DELETE method DELETE match HTTP DELETE method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016994METH_GET method GET HEAD match HTTP GET or HEAD method
16995METH_HEAD method HEAD match HTTP HEAD method
16996METH_OPTIONS method OPTIONS match HTTP OPTIONS method
16997METH_POST method POST match HTTP POST method
Daniel Schneller9ff96c72016-04-11 17:45:29 +020016998METH_PUT method PUT match HTTP PUT method
Willy Tarreauc57f0e22009-05-10 13:12:33 +020016999METH_TRACE method TRACE match HTTP TRACE method
Emeric Brunbede3d02009-06-30 17:54:00 +020017000RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017001REQ_CONTENT req_len gt 0 match data in the request buffer
Willy Tarreaud63335a2010-02-26 12:56:52 +010017002TRUE always_true always match
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017003WAIT_END wait_end wait for end of content analysis
17004---------------+-----------------------------+---------------------------------
Willy Tarreauced27012008-01-17 20:35:34 +010017005
Willy Tarreaub937b7e2010-01-12 15:27:54 +010017006
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170078. Logging
17008----------
Willy Tarreau844e3c52008-01-11 16:28:18 +010017009
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017010One of HAProxy's strong points certainly lies is its precise logs. It probably
17011provides the finest level of information available for such a product, which is
17012very important for troubleshooting complex environments. Standard information
17013provided in logs include client ports, TCP/HTTP state timers, precise session
17014state at termination and precise termination cause, information about decisions
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010017015to direct traffic to a server, and of course the ability to capture arbitrary
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017016headers.
17017
17018In order to improve administrators reactivity, it offers a great transparency
17019about encountered problems, both internal and external, and it is possible to
17020send logs to different sources at the same time with different level filters :
17021
17022 - global process-level logs (system errors, start/stop, etc..)
17023 - per-instance system and internal errors (lack of resource, bugs, ...)
17024 - per-instance external troubles (servers up/down, max connections)
17025 - per-instance activity (client connections), either at the establishment or
17026 at the termination.
Davor Ocelice9ed2812017-12-25 17:49:28 +010017027 - per-request control of log-level, e.g.
Jim Freeman9e8714b2015-05-26 09:16:34 -060017028 http-request set-log-level silent if sensitive_request
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017029
17030The ability to distribute different levels of logs to different log servers
17031allow several production teams to interact and to fix their problems as soon
17032as possible. For example, the system team might monitor system-wide errors,
17033while the application team might be monitoring the up/down for their servers in
17034real time, and the security team might analyze the activity logs with one hour
17035delay.
17036
17037
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170388.1. Log levels
17039---------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017040
Simon Hormandf791f52011-05-29 15:01:10 +090017041TCP and HTTP connections can be logged with information such as the date, time,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017042source IP address, destination address, connection duration, response times,
Simon Hormandf791f52011-05-29 15:01:10 +090017043HTTP request, HTTP return code, number of bytes transmitted, conditions
17044in which the session ended, and even exchanged cookies values. For example
17045track a particular user's problems. All messages may be sent to up to two
17046syslog servers. Check the "log" keyword in section 4.2 for more information
17047about log facilities.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017048
17049
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170508.2. Log formats
17051----------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017052
William Lallemand48940402012-01-30 16:47:22 +010017053HAProxy supports 5 log formats. Several fields are common between these formats
Simon Hormandf791f52011-05-29 15:01:10 +090017054and will be detailed in the following sections. A few of them may vary
17055slightly with the configuration, due to indicators specific to certain
17056options. The supported formats are as follows :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017057
17058 - the default format, which is very basic and very rarely used. It only
17059 provides very basic information about the incoming connection at the moment
17060 it is accepted : source IP:port, destination IP:port, and frontend-name.
17061 This mode will eventually disappear so it will not be described to great
17062 extents.
17063
17064 - the TCP format, which is more advanced. This format is enabled when "option
17065 tcplog" is set on the frontend. HAProxy will then usually wait for the
17066 connection to terminate before logging. This format provides much richer
17067 information, such as timers, connection counts, queue size, etc... This
17068 format is recommended for pure TCP proxies.
17069
17070 - the HTTP format, which is the most advanced for HTTP proxying. This format
17071 is enabled when "option httplog" is set on the frontend. It provides the
17072 same information as the TCP format with some HTTP-specific fields such as
17073 the request, the status code, and captures of headers and cookies. This
17074 format is recommended for HTTP proxies.
17075
Emeric Brun3a058f32009-06-30 18:26:00 +020017076 - the CLF HTTP format, which is equivalent to the HTTP format, but with the
17077 fields arranged in the same order as the CLF format. In this mode, all
17078 timers, captures, flags, etc... appear one per field after the end of the
17079 common fields, in the same order they appear in the standard HTTP format.
17080
William Lallemand48940402012-01-30 16:47:22 +010017081 - the custom log format, allows you to make your own log line.
17082
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017083Next sections will go deeper into details for each of these formats. Format
17084specification will be performed on a "field" basis. Unless stated otherwise, a
17085field is a portion of text delimited by any number of spaces. Since syslog
17086servers are susceptible of inserting fields at the beginning of a line, it is
17087always assumed that the first field is the one containing the process name and
17088identifier.
17089
17090Note : Since log lines may be quite long, the log examples in sections below
17091 might be broken into multiple lines. The example log lines will be
17092 prefixed with 3 closing angle brackets ('>>>') and each time a log is
17093 broken into multiple lines, each non-final line will end with a
17094 backslash ('\') and the next line will start indented by two characters.
17095
17096
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200170978.2.1. Default log format
17098-------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017099
17100This format is used when no specific option is set. The log is emitted as soon
17101as the connection is accepted. One should note that this currently is the only
17102format which logs the request's destination IP and ports.
17103
17104 Example :
17105 listen www
17106 mode http
17107 log global
17108 server srv1 127.0.0.1:8000
17109
17110 >>> Feb 6 12:12:09 localhost \
17111 haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \
17112 (www/HTTP)
17113
17114 Field Format Extract from the example above
17115 1 process_name '[' pid ']:' haproxy[14385]:
17116 2 'Connect from' Connect from
17117 3 source_ip ':' source_port 10.0.1.2:33312
17118 4 'to' to
17119 5 destination_ip ':' destination_port 10.0.3.31:8012
17120 6 '(' frontend_name '/' mode ')' (www/HTTP)
17121
17122Detailed fields description :
17123 - "source_ip" is the IP address of the client which initiated the connection.
17124 - "source_port" is the TCP port of the client which initiated the connection.
17125 - "destination_ip" is the IP address the client connected to.
17126 - "destination_port" is the TCP port the client connected to.
17127 - "frontend_name" is the name of the frontend (or listener) which received
17128 and processed the connection.
17129 - "mode is the mode the frontend is operating (TCP or HTTP).
17130
Willy Tarreauceb24bc2010-11-09 12:46:41 +010017131In case of a UNIX socket, the source and destination addresses are marked as
17132"unix:" and the ports reflect the internal ID of the socket which accepted the
17133connection (the same ID as reported in the stats).
17134
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017135It is advised not to use this deprecated format for newer installations as it
17136will eventually disappear.
17137
17138
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200171398.2.2. TCP log format
17140---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017141
17142The TCP format is used when "option tcplog" is specified in the frontend, and
17143is the recommended format for pure TCP proxies. It provides a lot of precious
17144information for troubleshooting. Since this format includes timers and byte
17145counts, the log is normally emitted at the end of the session. It can be
17146emitted earlier if "option logasap" is specified, which makes sense in most
17147environments with long sessions such as remote terminals. Sessions which match
17148the "monitor" rules are never logged. It is also possible not to emit logs for
17149sessions for which no data were exchanged between the client and the server, by
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020017150specifying "option dontlognull" in the frontend. Successful connections will
17151not be logged if "option dontlog-normal" is specified in the frontend. A few
17152fields may slightly vary depending on some configuration options, those are
17153marked with a star ('*') after the field name below.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017154
17155 Example :
17156 frontend fnt
17157 mode tcp
17158 option tcplog
17159 log global
17160 default_backend bck
17161
17162 backend bck
17163 server srv1 127.0.0.1:8000
17164
17165 >>> Feb 6 12:12:56 localhost \
17166 haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \
17167 bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0
17168
17169 Field Format Extract from the example above
17170 1 process_name '[' pid ']:' haproxy[14387]:
17171 2 client_ip ':' client_port 10.0.1.2:33313
17172 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443]
17173 4 frontend_name fnt
17174 5 backend_name '/' server_name bck/srv1
17175 6 Tw '/' Tc '/' Tt* 0/0/5007
17176 7 bytes_read* 212
17177 8 termination_state --
17178 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3
17179 10 srv_queue '/' backend_queue 0/0
17180
17181Detailed fields description :
17182 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010017183 connection to haproxy. If the connection was accepted on a UNIX socket
17184 instead, the IP address would be replaced with the word "unix". Note that
17185 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010017186 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010017187 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010017188 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017189
17190 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010017191 If the connection was accepted on a UNIX socket instead, the port would be
17192 replaced with the ID of the accepting socket, which is also reported in the
17193 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017194
17195 - "accept_date" is the exact date when the connection was received by haproxy
17196 (which might be very slightly different from the date observed on the
17197 network if there was some queuing in the system's backlog). This is usually
Willy Tarreau590a0512018-09-05 11:56:48 +020017198 the same date which may appear in any upstream firewall's log. When used in
17199 HTTP mode, the accept_date field will be reset to the first moment the
17200 connection is ready to receive a new request (end of previous response for
17201 HTTP/1, immediately after previous request for HTTP/2).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017202
17203 - "frontend_name" is the name of the frontend (or listener) which received
17204 and processed the connection.
17205
17206 - "backend_name" is the name of the backend (or listener) which was selected
17207 to manage the connection to the server. This will be the same as the
17208 frontend if no switching rule has been applied, which is common for TCP
17209 applications.
17210
17211 - "server_name" is the name of the last server to which the connection was
17212 sent, which might differ from the first one if there were connection errors
17213 and a redispatch occurred. Note that this server belongs to the backend
17214 which processed the request. If the connection was aborted before reaching
17215 a server, "<NOSRV>" is indicated instead of a server name.
17216
17217 - "Tw" is the total time in milliseconds spent waiting in the various queues.
17218 It can be "-1" if the connection was aborted before reaching the queue.
17219 See "Timers" below for more details.
17220
17221 - "Tc" is the total time in milliseconds spent waiting for the connection to
17222 establish to the final server, including retries. It can be "-1" if the
17223 connection was aborted before a connection could be established. See
17224 "Timers" below for more details.
17225
17226 - "Tt" is the total time in milliseconds elapsed between the accept and the
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017227 last close. It covers all possible processing. There is one exception, if
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017228 "option logasap" was specified, then the time counting stops at the moment
17229 the log is emitted. In this case, a '+' sign is prepended before the value,
17230 indicating that the final one will be larger. See "Timers" below for more
17231 details.
17232
17233 - "bytes_read" is the total number of bytes transmitted from the server to
17234 the client when the log is emitted. If "option logasap" is specified, the
17235 this value will be prefixed with a '+' sign indicating that the final one
17236 may be larger. Please note that this value is a 64-bit counter, so log
17237 analysis tools must be able to handle it without overflowing.
17238
17239 - "termination_state" is the condition the session was in when the session
17240 ended. This indicates the session state, which side caused the end of
17241 session to happen, and for what reason (timeout, error, ...). The normal
17242 flags should be "--", indicating the session was closed by either end with
17243 no data remaining in buffers. See below "Session state at disconnection"
17244 for more details.
17245
17246 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017247 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017248 limits have been reached. For instance, if actconn is close to 512 when
17249 multiple connection errors occur, chances are high that the system limits
17250 the process to use a maximum of 1024 file descriptors and that all of them
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017251 are used. See section 3 "Global parameters" to find how to tune the system.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017252
17253 - "feconn" is the total number of concurrent connections on the frontend when
17254 the session was logged. It is useful to estimate the amount of resource
17255 required to sustain high loads, and to detect when the frontend's "maxconn"
17256 has been reached. Most often when this value increases by huge jumps, it is
17257 because there is congestion on the backend servers, but sometimes it can be
17258 caused by a denial of service attack.
17259
17260 - "beconn" is the total number of concurrent connections handled by the
17261 backend when the session was logged. It includes the total number of
17262 concurrent connections active on servers as well as the number of
17263 connections pending in queues. It is useful to estimate the amount of
17264 additional servers needed to support high loads for a given application.
17265 Most often when this value increases by huge jumps, it is because there is
17266 congestion on the backend servers, but sometimes it can be caused by a
17267 denial of service attack.
17268
17269 - "srv_conn" is the total number of concurrent connections still active on
17270 the server when the session was logged. It can never exceed the server's
17271 configured "maxconn" parameter. If this value is very often close or equal
17272 to the server's "maxconn", it means that traffic regulation is involved a
17273 lot, meaning that either the server's maxconn value is too low, or that
17274 there aren't enough servers to process the load with an optimal response
17275 time. When only one of the server's "srv_conn" is high, it usually means
17276 that this server has some trouble causing the connections to take longer to
17277 be processed than on other servers.
17278
17279 - "retries" is the number of connection retries experienced by this session
17280 when trying to connect to the server. It must normally be zero, unless a
17281 server is being stopped at the same moment the connection was attempted.
17282 Frequent retries generally indicate either a network problem between
17283 haproxy and the server, or a misconfigured system backlog on the server
17284 preventing new connections from being queued. This field may optionally be
17285 prefixed with a '+' sign, indicating that the session has experienced a
17286 redispatch after the maximal retry count has been reached on the initial
17287 server. In this case, the server name appearing in the log is the one the
17288 connection was redispatched to, and not the first one, though both may
17289 sometimes be the same in case of hashing for instance. So as a general rule
17290 of thumb, when a '+' is present in front of the retry count, this count
17291 should not be attributed to the logged server.
17292
17293 - "srv_queue" is the total number of requests which were processed before
17294 this one in the server queue. It is zero when the request has not gone
17295 through the server queue. It makes it possible to estimate the approximate
17296 server's response time by dividing the time spent in queue by the number of
17297 requests in the queue. It is worth noting that if a session experiences a
17298 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010017299 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017300 backend queue unless a redispatch occurs.
17301
17302 - "backend_queue" is the total number of requests which were processed before
17303 this one in the backend's global queue. It is zero when the request has not
17304 gone through the global queue. It makes it possible to estimate the average
17305 queue length, which easily translates into a number of missing servers when
17306 divided by a server's "maxconn" parameter. It is worth noting that if a
17307 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010017308 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017309 through both the server queue and the backend queue unless a redispatch
17310 occurs.
17311
17312
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200173138.2.3. HTTP log format
17314----------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017315
17316The HTTP format is the most complete and the best suited for HTTP proxies. It
17317is enabled by when "option httplog" is specified in the frontend. It provides
17318the same level of information as the TCP format with additional features which
17319are specific to the HTTP protocol. Just like the TCP format, the log is usually
17320emitted at the end of the session, unless "option logasap" is specified, which
17321generally only makes sense for download sites. A session which matches the
17322"monitor" rules will never logged. It is also possible not to log sessions for
17323which no data were sent by the client by specifying "option dontlognull" in the
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020017324frontend. Successful connections will not be logged if "option dontlog-normal"
17325is specified in the frontend.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017326
17327Most fields are shared with the TCP log, some being different. A few fields may
17328slightly vary depending on some configuration options. Those ones are marked
17329with a star ('*') after the field name below.
17330
17331 Example :
17332 frontend http-in
17333 mode http
17334 option httplog
17335 log global
17336 default_backend bck
17337
17338 backend static
17339 server srv1 127.0.0.1:8000
17340
17341 >>> Feb 6 12:14:14 localhost \
17342 haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \
17343 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 +010017344 {} "GET /index.html HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017345
17346 Field Format Extract from the example above
17347 1 process_name '[' pid ']:' haproxy[14389]:
17348 2 client_ip ':' client_port 10.0.1.2:33317
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017349 3 '[' request_date ']' [06/Feb/2009:12:14:14.655]
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017350 4 frontend_name http-in
17351 5 backend_name '/' server_name static/srv1
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017352 6 TR '/' Tw '/' Tc '/' Tr '/' Ta* 10/0/30/69/109
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017353 7 status_code 200
17354 8 bytes_read* 2750
17355 9 captured_request_cookie -
17356 10 captured_response_cookie -
17357 11 termination_state ----
17358 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0
17359 13 srv_queue '/' backend_queue 0/0
17360 14 '{' captured_request_headers* '}' {haproxy.1wt.eu}
17361 15 '{' captured_response_headers* '}' {}
17362 16 '"' http_request '"' "GET /index.html HTTP/1.1"
Willy Tarreaud72758d2010-01-12 10:42:19 +010017363
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017364Detailed fields description :
17365 - "client_ip" is the IP address of the client which initiated the TCP
Willy Tarreauceb24bc2010-11-09 12:46:41 +010017366 connection to haproxy. If the connection was accepted on a UNIX socket
17367 instead, the IP address would be replaced with the word "unix". Note that
17368 when the connection is accepted on a socket configured with "accept-proxy"
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010017369 and the PROXY protocol is correctly used, or with a "accept-netscaler-cip"
Davor Ocelice9ed2812017-12-25 17:49:28 +010017370 and the NetScaler Client IP insertion protocol is correctly used, then the
Bertrand Jacquin93b227d2016-06-04 15:11:10 +010017371 logs will reflect the forwarded connection's information.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017372
17373 - "client_port" is the TCP port of the client which initiated the connection.
Willy Tarreauceb24bc2010-11-09 12:46:41 +010017374 If the connection was accepted on a UNIX socket instead, the port would be
17375 replaced with the ID of the accepting socket, which is also reported in the
17376 stats interface.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017377
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017378 - "request_date" is the exact date when the first byte of the HTTP request
17379 was received by haproxy (log field %tr).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017380
17381 - "frontend_name" is the name of the frontend (or listener) which received
17382 and processed the connection.
17383
17384 - "backend_name" is the name of the backend (or listener) which was selected
17385 to manage the connection to the server. This will be the same as the
17386 frontend if no switching rule has been applied.
17387
17388 - "server_name" is the name of the last server to which the connection was
17389 sent, which might differ from the first one if there were connection errors
17390 and a redispatch occurred. Note that this server belongs to the backend
17391 which processed the request. If the request was aborted before reaching a
17392 server, "<NOSRV>" is indicated instead of a server name. If the request was
17393 intercepted by the stats subsystem, "<STATS>" is indicated instead.
17394
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017395 - "TR" is the total time in milliseconds spent waiting for a full HTTP
17396 request from the client (not counting body) after the first byte was
17397 received. It can be "-1" if the connection was aborted before a complete
John Roesler27c754c2019-07-10 15:45:51 -050017398 request could be received or a bad request was received. It should
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017399 always be very small because a request generally fits in one single packet.
17400 Large times here generally indicate network issues between the client and
Willy Tarreau590a0512018-09-05 11:56:48 +020017401 haproxy or requests being typed by hand. See section 8.4 "Timing Events"
17402 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017403
17404 - "Tw" is the total time in milliseconds spent waiting in the various queues.
17405 It can be "-1" if the connection was aborted before reaching the queue.
Willy Tarreau590a0512018-09-05 11:56:48 +020017406 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017407
17408 - "Tc" is the total time in milliseconds spent waiting for the connection to
17409 establish to the final server, including retries. It can be "-1" if the
Willy Tarreau590a0512018-09-05 11:56:48 +020017410 request was aborted before a connection could be established. See section
17411 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017412
17413 - "Tr" is the total time in milliseconds spent waiting for the server to send
17414 a full HTTP response, not counting data. It can be "-1" if the request was
17415 aborted before a complete response could be received. It generally matches
17416 the server's processing time for the request, though it may be altered by
17417 the amount of data sent by the client to the server. Large times here on
Willy Tarreau590a0512018-09-05 11:56:48 +020017418 "GET" requests generally indicate an overloaded server. See section 8.4
17419 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017420
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017421 - "Ta" is the time the request remained active in haproxy, which is the total
17422 time in milliseconds elapsed between the first byte of the request was
17423 received and the last byte of response was sent. It covers all possible
17424 processing except the handshake (see Th) and idle time (see Ti). There is
17425 one exception, if "option logasap" was specified, then the time counting
17426 stops at the moment the log is emitted. In this case, a '+' sign is
17427 prepended before the value, indicating that the final one will be larger.
Willy Tarreau590a0512018-09-05 11:56:48 +020017428 See section 8.4 "Timing Events" for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017429
17430 - "status_code" is the HTTP status code returned to the client. This status
17431 is generally set by the server, but it might also be set by haproxy when
17432 the server cannot be reached or when its response is blocked by haproxy.
17433
17434 - "bytes_read" is the total number of bytes transmitted to the client when
17435 the log is emitted. This does include HTTP headers. If "option logasap" is
John Roesler27c754c2019-07-10 15:45:51 -050017436 specified, this value will be prefixed with a '+' sign indicating that
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017437 the final one may be larger. Please note that this value is a 64-bit
17438 counter, so log analysis tools must be able to handle it without
17439 overflowing.
17440
17441 - "captured_request_cookie" is an optional "name=value" entry indicating that
17442 the client had this cookie in the request. The cookie name and its maximum
17443 length are defined by the "capture cookie" statement in the frontend
17444 configuration. The field is a single dash ('-') when the option is not
17445 set. Only one cookie may be captured, it is generally used to track session
17446 ID exchanges between a client and a server to detect session crossing
17447 between clients due to application bugs. For more details, please consult
17448 the section "Capturing HTTP headers and cookies" below.
17449
17450 - "captured_response_cookie" is an optional "name=value" entry indicating
17451 that the server has returned a cookie with its response. The cookie name
17452 and its maximum length are defined by the "capture cookie" statement in the
17453 frontend configuration. The field is a single dash ('-') when the option is
17454 not set. Only one cookie may be captured, it is generally used to track
17455 session ID exchanges between a client and a server to detect session
17456 crossing between clients due to application bugs. For more details, please
17457 consult the section "Capturing HTTP headers and cookies" below.
17458
17459 - "termination_state" is the condition the session was in when the session
17460 ended. This indicates the session state, which side caused the end of
17461 session to happen, for what reason (timeout, error, ...), just like in TCP
17462 logs, and information about persistence operations on cookies in the last
17463 two characters. The normal flags should begin with "--", indicating the
17464 session was closed by either end with no data remaining in buffers. See
17465 below "Session state at disconnection" for more details.
17466
17467 - "actconn" is the total number of concurrent connections on the process when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017468 the session was logged. It is useful to detect when some per-process system
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017469 limits have been reached. For instance, if actconn is close to 512 or 1024
17470 when multiple connection errors occur, chances are high that the system
17471 limits the process to use a maximum of 1024 file descriptors and that all
Willy Tarreauc57f0e22009-05-10 13:12:33 +020017472 of them are used. See section 3 "Global parameters" to find how to tune the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017473 system.
17474
17475 - "feconn" is the total number of concurrent connections on the frontend when
17476 the session was logged. It is useful to estimate the amount of resource
17477 required to sustain high loads, and to detect when the frontend's "maxconn"
17478 has been reached. Most often when this value increases by huge jumps, it is
17479 because there is congestion on the backend servers, but sometimes it can be
17480 caused by a denial of service attack.
17481
17482 - "beconn" is the total number of concurrent connections handled by the
17483 backend when the session was logged. It includes the total number of
17484 concurrent connections active on servers as well as the number of
17485 connections pending in queues. It is useful to estimate the amount of
17486 additional servers needed to support high loads for a given application.
17487 Most often when this value increases by huge jumps, it is because there is
17488 congestion on the backend servers, but sometimes it can be caused by a
17489 denial of service attack.
17490
17491 - "srv_conn" is the total number of concurrent connections still active on
17492 the server when the session was logged. It can never exceed the server's
17493 configured "maxconn" parameter. If this value is very often close or equal
17494 to the server's "maxconn", it means that traffic regulation is involved a
17495 lot, meaning that either the server's maxconn value is too low, or that
17496 there aren't enough servers to process the load with an optimal response
17497 time. When only one of the server's "srv_conn" is high, it usually means
17498 that this server has some trouble causing the requests to take longer to be
17499 processed than on other servers.
17500
17501 - "retries" is the number of connection retries experienced by this session
17502 when trying to connect to the server. It must normally be zero, unless a
17503 server is being stopped at the same moment the connection was attempted.
17504 Frequent retries generally indicate either a network problem between
17505 haproxy and the server, or a misconfigured system backlog on the server
17506 preventing new connections from being queued. This field may optionally be
17507 prefixed with a '+' sign, indicating that the session has experienced a
17508 redispatch after the maximal retry count has been reached on the initial
17509 server. In this case, the server name appearing in the log is the one the
17510 connection was redispatched to, and not the first one, though both may
17511 sometimes be the same in case of hashing for instance. So as a general rule
17512 of thumb, when a '+' is present in front of the retry count, this count
17513 should not be attributed to the logged server.
17514
17515 - "srv_queue" is the total number of requests which were processed before
17516 this one in the server queue. It is zero when the request has not gone
17517 through the server queue. It makes it possible to estimate the approximate
17518 server's response time by dividing the time spent in queue by the number of
17519 requests in the queue. It is worth noting that if a session experiences a
17520 redispatch and passes through two server queues, their positions will be
Davor Ocelice9ed2812017-12-25 17:49:28 +010017521 cumulative. A request should not pass through both the server queue and the
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017522 backend queue unless a redispatch occurs.
17523
17524 - "backend_queue" is the total number of requests which were processed before
17525 this one in the backend's global queue. It is zero when the request has not
17526 gone through the global queue. It makes it possible to estimate the average
17527 queue length, which easily translates into a number of missing servers when
17528 divided by a server's "maxconn" parameter. It is worth noting that if a
17529 session experiences a redispatch, it may pass twice in the backend's queue,
Davor Ocelice9ed2812017-12-25 17:49:28 +010017530 and then both positions will be cumulative. A request should not pass
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017531 through both the server queue and the backend queue unless a redispatch
17532 occurs.
17533
17534 - "captured_request_headers" is a list of headers captured in the request due
17535 to the presence of the "capture request header" statement in the frontend.
17536 Multiple headers can be captured, they will be delimited by a vertical bar
17537 ('|'). When no capture is enabled, the braces do not appear, causing a
17538 shift of remaining fields. It is important to note that this field may
17539 contain spaces, and that using it requires a smarter log parser than when
17540 it's not used. Please consult the section "Capturing HTTP headers and
17541 cookies" below for more details.
17542
17543 - "captured_response_headers" is a list of headers captured in the response
17544 due to the presence of the "capture response header" statement in the
17545 frontend. Multiple headers can be captured, they will be delimited by a
17546 vertical bar ('|'). When no capture is enabled, the braces do not appear,
17547 causing a shift of remaining fields. It is important to note that this
17548 field may contain spaces, and that using it requires a smarter log parser
17549 than when it's not used. Please consult the section "Capturing HTTP headers
17550 and cookies" below for more details.
17551
17552 - "http_request" is the complete HTTP request line, including the method,
17553 request and HTTP version string. Non-printable characters are encoded (see
17554 below the section "Non-printable characters"). This is always the last
17555 field, and it is always delimited by quotes and is the only one which can
17556 contain quotes. If new fields are added to the log format, they will be
17557 added before this field. This field might be truncated if the request is
17558 huge and does not fit in the standard syslog buffer (1024 characters). This
17559 is the reason why this field must always remain the last one.
17560
17561
Cyril Bontédc4d9032012-04-08 21:57:39 +0200175628.2.4. Custom log format
17563------------------------
William Lallemand48940402012-01-30 16:47:22 +010017564
Willy Tarreau2beef582012-12-20 17:22:52 +010017565The directive log-format allows you to customize the logs in http mode and tcp
William Lallemandbddd4fd2012-02-27 11:23:10 +010017566mode. It takes a string as argument.
William Lallemand48940402012-01-30 16:47:22 +010017567
Davor Ocelice9ed2812017-12-25 17:49:28 +010017568HAProxy understands some log format variables. % precedes log format variables.
William Lallemand48940402012-01-30 16:47:22 +010017569Variables can take arguments using braces ('{}'), and multiple arguments are
17570separated by commas within the braces. Flags may be added or removed by
17571prefixing them with a '+' or '-' sign.
17572
17573Special variable "%o" may be used to propagate its flags to all other
17574variables on the same format string. This is particularly handy with quoted
Dragan Dosen835b9212016-02-12 13:23:03 +010017575("Q") and escaped ("E") string formats.
William Lallemand48940402012-01-30 16:47:22 +010017576
Willy Tarreauc8368452012-12-21 00:09:23 +010017577If a variable is named between square brackets ('[' .. ']') then it is used
Willy Tarreaube722a22014-06-13 16:31:59 +020017578as a sample expression rule (see section 7.3). This it useful to add some
Willy Tarreauc8368452012-12-21 00:09:23 +010017579less common information such as the client's SSL certificate's DN, or to log
17580the key that would be used to store an entry into a stick table.
17581
William Lallemand48940402012-01-30 16:47:22 +010017582Note: spaces must be escaped. A space character is considered as a separator.
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017583In order to emit a verbatim '%', it must be preceded by another '%' resulting
Willy Tarreau06d97f92013-12-02 17:45:48 +010017584in '%%'. HAProxy will automatically merge consecutive separators.
William Lallemand48940402012-01-30 16:47:22 +010017585
Dragan Dosen835b9212016-02-12 13:23:03 +010017586Note: when using the RFC5424 syslog message format, the characters '"',
17587'\' and ']' inside PARAM-VALUE should be escaped with '\' as prefix (see
17588https://tools.ietf.org/html/rfc5424#section-6.3.3 for more details). In
17589such cases, the use of the flag "E" should be considered.
17590
William Lallemand48940402012-01-30 16:47:22 +010017591Flags are :
17592 * Q: quote a string
Jamie Gloudonaaa21002012-08-25 00:18:33 -040017593 * X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
Dragan Dosen835b9212016-02-12 13:23:03 +010017594 * E: escape characters '"', '\' and ']' in a string with '\' as prefix
17595 (intended purpose is for the RFC5424 structured-data log formats)
William Lallemand48940402012-01-30 16:47:22 +010017596
17597 Example:
17598
17599 log-format %T\ %t\ Some\ Text
17600 log-format %{+Q}o\ %t\ %s\ %{-Q}r
17601
Dragan Dosen835b9212016-02-12 13:23:03 +010017602 log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]
17603
William Lallemand48940402012-01-30 16:47:22 +010017604At the moment, the default HTTP format is defined this way :
17605
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017606 log-format "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC \
17607 %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"
William Lallemand48940402012-01-30 16:47:22 +010017608
William Lallemandbddd4fd2012-02-27 11:23:10 +010017609the default CLF format is defined this way :
William Lallemand48940402012-01-30 16:47:22 +010017610
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017611 log-format "%{+Q}o %{-Q}ci - - [%trg] %r %ST %B \"\" \"\" %cp \
17612 %ms %ft %b %s %TR %Tw %Tc %Tr %Ta %tsc %ac %fc \
17613 %bc %sc %rc %sq %bq %CC %CS %hrl %hsl"
William Lallemand48940402012-01-30 16:47:22 +010017614
William Lallemandbddd4fd2012-02-27 11:23:10 +010017615and the default TCP format is defined this way :
17616
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017617 log-format "%ci:%cp [%t] %ft %b/%s %Tw/%Tc/%Tt %B %ts \
17618 %ac/%fc/%bc/%sc/%rc %sq/%bq"
William Lallemandbddd4fd2012-02-27 11:23:10 +010017619
William Lallemand48940402012-01-30 16:47:22 +010017620Please refer to the table below for currently defined variables :
17621
William Lallemandbddd4fd2012-02-27 11:23:10 +010017622 +---+------+-----------------------------------------------+-------------+
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017623 | R | var | field name (8.2.2 and 8.2.3 for description) | type |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017624 +---+------+-----------------------------------------------+-------------+
17625 | | %o | special variable, apply flags on all next var | |
17626 +---+------+-----------------------------------------------+-------------+
Willy Tarreau2beef582012-12-20 17:22:52 +010017627 | | %B | bytes_read (from server to client) | numeric |
17628 | H | %CC | captured_request_cookie | string |
17629 | H | %CS | captured_response_cookie | string |
William Lallemand5f232402012-04-05 18:02:55 +020017630 | | %H | hostname | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000017631 | H | %HM | HTTP method (ex: POST) | string |
17632 | H | %HP | HTTP request URI without query string (path) | string |
Andrew Hayworthe63ac872015-07-31 16:14:16 +000017633 | H | %HQ | HTTP request URI query string (ex: ?bar=baz) | string |
Andrew Hayworth0ebc55f2015-04-27 21:37:03 +000017634 | H | %HU | HTTP request URI (ex: /foo?bar=baz) | string |
17635 | H | %HV | HTTP version (ex: HTTP/1.0) | string |
William Lallemanda73203e2012-03-12 12:48:57 +010017636 | | %ID | unique-id | string |
Willy Tarreau4bf99632014-06-13 12:21:40 +020017637 | | %ST | status_code | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020017638 | | %T | gmt_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017639 | | %Ta | Active time of the request (from TR to end) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017640 | | %Tc | Tc | numeric |
Willy Tarreau27b639d2016-05-17 17:55:27 +020017641 | | %Td | Td = Tt - (Tq + Tw + Tc + Tr) | numeric |
Yuxans Yao4e25b012012-10-19 10:36:09 +080017642 | | %Tl | local_date_time | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017643 | | %Th | connection handshake time (SSL, PROXY proto) | numeric |
17644 | H | %Ti | idle time before the HTTP request | numeric |
17645 | H | %Tq | Th + Ti + TR | numeric |
17646 | H | %TR | time to receive the full request from 1st byte| numeric |
17647 | H | %Tr | Tr (response time) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020017648 | | %Ts | timestamp | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017649 | | %Tt | Tt | numeric |
17650 | | %Tw | Tw | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010017651 | | %U | bytes_uploaded (from client to server) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017652 | | %ac | actconn | numeric |
17653 | | %b | backend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017654 | | %bc | beconn (backend concurrent connections) | numeric |
17655 | | %bi | backend_source_ip (connecting address) | IP |
17656 | | %bp | backend_source_port (connecting address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017657 | | %bq | backend_queue | numeric |
Willy Tarreau2beef582012-12-20 17:22:52 +010017658 | | %ci | client_ip (accepted address) | IP |
17659 | | %cp | client_port (accepted address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017660 | | %f | frontend_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017661 | | %fc | feconn (frontend concurrent connections) | numeric |
17662 | | %fi | frontend_ip (accepting address) | IP |
17663 | | %fp | frontend_port (accepting address) | numeric |
Willy Tarreau773d65f2012-10-12 14:56:11 +020017664 | | %ft | frontend_name_transport ('~' suffix for SSL) | string |
Willy Tarreau7346acb2014-08-28 15:03:15 +020017665 | | %lc | frontend_log_counter | numeric |
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020017666 | | %hr | captured_request_headers default style | string |
17667 | | %hrl | captured_request_headers CLF style | string list |
17668 | | %hs | captured_response_headers default style | string |
17669 | | %hsl | captured_response_headers CLF style | string list |
Willy Tarreau812c88e2015-08-09 10:56:35 +020017670 | | %ms | accept date milliseconds (left-padded with 0) | numeric |
William Lallemand5f232402012-04-05 18:02:55 +020017671 | | %pid | PID | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017672 | H | %r | http_request | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017673 | | %rc | retries | numeric |
Willy Tarreau1f0da242014-01-25 11:01:50 +010017674 | | %rt | request_counter (HTTP req or TCP session) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017675 | | %s | server_name | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017676 | | %sc | srv_conn (server concurrent connections) | numeric |
17677 | | %si | server_IP (target address) | IP |
17678 | | %sp | server_port (target address) | numeric |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017679 | | %sq | srv_queue | numeric |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017680 | S | %sslc| ssl_ciphers (ex: AES-SHA) | string |
17681 | S | %sslv| ssl_version (ex: TLSv1) | string |
Willy Tarreau2beef582012-12-20 17:22:52 +010017682 | | %t | date_time (with millisecond resolution) | date |
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017683 | H | %tr | date_time of HTTP request | date |
17684 | H | %trg | gmt_date_time of start of HTTP request | date |
Jens Bissinger15c64ff2018-08-23 14:11:27 +020017685 | H | %trl | local_date_time of start of HTTP request | date |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017686 | | %ts | termination_state | string |
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017687 | H | %tsc | termination_state with cookie status | string |
William Lallemandbddd4fd2012-02-27 11:23:10 +010017688 +---+------+-----------------------------------------------+-------------+
William Lallemand48940402012-01-30 16:47:22 +010017689
Willy Tarreauffc3fcd2012-10-12 20:17:54 +020017690 R = Restrictions : H = mode http only ; S = SSL only
William Lallemand48940402012-01-30 16:47:22 +010017691
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010017692
176938.2.5. Error log format
17694-----------------------
17695
17696When an incoming connection fails due to an SSL handshake or an invalid PROXY
17697protocol header, haproxy will log the event using a shorter, fixed line format.
17698By default, logs are emitted at the LOG_INFO level, unless the option
17699"log-separate-errors" is set in the backend, in which case the LOG_ERR level
Davor Ocelice9ed2812017-12-25 17:49:28 +010017700will be used. Connections on which no data are exchanged (e.g. probes) are not
Willy Tarreau5f51e1a2012-12-03 18:40:10 +010017701logged if the "dontlognull" option is set.
17702
17703The format looks like this :
17704
17705 >>> Dec 3 18:27:14 localhost \
17706 haproxy[6103]: 127.0.0.1:56059 [03/Dec/2012:17:35:10.380] frt/f1: \
17707 Connection error during SSL handshake
17708
17709 Field Format Extract from the example above
17710 1 process_name '[' pid ']:' haproxy[6103]:
17711 2 client_ip ':' client_port 127.0.0.1:56059
17712 3 '[' accept_date ']' [03/Dec/2012:17:35:10.380]
17713 4 frontend_name "/" bind_name ":" frt/f1:
17714 5 message Connection error during SSL handshake
17715
17716These fields just provide minimal information to help debugging connection
17717failures.
17718
17719
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177208.3. Advanced logging options
17721-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017722
17723Some advanced logging options are often looked for but are not easy to find out
17724just by looking at the various options. Here is an entry point for the few
17725options which can enable better logging. Please refer to the keywords reference
17726for more information about their usage.
17727
17728
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177298.3.1. Disabling logging of external tests
17730------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017731
17732It is quite common to have some monitoring tools perform health checks on
17733haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
17734commercial load-balancer, and sometimes it will simply be a more complete
17735monitoring system such as Nagios. When the tests are very frequent, users often
17736ask how to disable logging for those checks. There are three possibilities :
17737
17738 - if connections come from everywhere and are just TCP probes, it is often
17739 desired to simply disable logging of connections without data exchange, by
17740 setting "option dontlognull" in the frontend. It also disables logging of
17741 port scans, which may or may not be desired.
17742
17743 - if the connection come from a known source network, use "monitor-net" to
17744 declare this network as monitoring only. Any host in this network will then
17745 only be able to perform health checks, and their requests will not be
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017746 logged. This is generally appropriate to designate a list of equipment
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017747 such as other load-balancers.
17748
17749 - if the tests are performed on a known URI, use "monitor-uri" to declare
17750 this URI as dedicated to monitoring. Any host sending this request will
17751 only get the result of a health-check, and the request will not be logged.
17752
17753
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177548.3.2. Logging before waiting for the session to terminate
17755----------------------------------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017756
17757The problem with logging at end of connection is that you have no clue about
17758what is happening during very long sessions, such as remote terminal sessions
17759or large file downloads. This problem can be worked around by specifying
Davor Ocelice9ed2812017-12-25 17:49:28 +010017760"option logasap" in the frontend. HAProxy will then log as soon as possible,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017761just before data transfer begins. This means that in case of TCP, it will still
17762log the connection status to the server, and in case of HTTP, it will log just
17763after processing the server headers. In this case, the number of bytes reported
17764is the number of header bytes sent to the client. In order to avoid confusion
17765with normal logs, the total time field and the number of bytes are prefixed
17766with a '+' sign which means that real numbers are certainly larger.
17767
17768
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177698.3.3. Raising log level upon errors
17770------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020017771
17772Sometimes it is more convenient to separate normal traffic from errors logs,
17773for instance in order to ease error monitoring from log files. When the option
17774"log-separate-errors" is used, connections which experience errors, timeouts,
17775retries, redispatches or HTTP status codes 5xx will see their syslog level
17776raised from "info" to "err". This will help a syslog daemon store the log in
17777a separate file. It is very important to keep the errors in the normal traffic
17778file too, so that log ordering is not altered. You should also be careful if
17779you already have configured your syslog daemon to store all logs higher than
17780"notice" in an "admin" file, because the "err" level is higher than "notice".
17781
17782
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177838.3.4. Disabling logging of successful connections
17784--------------------------------------------------
Willy Tarreauc9bd0cc2009-05-10 11:57:02 +020017785
17786Although this may sound strange at first, some large sites have to deal with
17787multiple thousands of logs per second and are experiencing difficulties keeping
17788them intact for a long time or detecting errors within them. If the option
17789"dontlog-normal" is set on the frontend, all normal connections will not be
17790logged. In this regard, a normal connection is defined as one without any
17791error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
17792and a response with a status 5xx is not considered normal and will be logged
17793too. Of course, doing is is really discouraged as it will remove most of the
17794useful information from the logs. Do this only if you have no other
17795alternative.
17796
17797
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200177988.4. Timing events
17799------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017800
17801Timers provide a great help in troubleshooting network problems. All values are
17802reported in milliseconds (ms). These timers should be used in conjunction with
17803the session termination flags. In TCP mode with "option tcplog" set on the
17804frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017805mode, 5 control points are reported under the form "TR/Tw/Tc/Tr/Ta". In
17806addition, three other measures are provided, "Th", "Ti", and "Tq".
17807
Guillaume de Lafondf27cddc2016-12-23 17:32:43 +010017808Timings events in HTTP mode:
17809
17810 first request 2nd request
17811 |<-------------------------------->|<-------------- ...
17812 t tr t tr ...
17813 ---|----|----|----|----|----|----|----|----|--
17814 : Th Ti TR Tw Tc Tr Td : Ti ...
17815 :<---- Tq ---->: :
17816 :<-------------- Tt -------------->:
17817 :<--------- Ta --------->:
17818
17819Timings events in TCP mode:
17820
17821 TCP session
17822 |<----------------->|
17823 t t
17824 ---|----|----|----|----|---
17825 | Th Tw Tc Td |
17826 |<------ Tt ------->|
17827
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017828 - Th: total time to accept tcp connection and execute handshakes for low level
Davor Ocelice9ed2812017-12-25 17:49:28 +010017829 protocols. Currently, these protocols are proxy-protocol and SSL. This may
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017830 only happen once during the whole connection's lifetime. A large time here
17831 may indicate that the client only pre-established the connection without
17832 speaking, that it is experiencing network issues preventing it from
Davor Ocelice9ed2812017-12-25 17:49:28 +010017833 completing a handshake in a reasonable time (e.g. MTU issues), or that an
Willy Tarreau590a0512018-09-05 11:56:48 +020017834 SSL handshake was very expensive to compute. Please note that this time is
17835 reported only before the first request, so it is safe to average it over
17836 all request to calculate the amortized value. The second and subsequent
17837 request will always report zero here.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017838
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017839 - Ti: is the idle time before the HTTP request (HTTP mode only). This timer
17840 counts between the end of the handshakes and the first byte of the HTTP
17841 request. When dealing with a second request in keep-alive mode, it starts
Willy Tarreau590a0512018-09-05 11:56:48 +020017842 to count after the end of the transmission the previous response. When a
17843 multiplexed protocol such as HTTP/2 is used, it starts to count immediately
17844 after the previous request. Some browsers pre-establish connections to a
17845 server in order to reduce the latency of a future request, and keep them
17846 pending until they need it. This delay will be reported as the idle time. A
17847 value of -1 indicates that nothing was received on the connection.
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017848
17849 - TR: total time to get the client request (HTTP mode only). It's the time
17850 elapsed between the first bytes received and the moment the proxy received
17851 the empty line marking the end of the HTTP headers. The value "-1"
17852 indicates that the end of headers has never been seen. This happens when
17853 the client closes prematurely or times out. This time is usually very short
17854 since most requests fit in a single packet. A large time may indicate a
17855 request typed by hand during a test.
17856
17857 - Tq: total time to get the client request from the accept date or since the
17858 emission of the last byte of the previous response (HTTP mode only). It's
Davor Ocelice9ed2812017-12-25 17:49:28 +010017859 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 +020017860 returns -1 as well. This timer used to be very useful before the arrival of
17861 HTTP keep-alive and browsers' pre-connect feature. It's recommended to drop
17862 it in favor of TR nowadays, as the idle time adds a lot of noise to the
17863 reports.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017864
17865 - Tw: total time spent in the queues waiting for a connection slot. It
17866 accounts for backend queue as well as the server queues, and depends on the
17867 queue size, and the time needed for the server to complete previous
17868 requests. The value "-1" means that the request was killed before reaching
17869 the queue, which is generally what happens with invalid or denied requests.
17870
17871 - Tc: total time to establish the TCP connection to the server. It's the time
17872 elapsed between the moment the proxy sent the connection request, and the
17873 moment it was acknowledged by the server, or between the TCP SYN packet and
17874 the matching SYN/ACK packet in return. The value "-1" means that the
17875 connection never established.
17876
17877 - Tr: server response time (HTTP mode only). It's the time elapsed between
17878 the moment the TCP connection was established to the server and the moment
17879 the server sent its complete response headers. It purely shows its request
17880 processing time, without the network overhead due to the data transmission.
17881 It is worth noting that when the client has data to send to the server, for
17882 instance during a POST request, the time already runs, and this can distort
17883 apparent response time. For this reason, it's generally wise not to trust
17884 too much this field for POST requests initiated from clients behind an
17885 untrusted network. A value of "-1" here means that the last the response
17886 header (empty line) was never seen, most likely because the server timeout
17887 stroke before the server managed to process the request.
17888
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017889 - Ta: total active time for the HTTP request, between the moment the proxy
17890 received the first byte of the request header and the emission of the last
17891 byte of the response body. The exception is when the "logasap" option is
17892 specified. In this case, it only equals (TR+Tw+Tc+Tr), and is prefixed with
17893 a '+' sign. From this field, we can deduce "Td", the data transmission time,
17894 by subtracting other timers when valid :
17895
17896 Td = Ta - (TR + Tw + Tc + Tr)
17897
17898 Timers with "-1" values have to be excluded from this equation. Note that
17899 "Ta" can never be negative.
17900
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017901 - Tt: total session duration time, between the moment the proxy accepted it
17902 and the moment both ends were closed. The exception is when the "logasap"
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017903 option is specified. In this case, it only equals (Th+Ti+TR+Tw+Tc+Tr), and
17904 is prefixed with a '+' sign. From this field, we can deduce "Td", the data
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017905 transmission time, by subtracting other timers when valid :
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017906
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017907 Td = Tt - (Th + Ti + TR + Tw + Tc + Tr)
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017908
17909 Timers with "-1" values have to be excluded from this equation. In TCP
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017910 mode, "Ti", "Tq" and "Tr" have to be excluded too. Note that "Tt" can never
17911 be negative and that for HTTP, Tt is simply equal to (Th+Ti+Ta).
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017912
17913These timers provide precious indications on trouble causes. Since the TCP
17914protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
17915that timers close to multiples of 3s are nearly always related to lost packets
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017916due to network problems (wires, negotiation, congestion). Moreover, if "Ta" or
17917"Tt" is close to a timeout value specified in the configuration, it often means
17918that a session has been aborted on timeout.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017919
17920Most common cases :
17921
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017922 - If "Th" or "Ti" are close to 3000, a packet has probably been lost between
17923 the client and the proxy. This is very rare on local networks but might
17924 happen when clients are on far remote networks and send large requests. It
17925 may happen that values larger than usual appear here without any network
17926 cause. Sometimes, during an attack or just after a resource starvation has
17927 ended, haproxy may accept thousands of connections in a few milliseconds.
17928 The time spent accepting these connections will inevitably slightly delay
17929 processing of other connections, and it can happen that request times in the
17930 order of a few tens of milliseconds are measured after a few thousands of
17931 new connections have been accepted at once. Using one of the keep-alive
17932 modes may display larger idle times since "Ti" measures the time spent
Patrick Mezard105faca2010-06-12 17:02:46 +020017933 waiting for additional requests.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017934
17935 - If "Tc" is close to 3000, a packet has probably been lost between the
17936 server and the proxy during the server connection phase. This value should
17937 always be very low, such as 1 ms on local networks and less than a few tens
17938 of ms on remote networks.
17939
Willy Tarreau55165fe2009-05-10 12:02:55 +020017940 - If "Tr" is nearly always lower than 3000 except some rare values which seem
17941 to be the average majored by 3000, there are probably some packets lost
17942 between the proxy and the server.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017943
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017944 - If "Ta" is large even for small byte counts, it generally is because
17945 neither the client nor the server decides to close the connection while
17946 haproxy is running in tunnel mode and both have agreed on a keep-alive
17947 connection mode. In order to solve this issue, it will be needed to specify
17948 one of the HTTP options to manipulate keep-alive or close options on either
17949 the frontend or the backend. Having the smallest possible 'Ta' or 'Tt' is
17950 important when connection regulation is used with the "maxconn" option on
17951 the servers, since no new connection will be sent to the server until
17952 another one is released.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017953
17954Other noticeable HTTP log cases ('xx' means any value to be ignored) :
17955
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017956 TR/Tw/Tc/Tr/+Ta The "option logasap" is present on the frontend and the log
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017957 was emitted before the data phase. All the timers are valid
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017958 except "Ta" which is shorter than reality.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017959
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017960 -1/xx/xx/xx/Ta The client was not able to send a complete request in time
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017961 or it aborted too early. Check the session termination flags
17962 then "timeout http-request" and "timeout client" settings.
17963
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017964 TR/-1/xx/xx/Ta It was not possible to process the request, maybe because
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017965 servers were out of order, because the request was invalid
17966 or forbidden by ACL rules. Check the session termination
17967 flags.
17968
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017969 TR/Tw/-1/xx/Ta The connection could not establish on the server. Either it
17970 actively refused it or it timed out after Ta-(TR+Tw) ms.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017971 Check the session termination flags, then check the
17972 "timeout connect" setting. Note that the tarpit action might
17973 return similar-looking patterns, with "Tw" equal to the time
17974 the client connection was maintained open.
17975
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017976 TR/Tw/Tc/-1/Ta The server has accepted the connection but did not return
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030017977 a complete response in time, or it closed its connection
Thierry FOURNIER / OZON.IO4cac3592016-07-28 17:19:45 +020017978 unexpectedly after Ta-(TR+Tw+Tc) ms. Check the session
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017979 termination flags, then check the "timeout server" setting.
17980
17981
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200179828.5. Session state at disconnection
17983-----------------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010017984
17985TCP and HTTP logs provide a session termination indicator in the
17986"termination_state" field, just before the number of active connections. It is
179872-characters long in TCP mode, and is extended to 4 characters in HTTP mode,
17988each of which has a special meaning :
17989
17990 - On the first character, a code reporting the first event which caused the
17991 session to terminate :
17992
17993 C : the TCP session was unexpectedly aborted by the client.
17994
17995 S : the TCP session was unexpectedly aborted by the server, or the
17996 server explicitly refused it.
17997
17998 P : the session was prematurely aborted by the proxy, because of a
17999 connection limit enforcement, because a DENY filter was matched,
18000 because of a security check which detected and blocked a dangerous
18001 error in server response which might have caused information leak
Davor Ocelice9ed2812017-12-25 17:49:28 +010018002 (e.g. cacheable cookie).
Willy Tarreau570f2212013-06-10 16:42:09 +020018003
18004 L : the session was locally processed by haproxy and was not passed to
18005 a server. This is what happens for stats and redirects.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018006
18007 R : a resource on the proxy has been exhausted (memory, sockets, source
18008 ports, ...). Usually, this appears during the connection phase, and
18009 system logs should contain a copy of the precise error. If this
18010 happens, it must be considered as a very serious anomaly which
18011 should be fixed as soon as possible by any means.
18012
18013 I : an internal error was identified by the proxy during a self-check.
18014 This should NEVER happen, and you are encouraged to report any log
18015 containing this, because this would almost certainly be a bug. It
18016 would be wise to preventively restart the process after such an
18017 event too, in case it would be caused by memory corruption.
18018
Simon Horman752dc4a2011-06-21 14:34:59 +090018019 D : the session was killed by haproxy because the server was detected
18020 as down and was configured to kill all connections when going down.
18021
Justin Karnegeseb2c24a2012-05-24 15:28:52 -070018022 U : the session was killed by haproxy on this backup server because an
18023 active server was detected as up and was configured to kill all
18024 backup connections when going up.
18025
Willy Tarreaua2a64e92011-09-07 23:01:56 +020018026 K : the session was actively killed by an admin operating on haproxy.
18027
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018028 c : the client-side timeout expired while waiting for the client to
18029 send or receive data.
18030
18031 s : the server-side timeout expired while waiting for the server to
18032 send or receive data.
18033
18034 - : normal session completion, both the client and the server closed
18035 with nothing left in the buffers.
18036
18037 - on the second character, the TCP or HTTP session state when it was closed :
18038
Willy Tarreauf7b30a92010-12-06 22:59:17 +010018039 R : the proxy was waiting for a complete, valid REQUEST from the client
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018040 (HTTP mode only). Nothing was sent to any server.
18041
18042 Q : the proxy was waiting in the QUEUE for a connection slot. This can
18043 only happen when servers have a 'maxconn' parameter set. It can
18044 also happen in the global queue after a redispatch consecutive to
18045 a failed attempt to connect to a dying server. If no redispatch is
18046 reported, then no connection attempt was made to any server.
18047
18048 C : the proxy was waiting for the CONNECTION to establish on the
18049 server. The server might at most have noticed a connection attempt.
18050
18051 H : the proxy was waiting for complete, valid response HEADERS from the
18052 server (HTTP only).
18053
18054 D : the session was in the DATA phase.
18055
18056 L : the proxy was still transmitting LAST data to the client while the
18057 server had already finished. This one is very rare as it can only
18058 happen when the client dies while receiving the last packets.
18059
18060 T : the request was tarpitted. It has been held open with the client
18061 during the whole "timeout tarpit" duration or until the client
18062 closed, both of which will be reported in the "Tw" timer.
18063
18064 - : normal session completion after end of data transfer.
18065
18066 - the third character tells whether the persistence cookie was provided by
18067 the client (only in HTTP mode) :
18068
18069 N : the client provided NO cookie. This is usually the case for new
18070 visitors, so counting the number of occurrences of this flag in the
18071 logs generally indicate a valid trend for the site frequentation.
18072
18073 I : the client provided an INVALID cookie matching no known server.
18074 This might be caused by a recent configuration change, mixed
Cyril Bontéa8e7bbc2010-04-25 22:29:29 +020018075 cookies between HTTP/HTTPS sites, persistence conditionally
18076 ignored, or an attack.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018077
18078 D : the client provided a cookie designating a server which was DOWN,
18079 so either "option persist" was used and the client was sent to
18080 this server, or it was not set and the client was redispatched to
18081 another server.
18082
Willy Tarreau996a92c2010-10-13 19:30:47 +020018083 V : the client provided a VALID cookie, and was sent to the associated
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018084 server.
18085
Willy Tarreau996a92c2010-10-13 19:30:47 +020018086 E : the client provided a valid cookie, but with a last date which was
18087 older than what is allowed by the "maxidle" cookie parameter, so
18088 the cookie is consider EXPIRED and is ignored. The request will be
18089 redispatched just as if there was no cookie.
18090
18091 O : the client provided a valid cookie, but with a first date which was
18092 older than what is allowed by the "maxlife" cookie parameter, so
18093 the cookie is consider too OLD and is ignored. The request will be
18094 redispatched just as if there was no cookie.
18095
Willy Tarreauc89ccb62012-04-05 21:18:22 +020018096 U : a cookie was present but was not used to select the server because
18097 some other server selection mechanism was used instead (typically a
18098 "use-server" rule).
18099
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018100 - : does not apply (no cookie set in configuration).
18101
18102 - the last character reports what operations were performed on the persistence
18103 cookie returned by the server (only in HTTP mode) :
18104
18105 N : NO cookie was provided by the server, and none was inserted either.
18106
18107 I : no cookie was provided by the server, and the proxy INSERTED one.
18108 Note that in "cookie insert" mode, if the server provides a cookie,
18109 it will still be overwritten and reported as "I" here.
18110
Willy Tarreau996a92c2010-10-13 19:30:47 +020018111 U : the proxy UPDATED the last date in the cookie that was presented by
18112 the client. This can only happen in insert mode with "maxidle". It
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030018113 happens every time there is activity at a different date than the
Willy Tarreau996a92c2010-10-13 19:30:47 +020018114 date indicated in the cookie. If any other change happens, such as
18115 a redispatch, then the cookie will be marked as inserted instead.
18116
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018117 P : a cookie was PROVIDED by the server and transmitted as-is.
18118
18119 R : the cookie provided by the server was REWRITTEN by the proxy, which
18120 happens in "cookie rewrite" or "cookie prefix" modes.
18121
18122 D : the cookie provided by the server was DELETED by the proxy.
18123
18124 - : does not apply (no cookie set in configuration).
18125
Willy Tarreau996a92c2010-10-13 19:30:47 +020018126The combination of the two first flags gives a lot of information about what
18127was happening when the session terminated, and why it did terminate. It can be
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018128helpful to detect server saturation, network troubles, local system resource
18129starvation, attacks, etc...
18130
18131The most common termination flags combinations are indicated below. They are
18132alphabetically sorted, with the lowercase set just after the upper case for
18133easier finding and understanding.
18134
18135 Flags Reason
18136
18137 -- Normal termination.
18138
18139 CC The client aborted before the connection could be established to the
18140 server. This can happen when haproxy tries to connect to a recently
18141 dead (or unchecked) server, and the client aborts while haproxy is
18142 waiting for the server to respond or for "timeout connect" to expire.
18143
18144 CD The client unexpectedly aborted during data transfer. This can be
18145 caused by a browser crash, by an intermediate equipment between the
18146 client and haproxy which decided to actively break the connection,
18147 by network routing issues between the client and haproxy, or by a
18148 keep-alive session between the server and the client terminated first
18149 by the client.
Willy Tarreaud72758d2010-01-12 10:42:19 +010018150
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018151 cD The client did not send nor acknowledge any data for as long as the
18152 "timeout client" delay. This is often caused by network failures on
Cyril Bontédc4d9032012-04-08 21:57:39 +020018153 the client side, or the client simply leaving the net uncleanly.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018154
18155 CH The client aborted while waiting for the server to start responding.
18156 It might be the server taking too long to respond or the client
18157 clicking the 'Stop' button too fast.
18158
18159 cH The "timeout client" stroke while waiting for client data during a
18160 POST request. This is sometimes caused by too large TCP MSS values
18161 for PPPoE networks which cannot transport full-sized packets. It can
18162 also happen when client timeout is smaller than server timeout and
18163 the server takes too long to respond.
18164
18165 CQ The client aborted while its session was queued, waiting for a server
18166 with enough empty slots to accept it. It might be that either all the
18167 servers were saturated or that the assigned server was taking too
18168 long a time to respond.
18169
18170 CR The client aborted before sending a full HTTP request. Most likely
18171 the request was typed by hand using a telnet client, and aborted
18172 too early. The HTTP status code is likely a 400 here. Sometimes this
18173 might also be caused by an IDS killing the connection between haproxy
Willy Tarreau0f228a02015-05-01 15:37:53 +020018174 and the client. "option http-ignore-probes" can be used to ignore
18175 connections without any data transfer.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018176
18177 cR The "timeout http-request" stroke before the client sent a full HTTP
18178 request. This is sometimes caused by too large TCP MSS values on the
18179 client side for PPPoE networks which cannot transport full-sized
18180 packets, or by clients sending requests by hand and not typing fast
18181 enough, or forgetting to enter the empty line at the end of the
Willy Tarreau2705a612014-05-23 17:38:34 +020018182 request. The HTTP status code is likely a 408 here. Note: recently,
Willy Tarreau0f228a02015-05-01 15:37:53 +020018183 some browsers started to implement a "pre-connect" feature consisting
18184 in speculatively connecting to some recently visited web sites just
18185 in case the user would like to visit them. This results in many
18186 connections being established to web sites, which end up in 408
18187 Request Timeout if the timeout strikes first, or 400 Bad Request when
18188 the browser decides to close them first. These ones pollute the log
18189 and feed the error counters. Some versions of some browsers have even
18190 been reported to display the error code. It is possible to work
Davor Ocelice9ed2812017-12-25 17:49:28 +010018191 around the undesirable effects of this behavior by adding "option
Willy Tarreau0f228a02015-05-01 15:37:53 +020018192 http-ignore-probes" in the frontend, resulting in connections with
18193 zero data transfer to be totally ignored. This will definitely hide
18194 the errors of people experiencing connectivity issues though.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018195
18196 CT The client aborted while its session was tarpitted. It is important to
18197 check if this happens on valid requests, in order to be sure that no
Willy Tarreau55165fe2009-05-10 12:02:55 +020018198 wrong tarpit rules have been written. If a lot of them happen, it
18199 might make sense to lower the "timeout tarpit" value to something
18200 closer to the average reported "Tw" timer, in order not to consume
18201 resources for just a few attackers.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018202
Willy Tarreau570f2212013-06-10 16:42:09 +020018203 LR The request was intercepted and locally handled by haproxy. Generally
18204 it means that this was a redirect or a stats request.
18205
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010018206 SC The server or an equipment between it and haproxy explicitly refused
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018207 the TCP connection (the proxy received a TCP RST or an ICMP message
18208 in return). Under some circumstances, it can also be the network
Davor Ocelice9ed2812017-12-25 17:49:28 +010018209 stack telling the proxy that the server is unreachable (e.g. no route,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018210 or no ARP response on local network). When this happens in HTTP mode,
18211 the status code is likely a 502 or 503 here.
18212
18213 sC The "timeout connect" stroke before a connection to the server could
18214 complete. When this happens in HTTP mode, the status code is likely a
18215 503 or 504 here.
18216
18217 SD The connection to the server died with an error during the data
18218 transfer. This usually means that haproxy has received an RST from
18219 the server or an ICMP message from an intermediate equipment while
18220 exchanging data with the server. This can be caused by a server crash
18221 or by a network issue on an intermediate equipment.
18222
18223 sD The server did not send nor acknowledge any data for as long as the
18224 "timeout server" setting during the data phase. This is often caused
Davor Ocelice9ed2812017-12-25 17:49:28 +010018225 by too short timeouts on L4 equipment before the server (firewalls,
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018226 load-balancers, ...), as well as keep-alive sessions maintained
18227 between the client and the server expiring first on haproxy.
18228
18229 SH The server aborted before sending its full HTTP response headers, or
18230 it crashed while processing the request. Since a server aborting at
18231 this moment is very rare, it would be wise to inspect its logs to
18232 control whether it crashed and why. The logged request may indicate a
18233 small set of faulty requests, demonstrating bugs in the application.
18234 Sometimes this might also be caused by an IDS killing the connection
18235 between haproxy and the server.
18236
18237 sH The "timeout server" stroke before the server could return its
18238 response headers. This is the most common anomaly, indicating too
18239 long transactions, probably caused by server or database saturation.
18240 The immediate workaround consists in increasing the "timeout server"
18241 setting, but it is important to keep in mind that the user experience
18242 will suffer from these long response times. The only long term
18243 solution is to fix the application.
18244
18245 sQ The session spent too much time in queue and has been expired. See
18246 the "timeout queue" and "timeout connect" settings to find out how to
18247 fix this if it happens too often. If it often happens massively in
18248 short periods, it may indicate general problems on the affected
18249 servers due to I/O or database congestion, or saturation caused by
18250 external attacks.
18251
18252 PC The proxy refused to establish a connection to the server because the
18253 process' socket limit has been reached while attempting to connect.
Cyril Bontédc4d9032012-04-08 21:57:39 +020018254 The global "maxconn" parameter may be increased in the configuration
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018255 so that it does not happen anymore. This status is very rare and
18256 might happen when the global "ulimit-n" parameter is forced by hand.
18257
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010018258 PD The proxy blocked an incorrectly formatted chunked encoded message in
18259 a request or a response, after the server has emitted its headers. In
18260 most cases, this will indicate an invalid message from the server to
Davor Ocelice9ed2812017-12-25 17:49:28 +010018261 the client. HAProxy supports chunk sizes of up to 2GB - 1 (2147483647
Willy Tarreauf3a3e132013-08-31 08:16:26 +020018262 bytes). Any larger size will be considered as an error.
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010018263
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018264 PH The proxy blocked the server's response, because it was invalid,
18265 incomplete, dangerous (cache control), or matched a security filter.
18266 In any case, an HTTP 502 error is sent to the client. One possible
18267 cause for this error is an invalid syntax in an HTTP header name
Willy Tarreaued2fd2d2010-12-29 11:23:27 +010018268 containing unauthorized characters. It is also possible but quite
18269 rare, that the proxy blocked a chunked-encoding request from the
18270 client due to an invalid syntax, before the server responded. In this
18271 case, an HTTP 400 error is sent to the client and reported in the
18272 logs.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018273
18274 PR The proxy blocked the client's HTTP request, either because of an
18275 invalid HTTP syntax, in which case it returned an HTTP 400 error to
18276 the client, or because a deny filter matched, in which case it
18277 returned an HTTP 403 error.
18278
18279 PT The proxy blocked the client's request and has tarpitted its
18280 connection before returning it a 500 server error. Nothing was sent
18281 to the server. The connection was maintained open for as long as
18282 reported by the "Tw" timer field.
18283
18284 RC A local resource has been exhausted (memory, sockets, source ports)
18285 preventing the connection to the server from establishing. The error
18286 logs will tell precisely what was missing. This is very rare and can
18287 only be solved by proper system tuning.
18288
Willy Tarreau996a92c2010-10-13 19:30:47 +020018289The combination of the two last flags gives a lot of information about how
18290persistence was handled by the client, the server and by haproxy. This is very
18291important to troubleshoot disconnections, when users complain they have to
18292re-authenticate. The commonly encountered flags are :
18293
18294 -- Persistence cookie is not enabled.
18295
18296 NN No cookie was provided by the client, none was inserted in the
18297 response. For instance, this can be in insert mode with "postonly"
18298 set on a GET request.
18299
18300 II A cookie designating an invalid server was provided by the client,
18301 a valid one was inserted in the response. This typically happens when
Jamie Gloudonaaa21002012-08-25 00:18:33 -040018302 a "server" entry is removed from the configuration, since its cookie
Willy Tarreau996a92c2010-10-13 19:30:47 +020018303 value can be presented by a client when no other server knows it.
18304
18305 NI No cookie was provided by the client, one was inserted in the
18306 response. This typically happens for first requests from every user
18307 in "insert" mode, which makes it an easy way to count real users.
18308
18309 VN A cookie was provided by the client, none was inserted in the
18310 response. This happens for most responses for which the client has
18311 already got a cookie.
18312
18313 VU A cookie was provided by the client, with a last visit date which is
18314 not completely up-to-date, so an updated cookie was provided in
18315 response. This can also happen if there was no date at all, or if
18316 there was a date but the "maxidle" parameter was not set, so that the
18317 cookie can be switched to unlimited time.
18318
18319 EI A cookie was provided by the client, with a last visit date which is
18320 too old for the "maxidle" parameter, so the cookie was ignored and a
18321 new cookie was inserted in the response.
18322
18323 OI A cookie was provided by the client, with a first visit date which is
18324 too old for the "maxlife" parameter, so the cookie was ignored and a
18325 new cookie was inserted in the response.
18326
18327 DI The server designated by the cookie was down, a new server was
18328 selected and a new cookie was emitted in the response.
18329
18330 VI The server designated by the cookie was not marked dead but could not
18331 be reached. A redispatch happened and selected another one, which was
18332 then advertised in the response.
18333
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018334
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200183358.6. Non-printable characters
18336-----------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018337
18338In order not to cause trouble to log analysis tools or terminals during log
18339consulting, non-printable characters are not sent as-is into log files, but are
18340converted to the two-digits hexadecimal representation of their ASCII code,
18341prefixed by the character '#'. The only characters that can be logged without
18342being escaped are comprised between 32 and 126 (inclusive). Obviously, the
18343escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It
18344is the same for the character '"' which becomes "#22", as well as '{', '|' and
18345'}' when logging headers.
18346
18347Note that the space character (' ') is not encoded in headers, which can cause
18348issues for tools relying on space count to locate fields. A typical header
18349containing spaces is "User-Agent".
18350
18351Last, it has been observed that some syslog daemons such as syslog-ng escape
18352the quote ('"') with a backslash ('\'). The reverse operation can safely be
18353performed since no quote may appear anywhere else in the logs.
18354
18355
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200183568.7. Capturing HTTP cookies
18357---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018358
18359Cookie capture simplifies the tracking a complete user session. This can be
18360achieved using the "capture cookie" statement in the frontend. Please refer to
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018361section 4.2 for more details. Only one cookie can be captured, and the same
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018362cookie will simultaneously be checked in the request ("Cookie:" header) and in
18363the response ("Set-Cookie:" header). The respective values will be reported in
18364the HTTP logs at the "captured_request_cookie" and "captured_response_cookie"
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018365locations (see section 8.2.3 about HTTP log format). When either cookie is
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018366not seen, a dash ('-') replaces the value. This way, it's easy to detect when a
18367user switches to a new session for example, because the server will reassign it
18368a new cookie. It is also possible to detect if a server unexpectedly sets a
18369wrong cookie to a client, leading to session crossing.
18370
18371 Examples :
18372 # capture the first cookie whose name starts with "ASPSESSION"
18373 capture cookie ASPSESSION len 32
18374
18375 # capture the first cookie whose name is exactly "vgnvisitor"
18376 capture cookie vgnvisitor= len 32
18377
18378
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200183798.8. Capturing HTTP headers
18380---------------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018381
18382Header captures are useful to track unique request identifiers set by an upper
18383proxy, virtual host names, user-agents, POST content-length, referrers, etc. In
18384the response, one can search for information about the response length, how the
18385server asked the cache to behave, or an object location during a redirection.
18386
18387Header captures are performed using the "capture request header" and "capture
18388response header" statements in the frontend. Please consult their definition in
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018389section 4.2 for more details.
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018390
18391It is possible to include both request headers and response headers at the same
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010018392time. Non-existent headers are logged as empty strings, and if one header
18393appears more than once, only its last occurrence will be logged. Request headers
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018394are grouped within braces '{' and '}' in the same order as they were declared,
18395and delimited with a vertical bar '|' without any space. Response headers
18396follow the same representation, but are displayed after a space following the
18397request headers block. These blocks are displayed just before the HTTP request
18398in the logs.
18399
Willy Tarreaud9ed3d22014-06-13 12:23:06 +020018400As a special case, it is possible to specify an HTTP header capture in a TCP
18401frontend. The purpose is to enable logging of headers which will be parsed in
18402an HTTP backend if the request is then switched to this HTTP backend.
18403
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018404 Example :
18405 # This instance chains to the outgoing proxy
18406 listen proxy-out
18407 mode http
18408 option httplog
18409 option logasap
18410 log global
18411 server cache1 192.168.1.1:3128
18412
18413 # log the name of the virtual server
18414 capture request header Host len 20
18415
18416 # log the amount of data uploaded during a POST
18417 capture request header Content-Length len 10
18418
18419 # log the beginning of the referrer
18420 capture request header Referer len 20
18421
18422 # server name (useful for outgoing proxies only)
18423 capture response header Server len 20
18424
18425 # logging the content-length is useful with "option logasap"
18426 capture response header Content-Length len 10
18427
Davor Ocelice9ed2812017-12-25 17:49:28 +010018428 # log the expected cache behavior on the response
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018429 capture response header Cache-Control len 8
18430
18431 # the Via header will report the next proxy's name
18432 capture response header Via len 20
18433
18434 # log the URL location during a redirection
18435 capture response header Location len 20
18436
18437 >>> Aug 9 20:26:09 localhost \
18438 haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \
18439 proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \
18440 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \
18441 "GET http://fr.adserver.yahoo.com/"
18442
18443 >>> Aug 9 20:30:46 localhost \
18444 haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \
18445 proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \
18446 {w.ods.org||} {Formilux/0.1.8|3495|||} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010018447 "GET http://trafic.1wt.eu/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018448
18449 >>> Aug 9 20:30:46 localhost \
18450 haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \
18451 proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \
18452 {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \
18453 {Apache|230|||http://www.sytadin.} \
Willy Tarreaud72758d2010-01-12 10:42:19 +010018454 "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018455
18456
Willy Tarreauc57f0e22009-05-10 13:12:33 +0200184578.9. Examples of logs
18458---------------------
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018459
18460These are real-world examples of logs accompanied with an explanation. Some of
18461them have been made up by hand. The syslog part has been removed for better
18462reading. Their sole purpose is to explain how to decipher them.
18463
18464 >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \
18465 px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \
18466 "HEAD / HTTP/1.0"
18467
18468 => long request (6.5s) entered by hand through 'telnet'. The server replied
18469 in 147 ms, and the session ended normally ('----')
18470
18471 >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \
18472 px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \
18473 0/9 "HEAD / HTTP/1.0"
18474
18475 => Idem, but the request was queued in the global queue behind 9 other
18476 requests, and waited there for 1230 ms.
18477
18478 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \
18479 px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \
18480 "GET /image.iso HTTP/1.0"
18481
18482 => request for a long data transfer. The "logasap" option was specified, so
Krzysztof Piotr Oledzkif8645332009-12-13 21:55:50 +010018483 the log was produced just before transferring data. The server replied in
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018484 14 ms, 243 bytes of headers were sent to the client, and total time from
18485 accept to first data byte is 30 ms.
18486
18487 >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \
18488 px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \
18489 "GET /cgi-bin/bug.cgi? HTTP/1.0"
18490
18491 => the proxy blocked a server response either because of an "rspdeny" or
18492 "rspideny" filter, or because the response was improperly formatted and
Willy Tarreau3c92c5f2011-08-28 09:45:47 +020018493 not HTTP-compliant, or because it blocked sensitive information which
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018494 risked being cached. In this case, the response is replaced with a "502
18495 bad gateway". The flags ("PH--") tell us that it was haproxy who decided
18496 to return the 502 and not the server.
18497
18498 >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \
Willy Tarreaud72758d2010-01-12 10:42:19 +010018499 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 +010018500
18501 => the client never completed its request and aborted itself ("C---") after
18502 8.5s, while the proxy was waiting for the request headers ("-R--").
18503 Nothing was sent to any server.
18504
18505 >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \
18506 px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 ""
18507
18508 => The client never completed its request, which was aborted by the
18509 time-out ("c---") after 50s, while the proxy was waiting for the request
Davor Ocelice9ed2812017-12-25 17:49:28 +010018510 headers ("-R--"). Nothing was sent to any server, but the proxy could
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018511 send a 408 return code to the client.
18512
18513 >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \
18514 px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0
18515
18516 => This log was produced with "option tcplog". The client timed out after
18517 5 seconds ("c----").
18518
18519 >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \
18520 px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \
Willy Tarreaud72758d2010-01-12 10:42:19 +010018521 0/0 "HEAD / HTTP/1.0"
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018522
18523 => The request took 3s to complete (probably a network problem), and the
Willy Tarreauc57f0e22009-05-10 13:12:33 +020018524 connection to the server failed ('SC--') after 4 attempts of 2 seconds
Willy Tarreaucc6c8912009-02-22 10:53:55 +010018525 (config says 'retries 3'), and no redispatch (otherwise we would have
18526 seen "/+3"). Status code 503 was returned to the client. There were 115
18527 connections on this server, 202 connections on this proxy, and 205 on
18528 the global process. It is possible that the server refused the
18529 connection because of too many already established.
Willy Tarreau844e3c52008-01-11 16:28:18 +010018530
Willy Tarreau52b2d222011-09-07 23:48:48 +020018531
Christopher Fauletc3fe5332016-04-07 15:30:10 +0200185329. Supported filters
18533--------------------
18534
18535Here are listed officially supported filters with the list of parameters they
18536accept. Depending on compile options, some of these filters might be
18537unavailable. The list of available filters is reported in haproxy -vv.
18538
18539See also : "filter"
18540
185419.1. Trace
18542----------
18543
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010018544filter trace [name <name>] [random-parsing] [random-forwarding] [hexdump]
Christopher Fauletc3fe5332016-04-07 15:30:10 +020018545
18546 Arguments:
18547 <name> is an arbitrary name that will be reported in
18548 messages. If no name is provided, "TRACE" is used.
18549
18550 <random-parsing> enables the random parsing of data exchanged between
18551 the client and the server. By default, this filter
18552 parses all available data. With this parameter, it
18553 only parses a random amount of the available data.
18554
Davor Ocelice9ed2812017-12-25 17:49:28 +010018555 <random-forwarding> enables the random forwarding of parsed data. By
Christopher Fauletc3fe5332016-04-07 15:30:10 +020018556 default, this filter forwards all previously parsed
18557 data. With this parameter, it only forwards a random
18558 amount of the parsed data.
18559
Davor Ocelice9ed2812017-12-25 17:49:28 +010018560 <hexdump> dumps all forwarded data to the server and the client.
Christopher Faulet31bfe1f2016-12-09 17:42:38 +010018561
Christopher Fauletc3fe5332016-04-07 15:30:10 +020018562This filter can be used as a base to develop new filters. It defines all
18563callbacks and print a message on the standard error stream (stderr) with useful
18564information for all of them. It may be useful to debug the activity of other
18565filters or, quite simply, HAProxy's activity.
18566
18567Using <random-parsing> and/or <random-forwarding> parameters is a good way to
18568tests the behavior of a filter that parses data exchanged between a client and
18569a server by adding some latencies in the processing.
18570
18571
185729.2. HTTP compression
18573---------------------
18574
18575filter compression
18576
18577The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
18578keyword must still be used to enable and configure the HTTP compression. And
Christopher Faulet27d93c32018-12-15 22:32:02 +010018579when no other filter is used, it is enough. When used with the cache enabled,
18580it is also enough. In this case, the compression is always done after the
18581response is stored in the cache. But it is mandatory to explicitly use a filter
18582line to enable the HTTP compression when at least one filter other than the
18583cache is used for the same listener/frontend/backend. This is important to know
18584the filters evaluation order.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020018585
Christopher Faulet27d93c32018-12-15 22:32:02 +010018586See also : "compression" and section 9.4 about the cache filter.
Christopher Fauletc3fe5332016-04-07 15:30:10 +020018587
18588
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200185899.3. Stream Processing Offload Engine (SPOE)
18590--------------------------------------------
18591
18592filter spoe [engine <name>] config <file>
18593
18594 Arguments :
18595
18596 <name> is the engine name that will be used to find the right scope in
18597 the configuration file. If not provided, all the file will be
18598 parsed.
18599
18600 <file> is the path of the engine configuration file. This file can
18601 contain configuration of several engines. In this case, each
18602 part must be placed in its own scope.
18603
18604The Stream Processing Offload Engine (SPOE) is a filter communicating with
18605external components. It allows the offload of some specifics processing on the
Davor Ocelice9ed2812017-12-25 17:49:28 +010018606streams in tiered applications. These external components and information
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020018607exchanged with them are configured in dedicated files, for the main part. It
18608also requires dedicated backends, defined in HAProxy configuration.
18609
18610SPOE communicates with external components using an in-house binary protocol,
18611the Stream Processing Offload Protocol (SPOP).
18612
Tim Düsterhus4896c442016-11-29 02:15:19 +010018613For all information about the SPOE configuration and the SPOP specification, see
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020018614"doc/SPOE.txt".
18615
18616Important note:
18617 The SPOE filter is highly experimental for now and was not heavily
18618 tested. It is really not production ready. So use it carefully.
18619
Christopher Faulet99a17a22018-12-11 09:18:27 +0100186209.4. Cache
18621----------
18622
18623filter cache <name>
18624
18625 Arguments :
18626
18627 <name> is name of the cache section this filter will use.
18628
18629The cache uses a filter to store cacheable responses. The HTTP rules
18630"cache-store" and "cache-use" must be used to define how and when to use a
John Roesler27c754c2019-07-10 15:45:51 -050018631cache. By default the corresponding filter is implicitly defined. And when no
Christopher Faulet27d93c32018-12-15 22:32:02 +010018632other filters than cache or compression are used, it is enough. In such case,
18633the compression filter is always evaluated after the cache filter. But it is
18634mandatory to explicitly use a filter line to use a cache when at least one
18635filter other than the compression is used for the same
18636listener/frontend/backend. This is important to know the filters evaluation
18637order.
Christopher Faulet99a17a22018-12-11 09:18:27 +010018638
Christopher Faulet27d93c32018-12-15 22:32:02 +010018639See also : section 9.2 about the compression filter and section 10 about cache.
Christopher Faulet99a17a22018-12-11 09:18:27 +010018640
William Lallemand86d0df02017-11-24 21:36:45 +01001864110. Cache
18642---------
18643
18644HAProxy provides a cache, which was designed to perform cache on small objects
18645(favicon, css...). This is a minimalist low-maintenance cache which runs in
18646RAM.
18647
18648The cache is based on a memory which is shared between processes and threads,
Cyril Bonté7b888f12017-11-26 22:24:31 +010018649this memory is split in blocks of 1k.
William Lallemand86d0df02017-11-24 21:36:45 +010018650
18651If an object is not used anymore, it can be deleted to store a new object
18652independently of its expiration date. The oldest objects are deleted first
18653when we try to allocate a new one.
18654
Cyril Bonté7b888f12017-11-26 22:24:31 +010018655The cache uses a hash of the host header and the URI as the key.
William Lallemand86d0df02017-11-24 21:36:45 +010018656
18657It's possible to view the status of a cache using the Unix socket command
18658"show cache" consult section 9.3 "Unix Socket commands" of Management Guide
18659for more details.
18660
18661When an object is delivered from the cache, the server name in the log is
18662replaced by "<CACHE>".
18663
Cyril Bonté7b888f12017-11-26 22:24:31 +01001866410.1. Limitation
18665----------------
William Lallemand86d0df02017-11-24 21:36:45 +010018666
18667The cache won't store and won't deliver objects in these cases:
18668
18669- If the response is not a 200
18670- If the response contains a Vary header
Frédéric Lécaille5f8bea62018-10-23 10:09:19 +020018671- If the Content-Length + the headers size is greater than "max-object-size"
William Lallemand86d0df02017-11-24 21:36:45 +010018672- If the response is not cacheable
18673
18674- If the request is not a GET
18675- If the HTTP version of the request is smaller than 1.1
William Lallemand8a16fe02018-05-22 11:04:33 +020018676- If the request contains an Authorization header
William Lallemand86d0df02017-11-24 21:36:45 +010018677
Christopher Faulet99a17a22018-12-11 09:18:27 +010018678Caution!: For HAProxy version prior to 1.9, due to the limitation of the
18679filters, it is not recommended to use the cache with other filters. Using them
18680can cause undefined behavior if they modify the response (compression for
18681example). For HAProxy 1.9 and greater, it is safe, for HTX proxies only (see
18682"option http-use-htx" for details).
William Lallemand86d0df02017-11-24 21:36:45 +010018683
Cyril Bonté7b888f12017-11-26 22:24:31 +01001868410.2. Setup
18685-----------
William Lallemand86d0df02017-11-24 21:36:45 +010018686
18687To setup a cache, you must define a cache section and use it in a proxy with
18688the corresponding http-request and response actions.
18689
Cyril Bonté7b888f12017-11-26 22:24:31 +01001869010.2.1. Cache section
18691---------------------
William Lallemand86d0df02017-11-24 21:36:45 +010018692
18693cache <name>
18694 Declare a cache section, allocate a shared cache memory named <name>, the
18695 size of cache is mandatory.
18696
18697total-max-size <megabytes>
Davor Ocelice9ed2812017-12-25 17:49:28 +010018698 Define the size in RAM of the cache in megabytes. This size is split in
Frédéric Lécaillee3c83d82018-10-25 10:46:40 +020018699 blocks of 1kB which are used by the cache entries. Its maximum value is 4095.
William Lallemand86d0df02017-11-24 21:36:45 +010018700
Frédéric Lécaille5f8bea62018-10-23 10:09:19 +020018701max-object-size <bytes>
Frédéric Lécaillee3c83d82018-10-25 10:46:40 +020018702 Define the maximum size of the objects to be cached. Must not be greater than
18703 an half of "total-max-size". If not set, it equals to a 256th of the cache size.
18704 All objects with sizes larger than "max-object-size" will not be cached.
Frédéric Lécaille5f8bea62018-10-23 10:09:19 +020018705
William Lallemand86d0df02017-11-24 21:36:45 +010018706max-age <seconds>
18707 Define the maximum expiration duration. The expiration is set has the lowest
18708 value between the s-maxage or max-age (in this order) directive in the
18709 Cache-Control response header and this value. The default value is 60
18710 seconds, which means that you can't cache an object more than 60 seconds by
18711 default.
18712
Cyril Bonté7b888f12017-11-26 22:24:31 +01001871310.2.2. Proxy section
18714---------------------
William Lallemand86d0df02017-11-24 21:36:45 +010018715
Jarno Huuskonen251a6b72019-01-04 14:05:02 +020018716http-request cache-use <name> [ { if | unless } <condition> ]
William Lallemand86d0df02017-11-24 21:36:45 +010018717 Try to deliver a cached object from the cache <name>. This directive is also
18718 mandatory to store the cache as it calculates the cache hash. If you want to
18719 use a condition for both storage and delivering that's a good idea to put it
18720 after this one.
18721
Jarno Huuskonen251a6b72019-01-04 14:05:02 +020018722http-response cache-store <name> [ { if | unless } <condition> ]
William Lallemand86d0df02017-11-24 21:36:45 +010018723 Store an http-response within the cache. The storage of the response headers
18724 is done at this step, which means you can use others http-response actions
18725 to modify headers before or after the storage of the response. This action
18726 is responsible for the setup of the cache storage filter.
18727
18728
18729Example:
18730
18731 backend bck1
18732 mode http
18733
18734 http-request cache-use foobar
18735 http-response cache-store foobar
18736 server srv1 127.0.0.1:80
18737
18738 cache foobar
18739 total-max-size 4
18740 max-age 240
18741
Willy Tarreau0ba27502007-12-24 16:55:16 +010018742/*
18743 * Local variables:
18744 * fill-column: 79
18745 * End:
18746 */